adapter

adapter

See Runtime adapter stack for the end-to-end topology, trust boundaries, startup order, and failure signals for adapter serve, adapter ingress, and adapter connect.

crabbox adapter serve exposes a small authenticated HTTP service that creates and stops Crabbox workspaces. It is intended for a trusted fleet UI or automation service that should use normal Crabbox provider configuration rather than embed provider-specific lifecycle logic.

The adapter host must run Linux or macOS. adapter serve exits with a clear unsupported-platform error on every other host OS. Windows workspaces remain supported as guests through providers that support them.

install -d -m 700 "$HOME/.local/run/crabbox"
crabbox adapter serve \
  --listen 127.0.0.1:8787 \
  --unix-socket "$HOME/.local/run/crabbox/adapter.sock" \
  --token-file ~/.config/crabbox/adapter.token \
  --state-file ~/.local/state/crabbox/adapter/state.json \
  --config ~/.config/crabbox/adapter.yaml \
  --provider external \
  --id mac-lab \
  --profile public-desktop \
  --forbid-class-override \
  --forbid-server-type-override \
  --max-concurrent 2 \
  --allow-desktop \
  --allow-browser \
  --attach-url-template 'wss://terminal.example.test/workspaces/{workspaceId}'

The listen address defaults to 127.0.0.1:8787. Put the service behind an authenticated HTTPS proxy before exposing it beyond loopback. The token file is required, must be a regular non-symlink file with mode 0600, and contains one bearer token. The adapter opens it once with no-follow semantics, validates that handle, and bounds the read to 8 KiB. Tokens are never accepted on argv. The state directory must be owned by the current user and not writable by group or others. The exclusive lock is opened relative to that verified directory with no-follow semantics, then its exact descriptor is checked for ownership, type, and private mode before the kernel lock is acquired.

--unix-socket adds a second listener for adapter connect; it does not replace --listen. Its existing parent directory must be owned by the current user and not writable by group or others. The adapter refuses to replace a foreign or non-socket path, removes only a stale current-user-owned socket, and installs the live socket with mode 0600. The outbound connector accepts only this Unix transport and verifies the server peer UID before sending the local bearer token.

Set --id to the same stable DNS-style ID used by crabbox adapter connect when the adapter is connected outbound to a coordinator. Child lifecycle commands then register both that adapter ID and the exact workspace ID with the coordinator. The portal can send Delete through the live relay. After the adapter proves stable provider absence, it sends an owner-scoped completion for that exact pending adapter/workspace registration generation before completing matching local-state cleanup. Each local claim persists a fresh registration ID; the coordinator retains it across refreshes and rejects stale completion retries after a later generation becomes active. If the coordinator record expires while the provider workspace remains live, the CLI rotates the persisted ID only after that explicit stale-generation rejection and retries registration. The old acknowledged ID remains durable beside the pending replacement until the replacement succeeds; confirmed-absence cleanup can safely try both after a crash or lost response. A workspace that never persisted a registration ID uses the legacy metadata-release cleanup path only after the coordinator confirms that its exact adapter/workspace binding also has no registration generation. Missing or malformed generation-aware claim state fails closed. Registration must return that exact adapter/workspace/registration binding before the workspace can become ready; a failed or mismatched registration instead enters exact-identity provider cleanup. Without --id, registered leases retain the metadata-only removal behavior.