Skip to main content

Sandboxes

A sandbox is a Linux machine where your agent runs code. It gives the agent a bash tool with real bash, python3 and node on the PATH, and, together with a workspace, the file tools read, write, edit, glob and grep. An agent that only talks and calls APIs does not need one. Add a sandbox when the agent should run scripts, process files, install packages or drive a computer.

broods/index.ts
import { defineAgent, defineSandbox, env } from "broods";

export const box = defineSandbox({
name: "box",
provider: "lambda",
network: { mode: "deny-all" },
permissionMode: "ask",
timeout: 60,
});

export const myAgent = defineAgent({
name: "my-agent",
provider: { openai: { apiKey: env("OPENAI_API_KEY") } },
model: { provider: "openai", modelId: "gpt-5.5" },
sandboxes: [box],
});

Only provider is required. Without a workspace every bash call gets a fresh machine, so nothing survives between calls. Attach a workspace for files that persist, or make the sandbox persistent to keep installed packages and running processes.

Providers​

ProviderWhat it isWorkspace mountPersistentBackground jobsNetwork enforcement
sandboxBroods-hosted Firecracker VMyesyes, pause and resumeyes, with logs and stopall modes, domain + CIDR lists
lambdaAWS Lambda MicroVMyesyes, 8 h max per VMyes, with logs and stopallow-all or no internet
daytonaDaytona sandboxyesyes, native auto-stopyes, with logs and stopall modes, CIDR lists only
e2bE2B templatenoyes, pause on timeoutyes, no logs or stopallow-all only
vercelVercel Sandboxyesyes, named sandboxyes, with logs and stopall modes, domain + CIDR lists
cloudflareCloudflare Containernoyes, while warmnoallow-all or no internet
workerFast Cloudflare V8 Workernoyes, files in storagenoallow-all or no internet
machineYour own computernononoallow-all only
customYour own server over HTTPnononoallow-all only

Pick by where the code should run, then by whether files must outlive a call:

lambda is the provider a sandbox gets when the API or the dashboard creates one without naming it. sandbox is not on the hosted service yet. Attaching a workspace to an e2b, cloudflare, worker, machine or custom sandbox is rejected rather than falling back to provider storage. Setup, options and quirks per provider are on Providers. machine and custom have their own pages, Your computer and Your own server.

Configuration​

FieldDefaultWhat it does
providerlambdaCompute backend, from the table above
fallbackProvidernoneEphemeral only. Where a run goes when provider is out of capacity. Cannot be machine or custom
sizeprovider defaultSizes sandbox and cloudflare. Ignored on lambda, worker, daytona, e2b, vercel. Rejected on machine, custom. See Sizes
imagenonelambda only. obscura or browser boots a platform image with a headless browser, see Web browsing
snapshotprovider defaultImage or snapshot to boot from, in the provider's format, see Images
network{ mode: "deny-all" }Outbound access, see Network
permissionModeaskWhich tool calls need approval, see below
runtimesallAdvisory list of bash, python, node. The tool rejects obvious other runtimes. Not a security boundary
timeout30Seconds per call. Maximum 600, or 60 on worker
outputLimitBytes65536Output kept per call. Maximum 262144
envVarsnoneVariables injected into every run. Accepts env("NAME"). Encrypted at rest
optionsnoneProvider-specific settings, see Providers. On lambda, cloudflare and worker, only workspaceRoot and reservationKey
persistentfalseReserve a long-lived machine, see Persistent sandboxes
lifecyclenoneidleTimeoutSeconds, maxLifetimeSeconds. Needs persistent: true
onCreate, onResumenoneSetup commands. Need persistent: true, not supported on e2b, cloudflare, worker

envVars cannot override the runtime's reserved names. Those are PATH, HOME, LD_*, NODE_OPTIONS, PYTHONPATH, BASH_ENV, ENV, PROMPT_COMMAND, the background-job slots and the run identity BROODS_RUN_TOKEN, BROODS_AGENT_ID, BROODS_ACCOUNT_ID, BROODS_BASE_URL. Those entries are dropped. The host environment, including any cloud credentials, never reaches a run.

Every command that blocks also receives that run identity: BROODS_RUN_TOKEN is a short-lived bearer that reads this agent's runs, BROODS_AGENT_ID and BROODS_ACCOUNT_ID say who it is, and BROODS_BASE_URL is the API base when the deployment publishes one. See Calling the API from a sandbox.

A call that blocks is capped at 600 seconds on every provider. Background jobs are not bound by the call timeout.

Permission mode​

Moderead, glob, grepwrite, editbash
askautoaskask
editautoautoask
bypassautoautoauto

Approval requests go to the caller over the direct API or WebSocket. Channels cannot answer an approval, so a tool that needs one is denied on a channel turn. Use bypass or edit for sandboxes that serve channel agents.

Network​

ModeMeaning
allow-allOutbound internet allowed
deny-allNo outbound internet
restrictedOnly allowDomains and allowCidrs, where the provider can enforce them
network: {
mode: "restricted",
allowDomains: ["api.example.com"],
allowCidrs: ["10.0.0.0/8"],
},
Providerallow-alldeny-allrestricted
sandboxalloweddenieddomain and CIDR allowlist
lambdaalloweddeniedsame as deny-all. Allowlists are rejected at validation
daytonaalloweddeniedCIDR allowlist only. Domain lists are ignored with a warning
vercelalloweddenieddomain and CIDR allowlist
cloudflarealloweddeniedrejected
workeralloweddeniedrejected
e2ballowedrejectedrejected
machineallowedrejectedrejected
customallowedrejectedrejected

A provider that cannot enforce a mode rejects the config instead of quietly granting more access. Background jobs report back to the platform over the network, so under deny-all a job still runs but its result has to be polled. See Persistent sandboxes.

Sizes​

SizevCPUMemoryDiskTier
tiny0.250.5 GB8 GBfree
xsmall0.51 GB8 GBfree, default
small12 GB8 GBpaid
medium24 GB16 GBpaid
large48 GB32 GBpaid

size sizes the machine on sandbox and cloudflare only. Every other provider sizes its machines its own way. The dashboard shows a size only when it is known to be true: the provider reported it, or Broods set it itself. Anything else shows as ?, never a guess; hover it to see why.

ProviderWhat size doesSize the dashboard shows
sandboxCreates the VM at that size, tiny rounded up to 0.5 vCPUThe resources the VM was created with
cloudflareStarts the nearest instance type: tiny and xsmall standard-1, then standard-2 to 4That instance type: 0.5 vCPU, 4 GB, 8 GB up to 4 vCPU, 12 GB, 20 GB
lambdaNothing4 vCPU, 8 GB, 8 GB disk: the MicroVM's ceiling, every MicroVM the same
daytonaNothing, the snapshot and Daytona's defaults size itvCPU, memory and disk Daytona reports
e2bNothing, the template sizes itvCPU and memory E2B reports. Disk is ?, E2B does not report it
vercelNothing, Vercel sizes itvCPU and memory Vercel reports. Disk is ?, Vercel does not report it
workerNothing, every isolate is the same?: an isolate has no machine, each command gets 128 MB of memory
machineRejectedCPUs, memory and home disk of your computer, as broods machine reports them
customRejectedNo instance row: Broods cannot see your server's hardware

When a sandbox's size is not known, the whole size shows as ?. Daytona reports on every use, so its ? clears the next time the sandbox runs, as does a lambda or cloudflare sandbox recorded before Broods verified sizes. Vercel's clears once Vercel reports a size. Broods reads an e2b size, and workdir fixes a sandbox size, only when the sandbox is created, so an older or unread one stays ? until it is recreated.

On the managed service, sandbox time on platform credentials counts at the machine's size when Broods knows it, and at the size derived from the config when it shows ?, except on lambda: a MicroVM counts at its 1 vCPU / 2 GB baseline, plus the vCPU and memory it bursts above that while in use, see Persistent sandboxes. A machine sandbox, and one on your own provider credentials, does not count.

Images​

Set snapshot to boot a prebuilt image instead of the provider default. Bake heavy toolchains into an image once rather than installing them on every cold start. It is the one field for this on every provider, and each provider reads it in its own format.

Providersnapshot namesThe Snapshot action saves
sandboxa workdir imagethe running instance
lambdaa MicroVM image ARN, in the default image's AWS account and regionevery file changed since the machine started, built as a new image in a few minutes
daytonaa Daytona snapshotthe sandbox filesystem, as a Daytona snapshot
e2ban E2B template or snapshotthe sandbox, as an E2B snapshot. E2B pauses it while it captures
vercela Vercel image, such as vercel/sandbox/python:3.14, or a snap_ idthe sandbox, as a Vercel snapshot that does not expire. Vercel stops it, and its next call resumes it
cloudflarerejected. The bridge Worker's image sets the machinenot available
workerrejected. A persistent sandbox's files are its whole statenot available

The Snapshot action runs on a running instance of a persistent sandbox and saves it under a name you pick. Any sandbox of the same provider on the same stage can then pin it, with the Snapshot select on its node or snapshot in code. On lambda, workspace files stay in the workspace, and deleted files are not carried over.

A snapshot is a copy of a sandbox's disk, so it is locked to the stage of the sandbox it was taken from. A development sandbox cannot boot a production snapshot, whoever configures it: the config plane answers 400 to an API call, a dashboard save or a broods deploy that points a sandbox at another stage's snapshot, and core refuses to boot one on every provider. A sandbox created through the API with no stage boots only snapshots taken on a sandbox with no stage. Names are unique per stage, so the same name on two stages is two snapshots. The dashboard shows each snapshot's stage, and the Snapshot select offers only the current stage's. To use the same image on another stage, take the snapshot again from a sandbox on that stage. Snapshots taken before snapshots recorded their stage show "no stage" and boot nowhere; take them again.

A snapshot boots only on the provider that made it. A MicroVM image, a workdir image, a Daytona snapshot, an E2B template and a Vercel snapshot are different formats held by different clouds, and none of them imports another, so there is no snapshot that moves between providers. Put setup you need everywhere in onCreate, or bake it into each provider's image. Daytona, E2B and Vercel keep snapshots in the provider account behind the sandbox's credentials, so only a sandbox using the same credentials can boot one. Broods does not delete them, so remove ones you no longer need in the provider console.

On daytona, options.image builds the sandbox from a Docker image when it is created, instead of booting a snapshot. Set one or the other.

On lambda, a snapshot starts from a running instance and comes back as the image the next machine boots:

The dashboard Snapshots view shows which image each running instance booted from.

On lambda, image: "obscura" or image: "browser" boots a platform image with a headless browser, see Web browsing. With snapshot set too, the machine boots the snapshot and image names the variant it was built from, so a snapshot of an Obscura sandbox keeps browse working. The dashboard sets it when you pick the snapshot. image cannot be combined with fallbackProvider.

A persistent lambda sandbox can also run a stdio MCP server from its image, such as obscura mcp, and keep it alive between calls. See Run a server in a sandbox.

More than one sandbox​

An agent lists its sandboxes in sandboxes. The first one is the default. bash without a workspace runs there, a workspace without its own sandbox mounts it, and a harness runs on it. Add more when one agent needs a second kind of machine, such as a browser image or a deny-all box.

export const myAgent = defineAgent({
name: "my-agent",
sandboxes: [general, offline], // general is the default
});

The model reaches a later sandbox by passing its name to bash, here sandbox: "offline". The file tools never run there, and no workspace is mounted, so nothing written there reaches durable storage. A named sandbox wins over a workspace passed in the same call. A machine sandbox anywhere in the list also gives the agent a computer tool. Each sandbox may appear once, and only the first may also back a workspace.

What the model sees​

With a workspace, bash starts in the workspace directory and file tools take relative paths. Tell the model to use relative paths such as analysis.json or src/index.ts. Provider mount paths belong in logs, not prompts.

write notes/a.txt # creates parent folders
read notes/a.txt # numbered lines
edit notes/a.txt # exact, unique string replacement
glob **/*.py # newest first
grep TODO # ripgrep, or grep -E without it
bash python3 notes/run.py

Without a workspace only bash exists and each call is a new machine, so write and run in one command:

cat <<'EOF' > /tmp/run.py
print("ok")
EOF
python3 /tmp/run.py

bash also takes pty: true for programs that refuse to run without a terminal. The output then merges stderr into stdout and ends lines with CRLF, so leave it off when you need byte-exact output.

bash returns stdout and stderr as text. Output is truncated at outputLimitBytes.

Examples​

DemoShows
sandboxStateless bash on sandbox
sandbox-lambdaStateless bash on lambda
sandbox-workspaceFile tools on a workspace
sandbox-workspace-persistentPersistent sandbox and background jobs
sandbox-multipleA default sandbox plus a deny-all one

How executors, mounts and credentials work inside the platform is covered in Sandbox internals.