sandbox_action capability for a dispatch. It covers when sandbox access is appropriate, how the sandbox VM is provisioned and reused, how command policy limits what the model can issue, and the pitfalls of lifecycle reuse and credential injection.
If the agent only needs to read an authorized file or call an API, use the corresponding tool. Sandbox is for executing code: tests, builds, package installation, and scripts. A VM adds cost, latency, and another policy boundary.
When to enable sandbox capability
Enablesandbox_action for the dispatch when one of the following is true:
- The agent must execute code in isolation. Running tests, building a package, executing a Python script, running a linter — anything where the agent’s success criterion is “does this command exit zero?” requires a sandbox.
- The agent must mutate a working directory across multiple steps. Cloning a repo, installing dependencies, making file edits, running tests, iterating until tests pass. The sandbox provides a stateful filesystem that persists across tool calls within a single dispatch (and, with snapshotting, across nodes).
- The agent must run untrusted code. Code authored by another agent, code from an external source, or code the operator does not want running inside the Forge runtime. The sandbox is the only execution path outside it.
- The agent’s task is fundamentally a command-line workflow. Factory Workers are the canonical case — given a task, clone a repo, write a fix, run tests, report. The sandbox is the workspace.
- The agent only needs to call HTTP APIs, read platform data, or invoke other agents. Those are tool-call jobs.
- The agent’s output is purely textual reasoning. No code execution means no sandbox.
- The agent is a chat assistant that helps a human reason about code. Show, don’t run.
- The agent is a router or join node. Routing decisions are not sandbox dispatches.
How the sandbox works
The sandbox VM is not a node attribute or a parameter an agent passes. It is the platform’s code-execution substrate: a layer underneath dispatch, the way the Trust Fabric is the layer underneath authorization. Agents reach into it through tools; the platform decides when a VM is provisioned, reused, kept warm, snapshotted and destroyed. That shape has four consequences:- Provisioning is lazy. A node never says “use sandbox X”. It declares which tools it can call, and the first call to a sandbox-bound tool provisions the VM. A turn that never calls the tool never creates one.
- A workflow can keep one sandbox lineage across nodes. Through snapshot continuity, the VM state that node 3 produced is restored at node 5, with
node_modulesstill in place. - Interactive contexts can use a warm pool. A chat turn or a Console-initiated workflow can check out a pre-booted VM and pay about 1–2 seconds instead of about 10 for the first call.
- The agent sees one interface. Whether the VM is new, restored from a lineage, or checked out from the pool, the agent calls
sandbox_actionand gets the same response contract. Credentials, network policy and runtime image are resolved at provisioning time and reach the agent as environment variables.
Where the sandbox sits in a dispatch
A sandbox-bound dispatch passes through five layers. The flow is the same whether it starts from a workflow node, a chat turn, a factory worker, a personal agent, or the Workflow Architect.- Agent — the model’s turn: reasoning and tool calls.
- Agent composition — the agent definition resolves into a ready-to-run configuration: prompt, tools, skills and model. Sandbox-bound dispatches use the same composition path as every other dispatch; the Trust Fabric’s policy and scope gates apply network-policy and resource constraints before a VM is provisioned.
sandbox_actiontool — the model-callable surface, bound to this dispatch. Pre-call guards enforce emergency controls, command policy and audit before anything reaches the VM.- Provisioning — the platform picks a VM source in this order: warm-pool checkout → hardened base snapshot → lineage-head restore → fresh runtime. Dispatches that restore a lineage skip the pool, because a restore needs a fresh boot from a specific snapshot.
- Sandbox VM — the VM runs with the resolved runtime, environment, network policy and source. Command output streams back, is scrubbed of known secret values, and is recorded in the tool execution log. At the end of the node the VM returns to the pool, is snapshotted into a lineage, or is destroyed.
Capability injection at boot
Every VM boots with three resolved capabilities:- Credentials. A sandbox dispatch receives only the credential material resolved for its declared tool calls. Injection happens after preflight, and known secret values are scrubbed from captured output. Still avoid printing environment variables or secret-bearing request data.
- Network policy. The effective policy comes from the dispatch’s sandbox policy plus the deployment baseline. The baseline denies all network access unless the node’s sandbox configuration allows it; a deployment can opt back into allow-all with
SANDBOX_DEFAULT_NETWORK_POLICY=allow-all. Tighter per-factory postures are applied by the Trust Fabric at dispatch. Network policy is enforced when the VM is created and cannot be changed at checkout, so a dispatch that needs a different posture from the pool baseline gets a fresh VM. - Runtime image.
node24,node22orpython3.13. Onlynode24has a hardened base image today.
The sandbox VM lifecycle
A single VM moves through a small set of states:
Cold to warm. A clean boot takes 5–15 seconds because it boots the runtime image and installs deployment-default dependencies. Two techniques shorten it:
- Hardened base image. The platform pre-bakes a snapshot with deployment-default dependencies installed and boots fresh VMs from it, so the per-boot
npm installdisappears. - Idle warm pool. A small fleet of pre-booted VMs per runtime, topped up to its desired size every 30 seconds, so the first sandbox call in an interactive turn checks out a hot VM.
sandbox.snapshotOnExit: true, the platform captures the VM’s state to a durable snapshot before releasing it and records the snapshot as the head of that node’s sandbox lineage.
Snapshotted to reused. A downstream node that sets sandbox.restoreFrom to the lineage boots from its latest snapshot. The runtime is checked against the lineage’s original runtime: restoring a node22 lineage onto a node24 dispatch fails loudly instead of silently booting the wrong runtime.
Reused to retired. Once a downstream node snapshots its own state, the prior snapshot is no longer the head. Pool VMs retire when they exceed their maximum lifetime, when a checkout returns one with too little remaining lifetime, or when a pool VM snapshots into a workflow lineage.
Emergency switches
Three deployment switches turn parts of the lifecycle off without a redeploy:Vercel Sandbox provider
Vercel Sandbox is the current sandbox provider. Dispatch code depends on the sandbox capability contract, not on the vendor SDK. Agents do not receive a reusable “run in sandbox” singleton. A sandbox-capable dispatch buildssandbox_action for that execution subject and seals the sandbox binding and executor context into it. Because the tool is injected per dispatch, adding sandbox_action to an agent’s static tool sets has no effect.
The sandbox_action contract
The model-visible schema is an operation union. Operations cover the lifecycle the bound dispatch allows: creating or reconnecting to a session, running a command, reading command output, file transfer, snapshot operations, and stopping the session. The exact operations and limits come from the bound executor and may be narrower than the provider’s full API.
Three rules matter when you author an agent or workflow:
- Use the schema the tool advertises. Do not assume the retired
{ command, files, runtime, snapshot, timeoutMs }request shape. - Move durable files through Files and Bindings. Use
file_getto copy an authorized Forge file into the VM andfile_putto persist a sandbox result. Tool output and a sandbox path are not durable workflow outputs. See Files and bindings. - Treat an interrupted command as uncertain. A timeout or lost observer does not prove an external effect did not happen. Inspect the session and the audit evidence before retrying a mutating command.
Session lifecycle
- Bind — dispatch resolves the sandbox provider, policy, subject and allowed operations.
- Create or reconnect — the tool obtains the run’s durable sandbox session.
- Operate — commands and file transfers execute through the governed binding.
- Persist or stop — required outputs become Forge files; the session is stopped or retained by policy.
Snapshots
Snapshots belong to the sandbox capability and the Console lifecycle, not to fields on every command call. A procedure build or another authorized path may create a reusable snapshot, and later sessions can use it when the binding and provider policy allow. Pass durable Forge inputs between workflow nodes unless the product surface explicitly promises snapshot reuse.Isolation guarantees
- The VM does not inherit platform authority. File and platform access returns through separately authorized callback or binding surfaces.
- Network access follows the resolved deployment and command policy; not every sandbox is offline.
- File access is allowlisted by the dispatch binding. A file ID the binding does not allow, or an undeclared workflow output key, is refused.
- Deadlines, leases, cancellation and provider failures are distinct. A command timing out does not by itself certify rollback of its effects.
Detached agent turns
An agent node whose declared timeout exceeds the inline budget (8 minutes) runs its whole turn inside a sandbox VM. Placement is declared, not predicted: the node’s timeout is the only control, exactly like a procedure’stimeoutSeconds. The platform preserves the composed configuration, eligible tool bindings and structured-output contract across placements. The Session view marks the detached placement with a Detached VM badge.
Around a detached turn, the platform provides:
- Narration. The platform reads structured output from the VM into the run’s Activity feed. Tool calls and terminal results use their authorized callback surfaces. The server writes the opening prompt; the VM cannot impersonate a user message in its thread.
- Liveness. Polling evaluates deadline, lease, cancellation and budget state, and a backstop can adopt a lost observation chain. An observation delay is not proof that remote work stopped.
- Cost attribution. Every model call the VM makes goes through the run-scoped inference gateway and is priced and booked to the same token ledger inline turns use. The completed step shows its token cost and VM compute cost separately.
- The same node tools. The tools every workflow agent node receives — the blackboard,
knowledge_search,knowledge_record,knowledge_report_outcome, and the tool-set-gated ones — are advertised to a detached turn too. Each call comes back through the agent callback and runs server-side under the same governance as an inline call. - One structured-output shape. A structured turn answers in text first and the platform parses the final JSON object; schema-constrained generation runs only to repair a reply that does not parse. The shape is the same on both placements, with or without tools.
Common patterns
Factory Worker code loopHow to declare a per-tool sandbox command whitelist
A sandbox-bound tool can declare asandboxCommands array on its tool definition, listing the shell commands the model may issue through that tool. This lets operators grant a Factory Worker narrow access — npm install *, npm test, git * — without lifting the deployment-wide command denylist for every other agent.
The schema
The whitelist lives on the tool definition’ssandboxCommands field next to requiresSandbox. Each entry has these fields:
A tool with
requiresSandbox: true and a non-empty sandboxCommands array is in strict allowlist mode: a command passes only if it matches at least one entry. A tool with requiresSandbox: true and no sandboxCommands falls back to the deployment-wide command denylist. A tool with sandboxCommands: [] blocks every command with command_not_in_whitelist.
How dispatch builds the effective allowlist
When the agent’s configuration is composed, the platform takes every resolved tool withrequiresSandbox: true and unions their sandboxCommands arrays into one effective allowlist for the dispatch. Each sandbox tool’s pre-call guard checks commands against that allowlist; the legacy denylist runs only when no allowlist is set. The command executor re-checks the same allowlist before running a command, as defense in depth.
Authoring the whitelist
Update a tool’s whitelist through the tool editor or the sandbox-commands operation; it requires thetools:manage permission. The update replaces the whole whitelist after validating it (non-empty patterns, globs that compile) and writes a tool_sandbox_commands_updated audit event with the previous and new counts.
For strict mode to engage, a tool needs both requiresSandbox: true and a non-empty sandboxCommands array. The built-in sandbox tools (sandbox_action, pa_sandbox_action) do not set requiresSandbox by default; until an operator flags the tool, the global denylist is the only enforcer.
Common pitfalls
Cold-start latency is real and asymmetric
A clean boot takes 5–15 seconds before the agent can issue a single command. The hardened image, snapshot restore and warm pool reduce it, but only under conditions. The pool reduces first-call latency to about 1–2 seconds only when the pool is hot for the requested runtime. The hardened image removes the per-bootnpm install only for node24 today; node22 and python3.13 boot from clean runtime images.
For an interactive context, the pool’s hit rate determines the latency the user sees. For a multi-step batch workflow, lineage restore skips per-step boot time entirely, but only if the upstream node snapshots on exit and the downstream node restores from its lineage.
If a dispatch consistently misses the pool, check three things:
- Is the pool enabled for the requested runtime, with a desired size above zero?
- Does the dispatch inject credentials? Credential injection forces fresh provisioning.
- Does the dispatch site skip the pool? Personal Agent tools and factory workers do, because they change VM state without snapshotting.
Snapshot reuse has runtime constraints
Restoring anode22 lineage onto a node24 dispatch fails with a runtime-mismatch error. This is intentional. If you change an agent’s runtime defaults, either archive the agent’s old lineages or accept that downstream nodes lose continuity.
A lineage advances only when a node successfully snapshots its own state. If a node restores a snapshot, runs a command, and crashes before snapshotting, the lineage head does not move, and the next dispatch restores the same prior snapshot. A provisioning failure on the restore path reaches the dispatch as a tool-call failure.
Credentials always bypass the pool
If your agent declares required credentials, the dispatch always provisions a fresh VM. Pool VMs are long-lived and shared, so injecting plaintext credentials into one would leak them across reuses; credentials only land on a VM that is about to be retired. A credentialed dispatch therefore always pays cold-start or hardened-base latency, never pool latency. You cannot have both pool warmth and credentials today. Do the credential-bound work in a non-sandbox tool call, and use the sandbox only for credential-free code execution.The pool is empty by default
The warm pool ships disabled: a fresh deployment pre-warms no runtime. Operators opt in per runtime. Until then, every sandbox-bound dispatch pays at least hardened-base latency, or full cold-start onnode22 and python3.13.
Pool starvation is a soft signal
When the pool is empty for a requested runtime, the governance decision records a pool-starvation marker. The decision itself does not change: the dispatch falls through to fresh provisioning, and hard budget enforcement stays with the budget gate. If you see that marker repeatedly in the audit log, raise the pool’s desired size.One sandbox tool can run another tool’s whitelisted commands
The allowlist is a union across the dispatch, not a per-tool check. An agent with two sandbox tools — tool A allowsnpm install, tool B allows yarn install — can run both commands through either tool. Design your whitelists assuming the union.
Do it over the API
A per-tool whitelist can be set over the API. These calls use theFORGE_BASE set up in the Raw HTTP tab of the quickstart. The two writes accept only a Personal key or a platform API key, not an External App, so send your Personal key as the bearer in place of $ACCESS_TOKEN for all four calls, with scopes that include tools:manage, tools:read and agents:read (see Choose a credential).
Flag the tool as sandbox-bound, so strict allowlist mode can engage:
tools:manage. Confirm the flag, then watch how many commands the whitelist rejects:
tools:read; the rejection count needs agents:read at the platform scope. The window defaults to the last seven days; pass sinceMs (epoch milliseconds, within the last 90 days) to choose its start. The count is a number only, never a command; auditAvailable is false when no sandbox audit is recorded for the window.
Over MCP, forge_call_operation replaces the whitelist. It is in the default start job:
See also
- Compose a Workflow — Declare the runtime budget — the Timeout field, which is the control that moves a node into a VM
- Files and bindings — how authorized files move in and out of the VM
- System overview — where sandbox dispatch sits in the platform

