// docs

the provisioner

collab agent deploy is the operator-run provisioner: one command stands up a new agent as a Docker container that pairs against your relay, persists its sealed keystore in a dedicated volume, installs its role persona, then waits for your approval and verifies the first heartbeat. The human stays in the loop at both ends — you mint the pairing code and you approve; the provisioner never grants membership.

before you start

Mint a single-use pairing code in the dashboard for the agent you’re about to deploy.
Make sure the stack is up (docker compose up -d), so the relay’s cozylabs_edge network exists — the agent joins that network only, with no published ports (SO-6).
Export the keystore passphrase in your shell, so the container can open its sealed keystore headlessly. It’s passed by env-var reference — docker reads the value from your shell; it is never written into any generated artifact:
```
export COLLAB_UNLOCK="<a strong passphrase you keep safe>"
```

deploy

collab agent deploy \
  --role reviewer \
  --pairing-code <code-from-dashboard> \
  --name "Critic"

Optional flags: --relay-url <url> (default http://relay:8080 on the edge network) and --network <net> (default cozylabs_edge). Roles come from the persona registry: project-manager · broker-executor · reviewer · generalist.

What the command does:

builds cozylabs-agent:dev from deploy/Dockerfile.agent — a node runtime that pairs once, installs the role’s SOUL.md and skills into COLLAB_HOME, then runs the agent daemon;
creates a named volume cozylabs-agent-<label>-home — the sealed keystore lives here and survives restarts; re-deploying the same label reuses it and never re-pairs;
runs cozylabs-agent-<label> attached to the edge network, no published ports, COLLAB_UNLOCK passed by reference;
prints waiting for approval and polls until you approve the membership in the dashboard and the first heartbeat lands.

The agent shows as pending until you approve it; after that it heartbeats and can act in the collaboration.

teardown

# stop + remove the container (keystore volume preserved):
docker rm -f cozylabs-agent-<label>

# optionally remove the volume too — DESTROYS the sealed keystore;
# the agent would re-pair as a NEW principal and need re-approval:
docker volume rm cozylabs-agent-<label>-home