Read this when you are standing up a shared broker, deciding what secrets to forward, or reasoning about who can reach a leased box.

Crabbox spans three trust layers, and each owns a different part of the security posture:

local CLI -> coordinator (Cloudflare or Node/PostgreSQL) -> provider VM

The CLI owns local config, per-lease SSH keys, sync, and remote command execution. The coordinator owns authentication, authorization, lease state, provider credentials, cost guardrails, and cleanup. Providers own VM creation, network reachability, and deletion. Delegated-run providers such as Docker Sandbox also own the command transport and runtime that receive commands and explicitly forwarded environment values.

Crabbox is built for trusted operators on a shared team, not for arbitrary untrusted tenants. Assume:

• Operators can run arbitrary commands on the boxes they lease.
• A box may observe any local environment value the CLI forwards to it.
• Operators are trusted not to attack each other deliberately.
• Bugs and crashes still happen, so cleanup must be defensive and idempotent.

Do not place mutually untrusted tenants on the same broker, in the same pond, or behind a single shared token. Per-lease and per-tenant isolation is not the current security boundary.

Every non-health route normally requires a Bearer token; requests without one are rejected 401 unauthorized. The Node runtime can instead accept an explicitly configured trusted reverse-proxy identity from allowlisted peer CIDRs. The generally unauthenticated routes are GET /v1/health, the GitHub login/OAuth and portal login/logout routes, and bridge agent upgrades that use short-lived tickets. The /v1/workspaces route tree also accepts the dedicated CRABBOX_RUNTIME_ADAPTER_TOKEN as a non-admin service@openclaw.org identity; that credential is rejected from every other coordinator route. Normal authentication is resolved in worker/src/auth.ts in this precedence:

1. Admin token — the request token equals the coordinator secret CRABBOX_ADMIN_TOKEN. Grants admin scope.
2. Shared operator token — the token equals CRABBOX_SHARED_TOKEN. Grants a non-admin shared identity for automation.
3. Signed user token — a cbxu_-prefixed token issued by GitHub browser login. It is an HMAC-SHA256 signature (verified in constant time) over a base64url payload signed with CRABBOX_SESSION_SECRET (falling back to CRABBOX_SHARED_TOKEN). The payload carries owner, org, and GitHub login, has a default 180-day expiry, and is rejected if it carries an admin claim — browser login can never mint admin tokens.

crabbox login --url <broker-url> opens a GitHub OAuth flow and stores the returned signed user token in local config. Authorization during login is gated by coordinator config:

• CRABBOX_GITHUB_ALLOWED_ORG / CRABBOX_GITHUB_ALLOWED_ORGS restrict login to members of the listed GitHub org(s).
• CRABBOX_GITHUB_ALLOWED_TEAMS (or CRABBOX_GITHUB_ALLOWED_TEAM) further narrows access to selected team slugs after org membership passes.

User tokens can only mutate leases, runs, and usage for their own owner/org identity. Lease owners also have read-only audit access to run history, logs, events, telemetry, and live event subscriptions for work recorded against their leases, including runs that later replace the active backing lease. See auth and admin and broker auth routing for the full flow.

Cloudflare Access can sit in front of a custom broker hostname (for example broker.example.com) as an edge layer. It does not replace Crabbox auth: a request must clear Access at the edge and present a valid Crabbox token before any lease, run, log, usage, or admin route is reached.

The Worker never trusts raw Access identity headers. If it uses an Access-provided email, it first verifies the cf-access-jwt-assertion JWT (RS256, key fetched from https://<team-domain>/cdn-cgi/access/certs) against CRABBOX_ACCESS_TEAM_DOMAIN and CRABBOX_ACCESS_AUD, checking issuer, audience, and expiry. Before forwarding any request to the Fleet Durable Object, the Worker strips caller-supplied cf-access-authenticated-user-email and cf-access-jwt-assertion headers and injects its own derived identity (x-crabbox-auth, -admin, -owner, -org, -github-login).

The local service-token credentials CRABBOX_ACCESS_CLIENT_ID and CRABBOX_ACCESS_CLIENT_SECRET only satisfy the Access edge; they authorize no Crabbox action by themselves. Store them in user config or env, never in repo config.

The Node runtime can accept an identity header from an ingress:

CRABBOX_TRUSTED_USER_HEADER=X-Authenticated-User
CRABBOX_TRUSTED_USER_ORG=example-org
CRABBOX_TRUSTED_PROXY_CIDRS=10.42.7.19/32,fd00:1234::19/128
CRABBOX_TRUSTED_PROXY_SECRET=replace-with-a-random-secret

The socket peer must match the CIDR allowlist. The ingress must authenticate the caller and remove caller-supplied copies of the configured identity and X-Crabbox-Proxy-Secret headers. When CRABBOX_TRUSTED_PROXY_SECRET is set, the ingress must send that value in X-Crabbox-Proxy-Secret; the coordinator strips it before routing the request. Allow only exact proxy addresses or dedicated subnets, or require the secret when direct access cannot be blocked. This path grants non-admin scope only; keep CRABBOX_ADMIN_TOKEN separate. The same proxy allowlist controls whether forwarded host, protocol, and client-IP headers affect URL construction and provider ingress rules.

X-Crabbox-Proxy-Secret is reserved and cannot be used as CRABBOX_TRUSTED_USER_HEADER.

There are three effective roles:

user        acquire/heartbeat/release own leases; read own and owned-lease run audit data
operator    shared automation identity via a shared bearer token
admin       view all leases/runs/pool/usage; drain/delete machines; image lifecycle

Admin scope comes from CRABBOX_ADMIN_TOKEN, or from a signed GitHub user token whose verified email or login matches CRABBOX_GITHUB_ADMIN_OWNERS or CRABBOX_GITHUB_ADMIN_LOGINS. Locally, admin commands can still send the admin bearer via CRABBOX_COORDINATOR_ADMIN_TOKEN or broker.adminToken. Shared-operator requests do not trust caller-supplied X-Crabbox-Owner / X-Crabbox-Org headers — pin that automation's identity with CRABBOX_SHARED_OWNER (and CRABBOX_DEFAULT_ORG), or prefer per-user signed tokens / verified Access identity instead. Missing shared-token config fails closed for non-health routes.

There is no central project secret store. Secrets stay on the operator's machine and are forwarded to a box only when explicitly allowed.

Handling rules:

• The CLI forwards environment variables only by allowlist. The default allow list is CI and NODE_OPTIONS; extend it with repo-local env.allow config (or a profile's env.allow).
• Never pass a secret value as a command-line flag.
• Never log environment values; redact secret-looking strings in diagnostics.
• Treat delegated-run providers as part of the runtime trust boundary: when you allow a variable for a Docker Sandbox run, Docker Sandbox receives that value through its sbx exec --env-file path even though Crabbox keeps the value out of local process arguments.
• User config files are written 0600. crabbox doctor flags any local config whose permissions are broader, because broker tokens may live there.

Example env.allow in .crabbox.yaml:

env:
  allow:
    - CI
    - NODE_OPTIONS
    - PROJECT_*

See environment forwarding for matching and profile behavior.

Inject these as Cloudflare Worker secrets or Node service secrets, never in the repo:

• CRABBOX_ADMIN_TOKEN — admin and image-lifecycle routes.
• CRABBOX_RUNTIME_ADAPTER_TOKEN — route-scoped service access to the /v1/workspaces lifecycle API only.
• CRABBOX_SHARED_TOKEN — trusted operator automation; also the fallback signing key when CRABBOX_SESSION_SECRET is unset.
• CRABBOX_GITHUB_CLIENT_ID, CRABBOX_GITHUB_CLIENT_SECRET, CRABBOX_SESSION_SECRET — GitHub browser login and user-token signing.
• CRABBOX_GITHUB_ADMIN_OWNERS, CRABBOX_GITHUB_ADMIN_LOGINS — optional comma-separated GitHub verified emails and logins whose user tokens become admin at request time; set these per deployment, not in the reusable repo config.
• CRABBOX_TAILSCALE_CLIENT_ID, CRABBOX_TAILSCALE_CLIENT_SECRET — minting one-off Tailscale auth keys for brokered --tailscale leases.
• CRABBOX_ARTIFACTS_ACCESS_KEY_ID, CRABBOX_ARTIFACTS_SECRET_ACCESS_KEY, and optional CRABBOX_ARTIFACTS_SESSION_TOKEN — brokered artifact publishing. Scope these to the artifact bucket/prefix and use them only to sign short-lived upload/read URLs.

Coordinator config values (not secret material):

• CRABBOX_GITHUB_ALLOWED_ORG(S), CRABBOX_GITHUB_ALLOWED_TEAMS — browser-login authorization.
• CRABBOX_TAILSCALE_TAGS — allowlist/default for requested Tailscale ACL tags. Do not allow arbitrary user-supplied tags.
• CRABBOX_ACCESS_TEAM_DOMAIN, CRABBOX_ACCESS_AUD — Access JWT verification.
• CRABBOX_ARTIFACTS_BACKEND, CRABBOX_ARTIFACTS_BUCKET, CRABBOX_ARTIFACTS_PREFIX, CRABBOX_ARTIFACTS_BASE_URL, CRABBOX_ARTIFACTS_REGION, CRABBOX_ARTIFACTS_ENDPOINT_URL, CRABBOX_ARTIFACTS_UPLOAD_EXPIRES_SECONDS, CRABBOX_ARTIFACTS_URL_EXPIRES_SECONDS — artifact storage settings.

Local-only direct-provider secret: CRABBOX_TAILSCALE_AUTH_KEY. Do not forward it to commands, print it, or store it in repo config.

SSH is the control and data path to a leased box; the broker manages leases but never proxies SSH traffic. The posture:

• Key-only authentication. No password login, no root login.
• A dedicated crabbox user; work happens under the platform work root (/work/crabbox on Linux).
• The CLI generates a per-lease key under the user config directory (<user-config>/crabbox/testboxes/<lease-id>/id_ed25519; RSA for AWS/Azure Windows). Matching cloud key pairs are removed when Crabbox deletes the box. See SSH keys.
• SSH listens on the configured primary port (default 2222) plus configured fallback ports (default 22), because port 22 is not reliably reachable from every operator network.
• AWS security groups use CRABBOX_AWS_SSH_CIDRS when set. Brokered leases otherwise scope ingress to the CLI-detected outbound IPv4 CIDR, falling back to the Cloudflare request source IP for the lease. Hetzner direct mode relies on provider firewall defaults unless a profile tightens them.
• Machines are disposable and cleanable; boot-time cleanup clears stale work-root directories.

Tailscale does not change this model. Crabbox still uses OpenSSH, per-lease keys, scoped known_hosts, SSH tunnels, lease expiry, and cleanup — Tailscale only changes which host the SSH client dials.

Hardening worth applying before first shared use:

• Keep long-lived operator keys out of machine images.
• Restrict provider firewalls to known callers where practical.
• Treat profiles that forward secrets as higher risk, and prefer ephemeral machines for them.

Ponds are a trusted-operator surface. A pond is a lease grouping plus transport metadata, not an isolation boundary.

• With --tailscale on a direct, Tailscale-capable provider, the local CLI may add a tag:cbx-pond-<owner>-<pond> tag owner and a same-tag allow rule to the operator's tailnet policy — but only when both TS_API_KEY and CRABBOX_POND_ACL_BOOTSTRAP=1 are set. TS_API_KEY alone enables read-only doctor --pond verification. The broker never receives the Tailscale API key.
• Brokered leases keep using the coordinator's CRABBOX_TAILSCALE_TAGS allowlist and do not receive generated tag:cbx-pond-* tags. Admins who want brokered tailnet reachability must configure and review that policy explicitly.

Security notes:

• Same-pond Tailscale members can reach each other by default once the policy row exists. Do not share a pond across mutually untrusted tenants.
• URL-bridge peers expose only provider-native HTTP(S) ingress, not arbitrary TCP/UDP reachability into the tailnet.
• The SSH-mesh is operator-side ssh -L forwarding; it does not create lease-to-lease networking.
• Removing a pond does not prune historical Tailscale policy rows. Audit and remove stale tag:cbx-pond-* entries when rotating preview environments.

Managed VNC stays tunnel-only even on Tailscale-enabled leases. Do not bind Crabbox-managed VNC to public interfaces or to the Tailscale 100.x interface.

Cleanup is security-sensitive: a leaked box keeps spending money and stays reachable. See lifecycle and cleanup.

Layered protections:

• A lease TTL cap and an idle timeout enforced against a heartbeat/touch deadline.
• Explicit release (crabbox stop / release).
• A Durable Object alarm or pg-boss job that expires leases and reschedules the next pending deadline, plus periodic reconciliation.
• A coordinator-side AWS orphan sweep over current broker credentials and capacity regions.
• A provider-label sweep for clearly expired, inactive orphan machines.

In direct-CLI mode, cleanup runs from the CLI using provider labels: it skips keep machines, deletes expired ready/leased/active machines, and only removes running/provisioning machines after an extra stale-safety window. When a coordinator is configured, provider-side cleanup is disabled — the coordinator scheduler owns brokered cleanup.

The brokered AWS orphan sweep treats live coordinator lease state as the authority and only acts on provider tags after a matching active lease is absent or points at a different cloud instance. It skips keep=true resources and applies a grace window before acting on missing labels or stale lease mappings.

Release is idempotent, and delete tolerates already-deleted provider resources.

For AWS accounts, apply low-cost default-deny guardrails rather than relying on lease cleanup alone:

• Enable account-level S3 Block Public Access (all four settings). This applies across regions after propagation.
• Set an IAM account password policy when IAM users exist. Prefer SSO for human access; do not leave IAM user passwords on the AWS default policy.
• Create IAM Access Analyzer external-access analyzers in every region where Crabbox can allocate resources — external analyzers are regional, so one in the launch region does not cover the full capacity pool.

For a default brokered AWS capacity pool, run Access Analyzer in eu-west-1, eu-west-2, eu-central-1, us-east-1, and us-west-2. Review active findings before deleting trusts: SSO roles and deliberately scoped artifact-publishing roles can appear as expected cross-account access.

The coordinator stores only operational metadata:

• lease ID, owner identity, machine ID, profile;
• timestamps and state transitions;
• the command string, unless disabled.

The coordinator does not store unbounded logs, environment values, file contents, or SSH keys. Run records keep bounded stdout/stderr captures (chunked, with a stored cap) and optional structured JUnit summaries for debugging.

For binary or sensitive-by-format output, use crabbox run --capture-stdout <path> or --capture-stderr <path> so the stream is written to a local file and skipped by coordinator log/event capture. Failed SSH-backed and Blacksmith delegated runs write local failure bundles by default, and run --download remote=local keeps successful binary proof files local. Crabbox does not redact those local files — review them before sharing.

Durable Object run and lease records already provide operational history for debugging and cleanup (not compliance). A fuller event audit trail would record lease and machine lifecycle events such as:

lease.created
machine.provisioned
lease.heartbeat
lease.extended
lease.released
lease.expired
machine.drained
machine.deleted
provider.error