Sandbox Claude Inside

sandbox-claude-inside

Put Claude Code in the box, not the box on your machine. --with-claude runs the

CLI inside a host-FS-isolated ca-sandbox container, authenticating from an

env-injected token with no host bind of ~/.claude — the mechanism proven by

Spike B (.codearbiter/spikes/ca-sandbox-claude-auth.md, CONFIRM-07). It is the

deliberately-hardened lane: a token in a box is stealable, so the posture is locked

down by construction (offline or Anthropic-only egress, token volume never shared

with untrusted code), never left to operator discipline.

Pre-flight

Read these, or STOP and surface the gap — never guess the token source, the egress

posture, or the persistence mechanism:

• ${CLAUDE_PROJECT_DIR}/.codearbiter/spikes/ca-sandbox-claude-auth.md — the

proven auth path (env token → real 401 on a dummy), the named-volume HOME

persistence mechanism, and the load-bearing caveat that fixes the hard default.

• ${CLAUDE_PROJECT_DIR}/.codearbiter/spikes/ca-sandbox-egress.md — why the

egress allowlist is EXPERIMENTAL (CDN drift + DNS-exfil hole), so offline is

the only GUARANTEED posture for a token-bearing box.

• ${CLAUDE_PROJECT_DIR}/.codearbiter/decisions/0007-second-plugin-ca-sandbox.md

— the governing decision; ca-sandbox is infrastructure, sibling to ca.

The shipped driver is plugins/ca-sandbox/tools/claude-inside.js, its OWN

binary rather than a sandbox subcommand (#377):

node <plugin>/tools/claude-inside.js --image <tag> --home-volume <name> [--net offline|anthropic-only]

That separation IS the gate. A sandbox with-claude subcommand would let anyone

start a token-bearing box with one ungated command, which would turn the five

BLOCK phases below from enforcement into advice. This routine is the only

sanctioned caller.

The token MUST come from the approved store as CLAUDE_CODE_OAUTH_TOKEN, in the

ENVIRONMENT. The entry point refuses a --token flag outright: an argument list

is world-readable, so passing a credential there publishes it to every process

on the host. In tests use a DUMMY token only.

Sources: plugins/ca-sandbox/tools/claude-inside.ts

(buildClaudeImageDockerfile, buildClaudeRunArgs, runClaudeInside,

TokenCoMountRejectedError) and claude-inside-cli.ts (the entry).

Phase 1 — Posture · gate: BLOCK

Fix the egress posture and the trust boundary BEFORE anything is built or started.

A token-bearing box is the one place ca-sandbox's FS-isolation invariant and a live

credential are in direct tension — resolve it here, explicitly.

• Egress — choose exactly one: offline (default, GUARANTEED — no interface at

all) or anthropic-only (the EXPERIMENTAL Anthropic-domains allowlist, for

interactive inference). No third option exists; a wide-open policy is rejected.

• Trust boundary — the box runs Claude, NOT the untrusted source repo. Confirm

the run mounts only the token/home volume, never the source volume at

/work/repo. If the user wants Claude to read an untrusted repo, that is a

SEPARATE, source-only box without the token — say so.

Gate: a named egress posture (offline or anthropic-only) AND an explicit

statement that this box carries the token and NOT untrusted source. If the user

asks for both at once, STOP and split them — the co-mount is forbidden (Phase 4).

Phase 2 — Image · gate: BLOCK

Build (or reuse) the pinned --with-claude image via buildClaudeImageDockerfile.

• The image installs @anthropic-ai/claude-code@<pinned> — a PINNED semver,

never @latest — and bakes DISABLE_AUTOUPDATER=1 so the box never silently

pulls an unreviewed CLI into a token-bearing environment.

• The base is node:22-slim (Spike B installed the CLI cleanly there), bound to a

reviewed content DIGEST — node:22-slim@sha256:…, the CLAUDE_BASE_IMAGE

constant. The tag is kept only as human-readable provenance; docker resolves the

digest. This is the driver's highest-stakes pin: the base image's code runs in

the SAME container as CLAUDE_CODE_OAUTH_TOKEN, so a retag or registry

compromise would otherwise execute unreviewed code alongside a live credential.

Pinning the CLI version alone is not enough. HOME is baked to the in-container

claude home so the named volume has a writable mount point.

Gate: the image carries the exact pinned version (claude --version reports it),

DISABLE_AUTOUPDATER=1, and a digest-pinned base. A floating or unpinned CLI —

or an unpinned base image — fails the gate; image reproducibility is

non-negotiable for a token box. Changing the digest is a reviewed dependency

change: re-resolve it with docker buildx imagetools inspect, then re-run the

credential-boundary and isolation suites.

Phase 3 — Token · gate: BLOCK

Source the OAuth token and confirm it is injected as ENV, never bound from the host.

• The token comes from the approved secret store as CLAUDE_CODE_OAUTH_TOKEN

(auth-precedence #5, from claude setup-token). It is env-injected

(-e CLAUDE_CODE_OAUTH_TOKEN=…) — this IS the auth path; no host bind of

~/.claude is required or permitted.

• The token MUST NOT be echoed to logs, written to a file the source volume can

read, or passed into any LLM prompt. Prefer a scoped/short-lived setup-token.

• Persistence: HOME is backed by a docker NAMED VOLUME, so the credential store

$HOME/.claude/.credentials.json survives a restart on the volume — not on the

host. A fresh container on the same volume resumes the session.

Gate: the token is from the approved store, env-injected (not bound), and never

logged/persisted to a host-readable location. The home volume is a NAMED VOLUME,

not a bind.

Phase 4 — Run · gate: BLOCK

Start the box via buildClaudeRunArgs / runClaudeInside. The builder enforces the

guarantees by construction — do not hand-roll a docker run.

• Mounts go through the one chokepoint (mounts.ts): the home named volume at HOME

and a tmpfs /tmp. NO bind mount, NO /var/run/docker.sock, NEVER

--privileged. Read-only root, non-root, no-new-privileges, resource caps —

the same structural lockdown as any sandbox.

• The egress posture from Phase 1 is applied: offline → --network none;

anthropic-only → the experimental Anthropic-domains allowlist (custom bridge +

NET_ADMIN/NET_RAW + the init-firewall script applied inside the box).

• The CO-MOUNT GUARD: supplying a sourceVolume throws TokenCoMountRejectedError.

The token volume is NEVER co-mounted with an untrusted-code run. This is the

load-bearing Spike B caveat made structural — it is not optional.

Gate: the run argv was produced by the builder (not hand-rolled), the co-mount

guard was not bypassed, the posture matches Phase 1, and a dummy token reaches AUTH

(a real 401 Invalid bearer token) — proving the env token is the auth path before

any real credential is used.

Phase 5 — Teardown · gate: BLOCK

Tear down per the lifecycle rules, deciding the fate of the credential volume.

• Remove the container (docker rm -f). By default REMOVE the home/token volume

too — a persisted credential store is a standing exfil target; keep it only on an

explicit, recorded --keep-volume decision.

• Every object created carries the ca.sandbox=1 label (plus a build marker in

tests); the lifecycle/registry surfaces (destroy, prune) reclaim them.

• Confirm zero leaked labeled containers/volumes after teardown (cached images

excepted).

Gate: container removed; the credential volume removed unless --keep-volume was

explicitly chosen and recorded; no leaked ca.sandbox=1 objects remain.

Hard rules

• MUST authenticate via an env-injected CLAUDE_CODE_OAUTH_TOKEN — NEVER a host

bind of ~/.claude.

• MUST install a PINNED @anthropic-ai/claude-code@<semver> with

DISABLE_AUTOUPDATER=1; MUST NOT use @latest or an unpinned CLI.

• MUST default --with-claude egress to offline or anthropic-only; MUST NOT

give a token-bearing box wide-open egress.

• MUST NEVER co-mount the token/credential volume with an untrusted-code run (a run

that mounts the source volume at /work/repo) — buildClaudeRunArgs throws

TokenCoMountRejectedError and that throw MUST NOT be bypassed.

• MUST back HOME with a docker NAMED VOLUME (never a bind) so the .claude

credential store persists across restart on the volume, not on the host.

• MUST NOT give the box a host bind mount, the docker socket, or --privileged;

read-only root, non-root, and cap-drop hold as for any sandbox.

• MUST source the token from the approved store; MUST NOT log it, write it to a

host-readable file, or pass it into any LLM prompt. Use a DUMMY token in tests.

• MUST remove the credential volume on teardown unless --keep-volume is an

explicit, recorded decision.

• MUST treat the egress allowlist as EXPERIMENTAL (Spike C): for a token-bearing

box, offline is the only GUARANTEED posture.