Skip to main content

Persistent sandboxes

By default a sandbox is ephemeral. Each call creates a machine, runs, and destroys it. Only workspace files survive. Set persistent: true to reserve a long-lived machine instead, so installed packages, code on local disk and running processes survive between calls. It scales down when idle and wakes on the next call.

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

export const devBox = defineSandbox({
name: "dev-box",
provider: "sandbox",
network: { mode: "allow-all" },
permissionMode: "bypass",
persistent: true,
lifecycle: {
idleTimeoutSeconds: 1800, // scale down after 30 min idle, default 900
maxLifetimeSeconds: 86400, // rebuild once a day, optional
},
onCreate: ["python3 -m venv $HOME/.venv"],
onResume: ["test -x $HOME/.venv/bin/python"],
});

When to use it​

Stay ephemeral unless the agent needs state between calls. Ephemeral runs hold resources only for the seconds a command runs, and there is nothing to leak. Give an ephemeral sandbox a fallbackProvider so a full provider hands the run to a second one instead of failing the tool call.

Reserve a machine for iterative coding sessions, long-running work, background jobs, or when you want the live terminal in the dashboard. Avoid it for one-shot tasks.

On lambda, a reserved MicroVM counts against your account's allocated memory quota while it runs and while it is suspended. A handful of persistent agents can exhaust the quota, and every new launch then fails with ServiceQuotaExceededException and the message "maximum allocated memory limit". Terminate reservations you are done with from the dashboard, under Sandbox, Instances. That frees the quota at once instead of waiting for the idle window. If no reservation is running and launches still fail, the quota itself is too low: check "Max allocated ARM_64 MicroVM memory" for your region in AWS Service Quotas, which can start at 0 on a new account, and request an increase.

Which machine you get​

A persistent sandbox reserves one machine per workspace that mounts it. A persistent sandbox the agent uses without a workspace reserves one machine per agent and sandbox. Pointing the agent at a different sandbox record gives it that record's machine.

Set options.reservationKey to choose the reservation yourself. Two sandboxes with the same key share one machine, which is how several agents deliberately work on one box. Keys are scoped to your account, so the same string on another account names a different machine.

Only the workspace mount outlives the reservation. When a reservation ends, local disk is gone.

How one tool call finds its machine:

Idle and lifetime​

A reserved machine moves through these states. Only the workspace survives a recreate or a release.

ProviderOn idleResumeLimits
sandboxpause and standbyon the next exec
lambdasuspended to a snapshot of memory and disk1 to 10 sa MicroVM lives at most 8 hours, then it is recreated
daytonastopped via autoStopInterval, disk kepton the next call
e2bpaused, files, installs and processes kepton the next call
vercelstopped, filesystem kepton the next calleach call keeps the session open; 24 h cap (45 min on Hobby)
workernothing to stop; files kept in storageon the next callno idle time: nothing runs between commands

idleTimeoutSeconds defaults to 900 and can be at most 7 days. maxLifetimeSeconds is an optional ceiling on age since creation, at most 30 days. It is checked when a call acquires the machine, so it never interrupts a running command; the call that trips it boots a fresh machine. On Vercel the idle window is at most 24 hours, the longest session Vercel allows on Pro and Enterprise (45 minutes on Hobby). Each call keeps the session open one idle window past its own end, so a busy sandbox is never stopped mid-command until it reaches that session cap.

Idle scale-down never pauses a machine while a background job runs, except on Vercel: there a job keeps the session open only while something polls it, so a job left unpolled for longer than the idle window stops with the session. Set idleTimeoutSeconds above the job's run time.

On the managed service, sandbox time counts from each use until idleTimeoutSeconds scales the machine down, because the provider bills that idle stretch too. A suspended lambda MicroVM keeps counting a little for its stored snapshot until it resumes or is released. A lambda MicroVM that bursts above its 1 vCPU / 2 GB baseline also counts the extra vCPU and memory while it is used, the way AWS bills it. A shorter idle timeout uses less of the plan's monthly sandbox time. An worker sandbox has no idle stretch: it counts only the milliseconds its commands ran, plus one request each. The dashboard shows it under Resources on a project's Usage tab, and for all of the org's projects under Settings → Organization → Usage.

Setup commands​

onCreate runs once, when the machine is first reserved. onResume runs when it is acquired again. Both need persistent: true.

ProviderWhen onResume runs
sandbox, daytona, lambdaon every call
vercelonly when a stopped sandbox resumes
e2bnot supported. Put setup in the E2B template
cloudflare, workernot supported. The Worker sets the machine

Make onResume idempotent, since on most providers it runs every time.

Background jobs​

On a persistent sandbox bash accepts background: true. The command starts as a detached job and the tool returns a statusId at once:

bash { command: "uv run train.py", background: true } → statusId
async_status { statusId } → running, completed with logs, or failed
async_status { statusId, action: "logs" } → tail the output
async_status { statusId, action: "stop" } → stop the job

When the job exits it reports back, the conversation resumes with the result, and the follow-up goes to wherever the turn came from:

Turn came fromResult delivered
A chat channelposted into the same chat
WebSocketpublished to the conversation stream, replayed on reconnect
Direct or async APIsettled on the run status, and lifecycle webhooks fire agent.finished

The model does not have to poll, though it can. async_status is added automatically when the agent has a workspace on a persistent sandbox. A persistent sandbox used with no workspace does not get it.

  • Auto-delivery needs the sandbox to reach the Broods gateway, so use network.mode: "allow-all" or allow that host. Without egress the job still runs and async_status polling still works.
  • logs and stop exist only where the provider exposes live job control. E2B launches jobs natively and offers status only.
  • sandbox, daytona and vercel run at most 10 background jobs at once.
  • A job killed because its machine was recreated reports failed, never "running forever".
  • No account key enters the sandbox. The job reports back with a short-lived token of its own.
  • Discord delivers a late reply with the bot token, so the bot needs the Send Messages permission in that channel.

Terminals​

bash with pty: true gives the agent a real terminal for programs that need one. It works on every provider. See What the model sees.

The dashboard gives you a live terminal on sandbox and lambda instances, under Sandbox, Instances. It is a real TTY, and connecting resumes a suspended instance. Other providers get a command runner capped at 30 seconds and 64 KiB per command. A lambda reservation made before terminals shipped has to be terminated and reserved again once to get one; the API answers 409 with that hint.

Cleanup​

  • Deleting a workspace, a sandbox config or the account from the dashboard or the API tries to terminate its reserved machines, then deletes it. Deleting a workspace this way also removes its files, unless it uses your own bucket.
  • A CLI sync (broods deploy --prune, or a resource removed under broods dev) tries to terminate the reserved machines first. A sandbox config is kept while a reservation is still live: the prune lists it in a warning, and a single delete answers 409. Terminate the reservation from the dashboard and run it again. A workspace is deleted after the terminate attempt. The CLI path does not remove workspace files.
  • A reservation that has not been used for 7 days expires, and the machine is deleted at its provider.
  • Terminate a reservation from the dashboard to free it immediately.

See Providers for per-provider details and Sandbox internals for how reservations are tracked.