Sandboxes
Sandboxes are isolated execution environments where agents can browse, run shell commands, or drive a virtual desktop without risking the host.
A sandbox is a short-lived, isolated environment that an agent can drive through tool calls. Nova Admin uses E2B for both code-only sandboxes and full desktop sandboxes, with the @e2b/desktop package for GUI workflows.
When to use a sandbox
- The agent needs to execute code with arbitrary dependencies.
- The agent needs a browser to scrape, log in, or click through a flow that has no API.
- The agent needs to run a shell command that should not touch production credentials.
- You want a clean, reproducible environment per run.
How sandboxes plug in
Sandboxes show up to agents as integration actions on the sandbox provider. Typical actions:
| Action | What it does |
|---|---|
sandbox_create | Spins up a new E2B environment, returns an ID. |
sandbox_exec | Runs a shell command inside the sandbox. |
sandbox_read_file / sandbox_write_file | Move files in and out. |
sandbox_browser_navigate | Drive the headless browser. |
sandbox_desktop_screenshot | Capture the virtual desktop. |
A sandbox auto-destroys on a timeout or when the run completes. Files you want to keep must be uploaded to a durable store (Cloud Storage, Firestore) before teardown.
Limits
- Lifetimes are bounded, so long-running tasks need to checkpoint state.
- Outbound network is open, but the agent's credentials never enter the sandbox unless you explicitly pass them through.
- Each sandbox costs money. The platform tracks spend per agent in the Costs tab.
See also
- Observability — every sandbox action shows up in the run timeline.
Governance & Safety
How Nova Admin keeps autonomous agents safe. Covers HITL approvals, the outbound allowlist, invocation gating, budget enforcement, and memory retention. Most controls ship observe-first behind editable config flags.
Capsules
Capsules are portable bundles of Nova context that expose selected tools and resources through one scoped key.