Sandboxes
Select and configure the isolated filesystem and command backend.
Select a built-in sandbox in agent.md:
sandbox: e2bE2B sandboxes block outbound internet by default. Use the single-key form only when the agent must opt in to internet access:
sandbox:
e2b:
internet: enabledThe compiler expands the profile into the same sandbox adapter contract used
by the runtime. Supported built-in profiles are local, docker, daytona,
e2b, and modal.
Agent-owned environments
Add a named YAML profile only when the agent needs a custom image or build context:
sandbox/
coding.yaml
coding-environment/
Dockerfile
package-lock.json
smoke.sh# sandbox/coding.yaml
adapter: e2b
workingDirectory: /workspace
env: [GITHUB_TOKEN]
environment:
context: coding-environment
dockerfile: Dockerfile
verifyCommand: ./smoke.shSelect it with sandbox: coding. The compiler contains and hashes every file
in the environment, then records an immutable fingerprint. Deployment reuses a
matching provider artifact or builds and verifies a new one. A source change
creates a new fingerprint.
Filesystem contract
Hosted sandboxes expose a physical /workspace directory. Core file tools and
sandbox shell commands address the same files.
| Path | Access | Purpose |
|---|---|---|
/memory | policy-controlled writes | Durable memory documents. |
/skills | policy-controlled writes | Durable learned Skills. |
/history | read-only | Bounded conversation history. |
/files | read-only | Inputs and attachment projections. |
/workspace | writable | Durable versioned project files and outputs. |
The provider sandbox is a disposable working copy. The runtime hydrates the current committed workspace before use and syncs changes through state and blob storage. Provider snapshots may reduce startup time, but they do not replace durable workspace versions.
Sandboxes start lazily when a sandbox-backed capability needs one. Channel events and final delivery do not require sandbox startup.
Use local for trusted development, docker for local isolation, and a hosted
profile for production isolation. Forward only the environment variables that
the sandbox needs.