Skip to main content

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​

RoleProfileModel callToolsOut fileNetworkCredentials in the container
Plannerfactory-planneryes (gateway)Read, Glob, Grepplan.md (at most 64 KiB)job network only, to the gatewaythe per-job token only
Coderfactory-coderyesBash, Read, Glob, Grep, Edit, Writepatch.diff (at most 1 MiB)as plannerthe per-job token only
Reviewerfactory-revieweryesRead, Glob, Grepreview.json (at most 16 KiB)as plannerthe per-job token only
Testnone (SandboxTestRunner)nothe repo policy's fixed test commandcombined output, captured (at most 1 MiB)--network nonenone: 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 --internal and com.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 (gatewayPort default 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 labels agentforge.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 is timeoutMs + 60,000 ms (TTL_MARGIN_MS), capped at MAX_TTL_MS 900,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 success for the role steps). The runtime's status is display-only except aborted, timeout, disabled and budget_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_MS 15,000. After a claimed result the container gets EXIT_WAIT_MS 10,000 ms to exit before kill. The host timer (timeoutMs) is the bound; the timeout --signal=KILL wrapper (timeout plus KILL_MARGIN_S 30 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):

SettingValue
user10001: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
DNSpointed 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)
mountsvolume at /workspace
environment--env-file only
commandtimeout --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 archive from 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 job repo_too_large. The workspace is extracted in the keeper with tar -x --no-same-owner.
  • Coder runner. Before the model starts the runner removes .agentforge/out, creates it, runs git init, git add -A (excluding node_modules and .agentforge) and one base commit, 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 next patch.diff is cumulative against the base. After the SDK ends it overwrites .git/config with a minimal fixed one, removes .git/info, stages the tree and writes git 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 with core.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.md or review.json.
  • Workspace out. The keeper runs tar -c -C /workspace/.agentforge/out --no-recursion -- <name> (a fixed argv) bounded by workspaceOutTimeoutMs (default 60,000; FACTORY_WORKSPACE_OUT_TIMEOUT_MS). A .agentforge or out symlink resolves only inside the keeper. Every other workspace byte, including node_modules after 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.timeoutMs default 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 timedOut and no exit code. Combined output is capped at 1 MiB (TEST_LOG_CAP) with a truncation marker. The log is stored as a test-log artifact (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​

ComponentTrustHoldsNever holds
factory workertrusteddatabase, Temporal, the Docker socket, the two GitHub App keys and minted tokens (memory only), the gateway worker control tokenan Anthropic key (startup refuses it)
gatewaytrustedthe Anthropic key, per-job tokens, role policiesGitHub keys
role sandboxuntrustedthe job token onlyeverything else
test sandboxuntrustednothingeverything
fork and PRexternal

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.ts
  • apps/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)