clawkerd

Overview ¶

Command clawkerd is the per-container agent daemon. It runs as PID 1 of the agent container, owns the per-container ClawkerdService listener that the CP dials for command dispatch, and supervises the user CMD across its lifetime.

Boot sequence:

1. Read bootstrap material delivered by the CLI to consts.BootstrapDir (cert.pem, key.pem, ca.pem, assertion.jwt). cert/key/ca are loaded into the listener's TLS config; the assertion JWT is held in memory for the CP-driven Register handshake (clawkerd exchanges it at Hydra for an access token when CP sends RegisterRequired on the Session stream).
2. Start the ClawkerdService mTLS listener on consts.DefaultClawkerdPort. The listener pins peer CN to consts.ContainerCP so no other agent's CA-signed cert can connect.
3. Resolve the unprivileged container user via $CLAWKER_USER and /etc/passwd; build the spawn state but do NOT spawn yet — handleAgentReady triggers the spawn when CP-driven init completes. Privilege drop happens in the child via SysProcAttr.Credential; clawkerd stays root.
4. Wait for either ctx.Done (SIGTERM/SIGINT) or main child exit. On SIGTERM: forward to the child pgroup, escalate to SIGKILL after grace, then Stop (force-close) the listener and drain reparented orphans. On main exit: Stop first so in-flight session.go pipelines see a closed listener before the reaper transitions to Wait4(-1) — see spawnState's reaper phasing. Exit with the child's bash-convention exit code so Docker's restart-on-failure machinery sees the right value.

Identity / registration: clawkerd performs a one-time, CP-driven Register call when CP sends a RegisterRequired Command on the Session stream. clawkerd exchanges the CLI-signed client_assertion JWT at Hydra for an access token, mTLS-dials CP's AgentService, and calls Register. CP captures the live mTLS peer's cert thumbprint at handler entry and writes the (thumbprint, container_id) row into agentregistry. The assertion is single-use; subsequent Sessions for the same container observe an existing registry row and skip Register.