src/wiring.ts routes agent work to one of three sandbox backends (local, Fly.io, AWS Lambda), each implementing the Sandbox interface with a core set of file and process methods plus optional capabilities detected at runtime via type guards. Optional capabilities—backup, blob staging, and process sessions—require both a profile flag AND all associated methods to be present; egress enforcement is silently disabled if the control plane lacks signing credentials or an API URL.
src/wiring.ts supports three sandbox backends — createLocalSandbox, createSpritesSandbox (Fly.io MicroVM), and createAwsSandbox (AWS Lambda MicroVM) — selected at runtime.[1] The Docker sandbox implementation spans three layers: cli/src/backends/docker.ts (CLI backend), src/sandbox/local-sandbox.ts (server-side lifecycle), and deploy/core/Dockerfile (container image). The Docker sandbox backend (cli/src/backends/docker.ts) runs sandboxes directly on the deployment host; configuration is stored in cli/src/config.ts and src/config.ts, with wiring exposed via cli/src/providers.ts. The Docker sandbox backend routes authentication-broker traffic over a private network alias rather than the public interface, keeping auth-broker connectivity intact in deployments where the broker is not externally reachable; this routing is validated by preflight checks in cli/src/backends/doctor.ts and cli/src/commands/check.ts. aws/microvm-agent/Dockerfile and cli/templates/aws/microvm-agent/Dockerfile install the GitHub CLI via an immutable (pinned) method to ensure consistent versions across image rebuilds and prevent silent version drift. cli/test/microvm-dockerfile.test.ts validates that the MicroVM Dockerfile uses the immutable GitHub CLI install form, guarding against regression in CI. The agent37 sandbox backend is implemented in src/sandbox/agent37-sandbox.ts, integrating with Agent37's computer API to provision and manage sandbox environments. The agent37 sandbox backend is wired into src/sandbox/sandbox-routing.ts, src/wiring.ts, and src/config.ts. src/sandbox/agent37-sandbox.ts includes auto-sleep for idle computers and hardened state handling in the start path to prevent failures or hangs from transient lifecycle states.
The Sandbox interface in src/sandbox/sandbox.ts defines the full contract for agent computer backends, with required methods provision, run, readFile, writeFile, listDir, removeDir, and teardown, plus optional capabilities including backupComputer, startProcess, readProcess, writeStdin, signalProcess, listProcesses, stageIn, stageOut, and extractFiles.[2] Optional sandbox capabilities — backup, blob staging, and process sessions — are detected at runtime via type-guard functions (supportsAgentComputerBackup, supportsBlobStaging, supportsProcessSessions) rather than interface conformance alone.[2] supportsProcessSessions requires BOTH profile.processSessions === true AND all five process-related methods (startProcess, readProcess, writeStdin, signalProcess, listProcesses) to be functions — a backend that sets the profile flag but omits any method will fail the guard.[2] supportsBlobStaging requires all three of stageIn, stageOut, and extractFiles to be present; a sandbox implementing only some of these methods is not treated as blob-staging-capable.[2]
AgentComputerProfile in src/sandbox/sandbox.ts has two writable-persistence modes, "snapshot_to_workspace" and "resident_disk", controlled by the writablePersistence field.[2] EgressEnforcement has three levels — "none", "ip_port", and "domain" — ranked in ascending restrictiveness, where "domain" is the most restrictive.[2] effectiveEgressEnforcement in src/sandbox/sandbox.ts returns "none" if the control plane lacks either a signingSecret or an apiBaseUrl, regardless of what the profile's egressEnforcement field says — egress enforcement is silently disabled on incomplete control-plane configuration.[2] TeardownOptions accepts keepWarm (keep the sandbox alive for reuse) and destroy (force full destruction) as optional flags passed to sandbox.teardown().[2] AgentComputerBackupOptions allows filtering backup entries via include (areas), exclude (per-entry predicate), includePaths, followSymlinks, and keepContentCaches.[2]
capabilitiesLostMovingTo in src/sandbox/sandbox.ts compares two sandboxes and returns human-readable strings for any capability or egress-enforcement level that would be lost by the migration.[2] CapabilityUnsupportedError is thrown when a caller requests a capability not supported by the current backend; it exposes backend and capability string fields and uses the error name "CapabilityUnsupportedError" for programmatic detection.[2] hasParentPathSegment in src/sandbox/sandbox.ts detects path-traversal attempts by checking whether any /-delimited segment equals "..", serving as a security guard against relative escape paths.[2] visibleNotInstalled in src/sandbox/sandbox.ts filters notInstalled tool names that are already advertised as extra tools, preventing tools the operator added via extraTools from appearing in the "not installed" list shown to the agent.[2] visibleTools in src/sandbox/sandbox.ts deduplicates the tool list by binary name (first whitespace-delimited token per line), keeping only the first occurrence of each binary.[2] A bug in command-form approval rule evaluation, fixed in cli/src/sandbox-layer.ts and src/deployment/deployment-layer.ts, ensures approval rules correctly govern which tool invocations proceed without explicit human sign-off.
Sources