clawmates/deploy/compose

Clawmates on Docker Compose

A single-node deployment of the whole platform — the same images the Kubernetes/Helm path uses, with the same §15 security topology. This is the air-gapped appliance route; it is equally usable as a simple self-host.

What runs

Service	Role
postgres	database (named volume pgdata)
broker	the secret broker — credentials never leave it; reachable only over a private socket volume shared with the server
socket-proxy	allow-listed Docker API so the server can spawn agent sandboxes and nothing else
server	API + streaming gateway + agent runtime + scheduler
frontend	the Next.js web app

Networks core, secrets_net, sandbox_net, and engine_net are all internal: true; only edge is published. Agent sandboxes run with no network at all (egress is the browser container's alone).

Quick start

cd deploy/compose
cp .env.example .env
# Edit .env: set POSTGRES_PASSWORD and CLAWMATES_BOOTSTRAP_OWNER_PASSWORD.

# Either build the images locally...
docker compose build
# ...or load them from a signed release bundle (see deploy/airgapped/install.sh).

docker compose up -d

The server self-migrates on boot and, if CLAWMATES_BOOTSTRAP_OWNER_PASSWORD is set, provisions the first Owner + workspace once (a no-op on every later boot). Then open:

• App → http://localhost:3000
• Sign in with CLAWMATES_BOOTSTRAP_OWNER_EMAIL / …_PASSWORD.
• API health → http://localhost:8080/healthz

Configuration

Host- and secret-specific values come from .env (overlaid onto clawmates.toml at runtime — CLAWMATES_* env always wins). The knobs:

Concern	Where	Notes
DB password	.env POSTGRES_PASSWORD	also forms the server/broker DSN
Image tag	.env CLAWMATES_VERSION	latest after a local build, or a release version
First owner	.env CLAWMATES_BOOTSTRAP_*	password set = bootstrap on first boot
LLM	clawmates.toml [llm]	openai_compat (default, point base_url at vLLM/Ollama/llama.cpp) or anthropic (+ ANTHROPIC_API_KEY in .env)
Auth	clawmates.toml [auth] + .env AUTH_MODE	local (default) or clerk (see docs/clerk.md)
Tracing	.env CLAWMATES_TELEMETRY__OTLP_ENDPOINT	unset = logs only, no egress

Using Anthropic instead of a local model

In clawmates.toml:

[llm]
provider = "anthropic"
model = "claude-sonnet-4-6"

and set ANTHROPIC_API_KEY in .env.

The broker master key — back it up

On first boot the broker generates its encryption key into the broker_key volume and logs a reminder. Every stored credential is unrecoverable without it. Back it up:

docker compose cp broker:/etc/clawmates-broker/broker.key ./broker.key.backup

Operations

docker compose ps                 # status
docker compose logs -f server     # follow server logs
docker compose pull && docker compose up -d   # upgrade to a new CLAWMATES_VERSION
docker compose down               # stop (keeps volumes/data)
docker compose down -v            # stop AND delete all data

Production notes

• Put a TLS-terminating reverse proxy in front of ports 3000/8080; the SSE gateway needs response buffering off (the Helm ingress sets this; nginx: proxy_buffering off; with long read timeouts).
• socket-proxy mounts the Docker socket read-only and exposes only the container lifecycle verbs — verified by crates/cm-sandbox/tests/socket_proxy.rs.
• The full bring-up is exercised end to end by scripts/rehearse-install.sh (verify a signed bundle → docker load → compose up → assert the login page serves), which also runs in the release pipeline.