Runtime adapter stack

Crabbox can sit behind a fleet UI without teaching that UI how each provider creates, inspects, or deletes a workspace. Three crabbox adapter processes split the job into a provider lifecycle API, an authenticated browser ingress, and an optional outbound coordinator connection.

Use this stack when:

• a browser-facing service needs to create and stop Crabbox workspaces;
• the provider host should remain on loopback or behind NAT;
• browser identity and TLS terminate at an existing trusted proxy; and
• provider credentials must stay on the adapter host.

It is not a general reverse proxy, identity provider, WAF, or remote shell.

#Components

The fleet UI and provider adapter are deployment choices. The three adapter commands are reusable Crabbox building blocks.

#Topology

browser
   |
   | HTTPS
   v
trusted identity-aware proxy
   |
   | exact identity + secret assertions
   v
adapter ingress
   |
   | sanitized HTTP / WebSocket on loopback
   v
fleet UI ---------------------> adapter serve ----------------> provider
                                      ^
                                      | private Unix socket
                                      |
coordinator <--- outbound WSS --- adapter connect

The browser path and coordinator path are independent. adapter ingress protects the fleet UI. adapter connect lets a coordinator reach the lifecycle API without opening an inbound route to adapter serve.

#Request paths

#Browser traffic

1. The trusted proxy authenticates the browser and terminates TLS.
2. The proxy sends exactly one configured identity header and one configured

secret header to adapter ingress.

3. adapter ingress rejects denied routes before authentication, checks the

assertions and request origin, removes unsafe forwarding and private headers, then installs the configured upstream assertions.

4. The request reaches the loopback fleet UI. Streaming responses and valid

WebSocket upgrades remain streaming end to end.

The proxy is responsible for user authentication and TLS. adapter ingress trusts only the configured assertion pair; it does not validate browser login sessions itself.

#Workspace lifecycle

1. The fleet UI sends a bearer-authenticated request to adapter serve.
2. adapter serve validates the fixed deployment policy, persists lifecycle

state, and invokes the configured provider.

3. The provider returns a workspace identity and connection metadata.
4. Later reads and deletes resolve the persisted workspace record rather than

accepting arbitrary provider commands from the request.

The API exposes workspace operations, not shell commands, argv, environment, files, or provider credentials. Keep the bearer token between the fleet UI and adapter serve private.

#Outbound coordinator control

1. adapter connect authenticates to the coordinator using normal Crabbox

configuration and obtains a short-lived relay ticket. A new adapter ID starts with a ten-minute provisional owner/org claim; agent connection or successful lease registration makes it durable. Only expired inactive provisional claims are recoverable, and existing adapter claims remain durable across upgrades.

2. It opens an outbound WebSocket and accepts only the documented typed

workspace operations.

3. Each operation is forwarded through the verified, current-user-owned Unix

socket to adapter serve with the local bearer token.

4. The local token, remote cookies, and proxy credentials never cross the

relay.

The relay is optional. Omit it when only the local fleet UI needs lifecycle access.

#Trust boundaries

Do not reuse one secret across boundaries. In particular, the proxy secret, adapter bearer token, and coordinator credential serve different principals and rotation paths.

#Configuration and rotation

• Keep the adapter serve token, state, and Unix-socket parent in

current-user-owned private paths.

• Keep the adapter ingress JSON config and secret as current-user-owned

regular files with mode 0400 or 0600.

• Use one literal listener IP, one exact loopback HTTP upstream, and one exact

non-loopback HTTPS public origin for ingress.

• Bind the fleet UI and adapter serve to loopback. The trusted proxy should be

the only peer that can reach the ingress listener.

• Restart adapter ingress after rotating its config or proxy secret; both are

loaded when the process starts.

• adapter connect reloads normal Crabbox config and its local token file when

reconnecting. It also reloads the local token before each forwarded request.

#Start and stop order

Recommended startup:

1. Start adapter serve and wait for its loopback health check.
2. Start the fleet UI and verify it can reach the lifecycle API.
3. Start adapter ingress behind the trusted proxy.
4. Optionally start adapter connect and verify coordinator registration.
5. Expose the trusted proxy route only after every required health check passes.

Shutdown in reverse. Remove or disable the public proxy route first, stop the outbound connector, stop the fleet UI, then stop adapter serve. This prevents new browser or coordinator work from arriving while lifecycle state is being quiesced.

#Health and failure signals

Treat a healthy process as one layer of evidence, not proof of the full path. For a deployment smoke test, verify an authenticated browser request, one workspace lifecycle operation, and the outbound coordinator path when enabled.

#Related reference

• adapter command: complete flags, config schema,

API, relay protocol, and file-safety requirements.

• Broker auth and routing: coordinator and portal

authentication models.

• Security: repository-wide trust and secret boundaries.