Sandbox roles
Every factory step that involves a model runs the Claude CLI inside a disposable per-job container, never in the worker process. There are three model roles (planner, coder, reviewer) and one model-less role (the test container). The host treats everything a sandbox produces as untrusted data. This page documents the roles, what each can do and hold, the Docker contract the worker enforces, and the workspace in and out protocol. The isolation properties and threat analysis are on Sandbox.
Roles at a glance
| Role | Profile | Model call | Tools | Out file | Network | Credentials in the container |
|---|---|---|---|---|---|---|
| Planner | factory-planner | yes (gateway) | Read, Glob, Grep | plan.md (at most 64 KiB) | job network only, to the gateway | the per-job token only |
| Coder | factory-coder | yes | Bash, Read, Glob, Grep, Edit, Write | patch.diff (at most 1 MiB) | as planner | the per-job token only |
| Reviewer | factory-reviewer | yes | Read, Glob, Grep | review.json (at most 16 KiB) | as planner | the per-job token only |
| Test | none (SandboxTestRunner) | no | the repo policy's fixed test command | combined output, captured (at most 1 MiB) | --network none | none: no token, no env file |
Role policy ids registered at the gateway: factory-planner, factory-coder, factory-reviewer (DEFAULT_POLICY_IDS_BY_PROFILE; the runtime refuses a factory profile whose role policy is missing from an operator's partial map, and a missing policy id is a 400 at registration). The role policies set no tool allowlist and no identity: factory roles run with identity none and no MCP grants (plan decision D-U5).
Topology of one role step
- A per-job Docker network is created with
--internalandcom.docker.network.bridge.gateway_mode_ipv4=isolated; the gateway container is connected to it and its address on that network becomes the CLI's base URL. The only reachable peer is the gateway data port (gatewayPortdefault 8787). - The workspace is a tmpfs volume (
type=tmpfs, size 1 GiB, uid and gid 10001). A "keeper" container holds it between workspace-in, the run and workspace-out; the tmpfs content lives only while a container mounts it (probe 0e). - The job container runs the sandbox image by digest only (
<repo>@sha256:<64 hex>; a tag or digest-less reference refuses to start, SB-IMG1). - Object names derive from a validated job id and a per-attempt 8-hex nonce:
afsbx-<jobId>-<nonce>for the network, container, volume (-ws) and keeper (-keeper). All carry labelsagentforge.job,agentforge.owner,agentforge.instance,agentforge.started. A periodic sweeper removes this owner's earlier incarnations and any labelled object older than the sweep age (MAX_TTL_MS + 120 s= 1,020,000 ms); one live process per owner value is assumed.
Run sequence
Key rules (from SandboxRuntime and its contract):
- Register first. The decorators have already admitted the ledger row with this
jobId; the runtime then registers the job. Token TTL istimeoutMs + 60,000ms (TTL_MARGIN_MS), capped atMAX_TTL_MS900,000 ms, so a role step can last at most 840 s. - The token never touches argv. It reaches the container through a 0600 env file deleted once the container runs.
- Cost and token counts are never taken from the sandbox. The gateway's debits are the cost.
- Completion is a host fact. The factory activity treats a step as complete only when this attempt's awaited workspace-out extraction succeeded and the out file validated (and the runner reported
successfor the role steps). The runtime's status is display-only exceptaborted,timeout,disabledandbudget_exhausted, which the host itself caused. - Teardown. After an abort, timeout, kill-switch hit or failure the host kills (or after a normal end, stops) the container, then removes it, bounded by
STOP_TIMEOUT_MS15,000. After a claimed result the container getsEXIT_WAIT_MS10,000 ms to exit before kill. The host timer (timeoutMs) is the bound; thetimeout --signal=KILLwrapper (timeout plusKILL_MARGIN_S30 s) runs as the container's own uid and is a convenience, not a control. - Kill switch. Polled while running; a hung or erroring read counts as an error and fails closed after repeated errors.
The job container
runArgs produces this exact docker run (the driver checks every argv against an allowlist of flags with value checks, ALLOWED_FLAGS, which refuses --privileged, -v, -p, --entrypoint, --device, --sysctl, -e and anything unlisted):
| Setting | Value |
|---|---|
| user | 10001:10001 |
| root filesystem | --read-only |
| capabilities | --cap-drop ALL, --security-opt no-new-privileges:true |
| processes | --pids-limit 512 |
| memory | --memory 2g, --memory-swap 2g |
| CPU | --cpus 2 |
| file descriptors | --ulimit nofile=1024:1024 |
| IPC | --ipc private |
| DNS | pointed at the loopback address (no resolver reachable) |
| init and stop | --init, --stop-timeout 5 |
| logging | --log-driver none |
| runtime | --runtime runc or runsc (SANDBOX_RUNTIME) |
| tmpfs | /home/agent (256 MiB, uid 10001), /tmp (512 MiB) |
| mounts | volume at /workspace |
| environment | --env-file only |
| command | timeout --signal=KILL <seconds> node dist/main.js |
Keeper: --network none, --read-only, --cap-drop ALL, no-new-privileges, user 10001:10001, --pids-limit 64, --memory 256m, --cpus 0.5, --init, --log-driver none, command sleep infinity.
SANDBOX_RUNTIME=runc shares the host kernel; the factory worker refuses it at startup unless FACTORY_ALLOW_RUNC=throwaway-repo-only is set (use runsc for any repo that matters). runsc on the sandbox host is UNVERIFIED in docs/deploy-factory.md.
The runner
apps/sandbox-runner/src/runner.ts reads exactly one JSON job spec on stdin and writes one NDJSON RuntimeEvent per stdout line with exactly one result last. JobSpec is strict and never carries an image reference, mount, flag or path: jobId, requestId (1 to 256 characters), prompt (at most 1,000,000 characters), model (claude- plus a bounded id, a full model id, no alias), profile, and limits with maxTurns 1 to 100, maxBudgetUsd greater than 0 and at most 10 (advisory only: the gateway's ledger row is the ceiling) and timeoutMs 1000 to 840,000.
The CLI environment is closed (SB-ENV1): PATH, HOME=/home/agent, ANTHROPIC_BASE_URL, ANTHROPIC_API_KEY (the job token), CLAUDE_CODE_MAX_OUTPUT_TOKENS, the four DISABLE_* and CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC flags set to 1, and offline pnpm settings (pnpm_config_store_dir, pnpm_config_cache_dir, pnpm_config_offline). The runner validates that the key matches the job-token shape.
The SDK options are permissionMode: 'dontAsk', tools and allowedTools equal to the role's tool set, disallowedTools equal to every other built-in plus Task, settingSources: [] and persistSession: false. There is deliberately no path hook inside the sandbox: with Bash present a path hook confines nothing, so the controls live outside the container.
The SDK deadline for factory roles is timeoutMs - 30 s (OUT_MARGIN_MS), leaving the runner time to write the out file before the host's timeout.
Workspace in and out
- Workspace in. Streamed with
git archivefrom the host's clean clone for every step and never stored (its SHA-256 is recorded on the step). Reaching a tree over 256 MiB or 50,000 entries ends the jobrepo_too_large. The workspace is extracted in the keeper withtar -x --no-same-owner. - Coder runner. Before the model starts the runner removes
.agentforge/out, creates it, runsgit init,git add -A(excludingnode_modulesand.agentforge) and onebasecommit, keeps that commit SHA in memory, applies the host's carried patch uncommitted and deletes.agentforge/in. The commit must never include the carried patch, so the nextpatch.diffis cumulative against the base. After the SDK ends it overwrites.git/configwith a minimal fixed one, removes.git/info, stages the tree and writesgit diff --cached --binary --no-ext-diff --no-textconv <base sha>(the model can write.git/config, so a filter, textconv or external diff must never run). The runner's git runs withcore.hooksPath=/dev/null,core.fsmonitor=false,commit.gpgsign=false,GIT_CONFIG_NOSYSTEM=1,GIT_CONFIG_GLOBAL=/dev/null,GIT_NO_REPLACE_OBJECTS=1, fixed dates, and no remote. - Planner and reviewer. They have read tools only; the runner saves their final message text as
plan.mdorreview.json. - Workspace out. The keeper runs
tar -c -C /workspace/.agentforge/out --no-recursion -- <name>(a fixed argv) bounded byworkspaceOutTimeoutMs(default 60,000;FACTORY_WORKSPACE_OUT_TIMEOUT_MS). A.agentforgeoroutsymlink resolves only inside the keeper. Every other workspace byte, includingnode_modulesafter an honest install, is never read. The host's one-file validator rules are on Patch policy.
The test container
SandboxTestRunner runs the repository's test command in a container built from the job container's hardening and limits, with these differences (testRunArgs): --network none and no DNS option, no env file (no token, no gateway, no model), --workdir /workspace, and the policy's argv appended after the timeout --signal=KILL prefix.
- The command comes from the operator's
FactoryRepoPolicy.tests.command(default['pnpm', 'test']), a fixed argv, never a shell string. It must be 1 to 64 tokens, each 1 to 256 printable ASCII characters with no whitespace. tests.timeoutMsdefault 300,000, at most 840,000 (MAX_TEST_TIMEOUT_MS).- The result is the Docker-observed exit code only (evidence, never parsed from output); a timeout reports
timedOutand no exit code. Combined output is capped at 1 MiB (TEST_LOG_CAP) with a truncation marker. The log is stored as atest-logartifact (prefix cut at 1 MiB) and its tail of at most 8 KiB feeds the next coder prompt. - No ledger row and no gateway registration exist for a test step.
- Patched tests decide their own exit code. A passing run is evidence for the reviewer and the human, never an approval.
The same runner also serves CodeCrucible's model-less runs (quality-analyze, quality-run, quality-tests), which leave one JSON file in the out directory; see Quality exec worker and image.
Trust summary
| Component | Trust | Holds | Never holds |
|---|---|---|---|
| factory worker | trusted | database, Temporal, the Docker socket, the two GitHub App keys and minted tokens (memory only), the gateway worker control token | an Anthropic key (startup refuses it) |
| gateway | trusted | the Anthropic key, per-job tokens, role policies | GitHub keys |
| role sandbox | untrusted | the job token only | everything else |
| test sandbox | untrusted | nothing | everything |
| fork and PR | external |
The factory worker holds the Docker socket and parses attacker-influenced patches; the plan considered splitting publishing onto its own queue (option O4) and rejected it for P3 as too costly for a solo operator, recording the two-App split as the mitigation, with a revisit at the VPS gate.
Unverified
The sandbox image, the Docker spawn path on the target VPS (rootless Docker or a launcher), runsc, and fork-origin pull request flow are not verified on real infrastructure (docs/deploy-factory.md, items UP1, UP2, OQ-1, M-B). The local scripts that build and exercise the images (scripts/sandbox-image.test.sh, scripts/factory-e2e.test.sh) are local only and not in CI.
Sources
apps/worker/src/sandbox/contract.ts(SANDBOX_PROFILES,OUT_FILE_BY_PROFILE,SandboxConfig,runArgs,keeperRunArgs,networkCreateArgs,volumeCreateArgs,testRunArgs,workspaceOutArgs,ALLOWED_FLAGS, TTL and timing constants)apps/worker/src/sandbox/sandbox-runtime.ts(SandboxRuntime.run)apps/worker/src/sandbox/test-run.ts(SandboxTestRunner,TEST_LOG_CAP)apps/worker/src/sandbox/control.ts(dockerExecControl,httpControl)apps/sandbox-runner/src/runner.ts(ROLE_TOOLS,JobSpec,RunnerEnv,sandboxOptions,commitBase,writePatch,runJob,OUT_MARGIN_MS)apps/worker/src/factory/activities.ts(runRole,workspaceTar,StepIo),apps/worker/src/factory/outfile.ts,apps/worker/src/factory/config.tsapps/worker/src/factory-main.ts(sandboxPorts)packages/agent-types/src/factory.ts(FACTORY_PROFILES,FactoryRepoPolicy.tests)docs/deploy-factory.md,.omc/plans/p3-software-factory.md(sections 3, 5.1, 6.2, 6.4, 6.8)