Sandbox providers
Every provider runs the same tools, but setup, storage and network support differ. Pick one from the comparison on Sandboxes, then configure it here.
| Provider | Runs on | Section |
|---|---|---|
sandbox | Broods-hosted Firecracker VM | sandbox |
lambda | AWS Lambda MicroVM | lambda |
daytona, e2b, vercel | A vendor account you bring | daytona, e2b, vercel |
cloudflare | Cloudflare Container | cloudflare |
worker | Fast Cloudflare V8 Worker | worker |
machine | Your own computer | Your computer |
custom | Your server over HTTP | Your own server |
sandbox
Runs Firecracker VMs on a workdir node. The hosted service does not offer it yet, so use lambda there; a self-hosted deployment points it at its own node. It supports workspace mounts, persistence with pause and resume, background jobs with logs and stop, the live dashboard terminal, and the Create snapshot action.
export const box = defineSandbox({
name: "box",
provider: "sandbox",
size: "small",
network: { mode: "restricted", allowDomains: ["pypi.org"] },
permissionMode: "edit",
options: { docker: true },
});
options.docker: trueenables Docker inside the sandbox. It is accepted only on this provider.options.cpu,options.memoryMbandoptions.diskGboverride the size. vCPU is one of 0.5, 1, 2 or 4.options.mountAwsS3Buckets: truemounts workspace storage even when no workspace setsstorage.snapshotnames an image to boot.
Self-hosting this provider has guest image requirements, covered in Sandbox internals.
lambda
Each session runs in one AWS Lambda MicroVM with real bash, python3, Node 22, uv and ripgrep. It supports workspace mounts, persistence through suspend and resume, background jobs and the live terminal.
export const box = defineSandbox({
name: "box",
provider: "lambda",
network: { mode: "deny-all" },
permissionMode: "ask",
envVars: { MY_API_BASE: "https://api.example.com" },
});
- Every MicroVM is the same machine: a 2 GB baseline that bursts to 4 vCPU and 8 GB, on an 8 GB disk.
sizeand resource options do not change it, and the dashboard shows that machine. - A MicroVM lives at most 8 hours. A persistent reservation is recreated after that.
restrictedbehaves likedeny-all, andallowDomainsorallowCidrsare rejected. Underdeny-allthe managed workspace bucket stays reachable.- A workspace that brings its own bucket cannot be reached under
deny-all, so the run is refused. Pair it withallow-all. - The workspace mount cannot append or edit in place.
>>and in-place edits fail. Thewriteandedittools rewrite whole files, so tell the agent not to append. - The image, roles and log group are managed by the platform.
optionsaccepts onlyworkspaceRootandreservationKey. - The Snapshot action builds a new image from the files a running machine changed, see Images.
image: "obscura"orimage: "browser"boots a platform image with a headless browser.snapshotpins an image by ARN, in the same AWS account and region as the default. Any other ARN, a snapshot another account built, or one taken on another stage, fails the run. broods logs --sandbox <uuid>and the Instances Logs tab show what the guest itself writes to stdout and stderr.
The first exec after a resume can take 1 to 10 seconds while the VM restores.
daytona
Runs on a Daytona sandbox and supports workspace mounts through a mount-s3 snapshot.
export const box = defineSandbox({
name: "daytona",
provider: "daytona",
permissionMode: "ask",
snapshot: "fuse-s3",
options: {
target: "default",
workspaceRoot: "/mnt/workspaces",
mountAwsS3Buckets: true,
},
});
- Set your Daytona credentials in
options.apiKey,organizationId,apiUrlandtarget, withenv("NAME")for the key. A self-hosted deployment can set fallbacks for every account. See Self-hosting. - Set
options.mountAwsS3Buckets: truefor workspace tools. The snapshot must includemount-s3. snapshotnames the Daytona snapshot to boot.options.imageinstead builds the sandbox from a Docker image when it is created. Set one or the other.- The Snapshot action captures a reserved sandbox's filesystem as a new Daytona snapshot, see Images.
network.modemaps to Daytona'snetworkBlockAll.restrictedapplies the CIDR allowlist only; domain lists are ignored with a warning.- Idle and lifetime map to Daytona's
autoStopIntervalandautoDeleteInterval. sizedoes nothing here. The dashboard shows the vCPU, memory and disk Daytona reports for the sandbox.- TypeScript files are not transpiled. Run compiled JavaScript, and call
python3explicitly. options.s3Endpointmust be a publichttpsURL.
| Symptom | Fix |
|---|---|
Daytona has no available runner for snapshot '<name>' | The snapshot is pinned to one runner, or that runner is full. Rebuild it as a general snapshot, drop a target that does not match the snapshot's region, or retry |
e2b
Runs on an E2B template. Use it for compute without a workspace.
export const box = defineSandbox({
name: "e2b",
provider: "e2b",
network: { mode: "allow-all" },
permissionMode: "ask",
snapshot: "runtime-template",
});
network.modemust beallow-all, set explicitly. E2B cannot enforce egress limits, sodeny-all, the default, andrestrictedare rejected.- Workspaces are not supported. Attaching one fails.
onCreateandonResumeare rejected. Put setup in the template.- The template sets the machine size, and
sizedoes nothing. The dashboard shows the vCPU and memory E2B reports, and?for disk, which E2B does not report. - Set your E2B key in
options.apiKey. A self-hosted deployment can set a fallback for every account, see Self-hosting. snapshotnames the E2B template or snapshot to boot. The Snapshot action captures a reserved sandbox as an E2B snapshot, pausing it while it captures.- Persistent mode pauses on idle and keeps files, installs and processes.
- Background jobs run natively, and
async_statusoffersstatusonly, withoutlogsorstop. - The template needs Python for background-job completion callbacks.
vercel
Runs on Vercel Sandbox and mounts any workspace attached to it.
export const box = defineSandbox({
name: "vercel",
provider: "vercel",
persistent: true,
network: { mode: "restricted", allowDomains: ["api.example.com"] },
permissionMode: "bypass",
onCreate: ["npm install"],
onResume: ["test -d node_modules"],
// A snapshot with mount-s3 already installed, so a restricted network can
// mount a workspace. See the install note below.
snapshot: "snap_with_mount_s3",
});
-
Set your Vercel credentials in
options.token,teamIdandprojectId. A self-hosted deployment can set fallbacks for every account. See Self-hosting. -
snapshottakes a managed image, an OCI image in your project's Vercel Container Registry, or a Vercel snapshot id, which starts withsnap_.Image Contents vercel/sandbox/universal:latestNode.js 24, Bun, Python 3.14, coding agents, dev tools. The default vercel/sandbox/node:22,:24,:26Smaller Node.js images vercel/sandbox/python:3.14Python with pip, venv and uv vercel/sandbox/ubuntu:latest,vercel/sandbox/arch:latestGeneral base images -
The Snapshot action captures a reserved sandbox as a Vercel snapshot that does not expire. Vercel stops the sandbox to capture it, and its next call resumes it.
-
All three network modes are enforced natively.
-
options.networkIdattaches the sandbox to a Secure Compute network, so its public traffic leaves from the network's static IPs and it reaches your AWS VPC over peering. Secure Compute needs a Vercel Enterprise team; the ID is under Settings, Networking.network.modestill applies, so arestrictedsandbox lists the private hosts it calls. A reserved sandbox moves to a changed network once its current session ends. -
sizedoes nothing here. The dashboard shows the vCPU and memory once Vercel reports them, and?for disk, which Vercel does not report. -
A workspace attached to the sandbox is mounted, with no option to set. Each call mounts the workspace's S3 prefix at
/mnt/workspaces/<namespace>with Mountpoint for S3, on hour-long credentials scoped to that prefix. They stay out of the sandbox env and the agent's commands, but code withsudocan read them from the mount process, as on Daytona. The mount is replaced after 45 minutes or when a resumed session lost it. The deployment needs its mount role configured (see Self-hosting), or the workspace names its own bucket withassumeRoleor R2 auth. -
The images ship without
mount-s3, so the first mount installs it, which takes about 10 seconds and needs egress tos3.amazonaws.comand the Ubuntu mirrors. Underrestrictedordeny-all, or to skip the install, install it once in a reserved sandbox, capture it with the Snapshot action, and boot thatsnap_id. The workspace bucket's S3 hosts are always allowed, as onlambda. -
storage.provider: "vercel"(Vercel Drives) is rejected. -
lifecycle.idleTimeoutSecondsis at most 24 hours. Vercel holds one session to 24 hours on Pro and Enterprise and to 45 minutes on Hobby, so a longer idle window is refused. Each call extends the session to one idle window past its own end. A session that reaches the plan cap stops, and the next call resumes it. -
A background job holds the session open only while it is polled. One left unpolled for longer than
idleTimeoutSecondsstops with the session, so set the idle window above the job's run time. -
maxLifetimeSecondsis checked when a call takes the sandbox. The call that trips it boots a fresh one.
| Symptom | Fix |
|---|---|
Vercel Sandbox rejected the request (HTTP 403 / 401) | The token is invalid, expired, or cannot reach the team and project. Check it at vercel.com/account/tokens |
cloudflare
Runs bash in a Cloudflare Container with bash, python3, Node 24, git and ripgrep. Use it for compute without a workspace.
export const box = defineSandbox({
name: "cloudflare",
provider: "cloudflare",
persistent: true,
size: "small",
network: { mode: "allow-all" },
permissionMode: "ask",
lifecycle: { idleTimeoutSeconds: 600 },
});
| Field | Behavior |
|---|---|
persistent | true keeps one Container per agent while it is warm. false uses a new one per call |
lifecycle.idleTimeoutSeconds | How long a warm Container waits for the next command before it sleeps. Default 15 minutes, at most 6 hours |
network.mode | allow-all turns internet on, deny-all turns it off, restricted is rejected |
size | The nearest Cloudflare instance type, from standard-1 for tiny to standard-4 for large |
options | Only workspaceRoot and reservationKey |
- A Container that sleeps loses its files. Persistence keeps installs and files only while it stays warm, so keep setup in a step the agent can rerun.
- Changing
network.modeorsizereplaces a warm Container. - Workspaces are not supported. Attaching one fails.
onCreate,onResume,snapshotandlifecycle.maxLifetimeSecondsare rejected. Background jobs, suspend, resume and the Snapshot action are not available.config.harnessagents cannot run here. Usesandboxorlambda.- A
persistentsandbox gets the live dashboard terminal, a login shell in/workspace. It opens only on a running Container, so run a command first to wake one that slept. - The provider needs the deployment's Cloudflare bridge. Without it every run fails with an error saying the bridge is not configured. A self-hosted deployment deploys its own, see Sandbox internals.
worker
Runs bash in a V8 isolate on Cloudflare Workers: no container, no machine, nothing running between commands. The shell is just-bash, a bash written in TypeScript with its own in-memory disk and 81 built-in commands: cat, grep, sed, awk, jq, find, sort, cut, gzip, base64, sha256sum, date and the rest of the text toolbox, plus curl once internet is on. Use it for the cheapest compute an agent can get: a command starts in well under a second and costs only the milliseconds it ran.
export const box = defineSandbox({
name: "worker",
provider: "worker",
persistent: true,
network: { mode: "allow-all" },
permissionMode: "bypass",
timeout: 30,
});
| Field | Behavior |
|---|---|
persistent | true keeps the sandbox's files between calls, in storage. false runs every call on an empty disk |
network.mode | allow-all registers curl and turns internet on, deny-all has no network at all, restricted is rejected |
timeout | Seconds per call, at most 60: the isolate's CPU limit is the call's timeout |
options | Only workspaceRoot and reservationKey |
- Only built-ins run. There is no
python,node,git,npmor any binary, no process and no port; a command outside the 81 answerscommand not found. Usesandboxorlambdafor a real machine. - Files are the sandbox's whole state. A persistent sandbox restores them into a fresh shell on every call and stores what changed, up to 24 MiB on disk and 16 MiB compressed; an ephemeral one keeps nothing. The shell's own layout (
/bin,/dev,/proc) is rebuilt every time and never stored. - Each call runs in 128 MB of memory, and a command that never yields is stopped at the timeout by the isolate's CPU limit.
- The shell itself stops a script at 100,000 commands, 100,000 loop iterations or 100 nested function calls, with an error naming the limit. A job that big belongs on
sandboxorlambda. sizedoes nothing, like onlambda: every command gets the same 128 MB.snapshot,lifecycle,onCreateandonResumeare rejected. It cannot mount a bucket workspace, but a persistent one backs adiskworkspace (see Workspaces): each workspace folder, and each user conversation's folder, is its own disk. Background jobs, suspend, resume, the Snapshot action and the live terminal are not available.config.harnessagents cannot run here. Usesandboxorlambda.- Billing counts only the milliseconds each command took, waits included, plus one request each, inside Sandbox time; nothing idles. A
sleepcosts the same as a busy command, a fraction of a VM's idle time. - The provider needs the deployment's V8 Worker. Without it every run fails with an error saying the Worker is not configured. A self-hosted deployment deploys its own, see Sandbox internals.
Environment variables in every provider
envVars is a flat map of strings, read the usual way. Use $MY_API_BASE in shell, process.env.MY_API_BASE in Node, os.environ["MY_API_BASE"] in Python. Each run starts from an empty environment, so only the keys you declare reach it.