API + guides
01Documentation
Core Concepts
This page explains Sandbox0 from an AI agent developer perspective: how to think about runtime state, isolation, and long-running workflows.
The Mental Model#
Think in six building blocks:
| Concept | What It Is | Why Agent Developers Care |
|---|---|---|
Template | The runtime blueprint (image, resources, defaults). | Defines your agent's execution environment and startup behavior. |
Sandbox | Durable identity and configuration for an isolated environment. | The agent's working machine identity across runtime generations. |
| Root filesystem | The sandbox writable filesystem checkpointed during pause/resume. | Keeps files written inside the sandbox available when compute is released and later restored. |
Context | A one-shot command or stateful REPL process inside the sandbox. | Provides direct command and REPL execution for active work. |
| Supervised session | A stable process identity with attempts, lifecycle policy, and a replayable event journal. | Keeps long-running work controllable across client reconnects and sandbox runtime replacement. |
Volume | Persistent storage decoupled from sandbox lifecycle. | Keeps knowledge, artifacts, and checkpoints across sandbox recreation. |
The key idea is separation of concerns:
- Use
Templatefor environment consistency. - Use
Sandboxfor isolated execution. - Use the root filesystem for same-sandbox file continuity across pause/resume.
- Use
Contextfor one-shot commands and REPL interaction. - Use supervised sessions for long-running, reconnectable, restartable processes.
- Use
Volumefor durable, shareable, or snapshot-ready memory.
Agent Runtime vs Agent Memory#
A common confusion is mixing compute state and durable state.
- Process state lives in the sandbox runtime and disappears when the runtime is paused or replaced. A supervised session can preserve its identity, specification, and journal, then start a new attempt; it does not preserve process memory or sockets.
- Sandbox0 restores the writable root filesystem checkpoint for paused sandboxes, so files written outside mounted volumes survive pause/resume for the same sandbox identity.
- The rootfs checkpoint is not a Volume. It is not shareable across sandboxes, does not expose volume snapshot/fork APIs, and is deleted with the sandbox identity.
- Durable state that must survive sandbox delete or
hard_ttl, needs snapshots, or needs sharing outside the sandbox identity should be written to volumes or external systems. - If your agent must recover after failures or redeploys, treat sandbox runtime as ephemeral and volumes as the source of truth.
ℹ
Design for restartability: assume any sandbox can be replaced, and your agent should still continue from persisted checkpoints.
Lifecycle and Time Limits#
Sandbox0 uses lifecycle controls to balance responsiveness and cost:
ttl: runtime soft timeout, leading to checkpointed pause.hard_ttl: hard sandbox deadline, deleting identity and durable state even if paused.
For agents, this means:
- Keep short
ttlfor bursty workloads. - Extend lifecycle only when needed.
- Persist progress frequently so expiration is not a data-loss event.
Isolation and Security Boundary#
Each sandbox is isolated by default. This is critical for agent workloads that execute untrusted code or process user-provided inputs.
From an agent architecture perspective:
- Isolation limits blast radius between tasks and tenants.
- Network policy controls where the agent can call out.
- Auth tokens define what the agent can operate on in the control plane.
Use least privilege by default: only grant the permissions and network egress your workflow requires.
Choosing the Right Interaction Pattern#
Choose execution style based on task shape:
| Pattern | Best For | Tradeoff |
|---|---|---|
| REPL context | Multi-step evaluation with intermediate variables and working-directory state. | The REPL process does not recover across runtime replacement. |
| One-shot context | Deterministic, idempotent, task-based jobs. | No in-process continuity between runs. |
| Supervised session | Long-running workers, reconnectable terminals, and restartable processes. | The application must tolerate new process attempts after runtime replacement. |
In practice, many agents combine both:
- REPL context during active reasoning.
- One-shot jobs for isolated tools or side effects.
- Supervised sessions for workers that must remain independently controllable.
Multi-Agent and Parallelism#
Sandbox0 works well for fan-out workloads:
- Run separate sandboxes per task for strong isolation.
- Share durable outputs through volumes or external storage.
- Keep coordination outside the sandbox boundary (scheduler/orchestrator layer).
This keeps each agent worker simple while allowing safe parallel execution.
Common Pitfalls#
- Treating the sandbox root filesystem as permanent storage after sandbox delete or
hard_ttl. - Using a single long-lived sandbox for unrelated tasks.
- Skipping checkpoint persistence until task end.
- Over-permissive auth/network settings in early prototypes that leak into production.