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 five 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. |
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, and named rootfs snapshots for reusable restore points.
- Use
Contextfor one-shot commands and REPL interaction. - Use supervised sessions for long-running, reconnectable, restartable processes.
Agent Runtime vs Agent Memory#
A common confusion is mixing compute state and durable state.
- Process state lives in the sandbox runtime and disappears on default filesystem-only pause or replacement. Explicit experimental memory pause/resume can retain supported process state. A supervised session can preserve its identity, specification, and journal, then start a new attempt; the session abstraction alone does not preserve process memory or sockets. Retaining supported process state requires a compatible memory checkpoint.
- Sandbox0 restores the writable root filesystem checkpoint for paused sandboxes, so files in the writable RootFS survive successful pause/resume for the same sandbox identity. Runtime-only mounts such as
/tmpare excluded from filesystem-only checkpoints. The Files API can inspect persistent files without waking compute, and supports edits during filesystem-only pauses. - A named rootfs snapshot can initialize a new sandbox, restore a paused sandbox, or serve as the source for a fork.
- Current rootfs state is deleted with the sandbox identity. Create a named snapshot before deletion when you need a reusable restore point, and account for snapshot expiry and retention limits; use an external system for data that must be shared independently of sandbox identity.
- If your agent must recover after failures or redeploys, treat process state as ephemeral and checkpoint progress to the rootfs or an external system. Abrupt node loss can recover the last regionally committed RootFS cut, not unpublished local writes; guest
fsyncalone does not confirm regional publication.
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 its current durable state even if paused.
Both default to 0 (disabled). A soft TTL is a deadline, not a guarantee that active commands will finish before pause. Refresh or update it explicitly when work needs more time. Refresh also renews an enabled hard TTL from the refresh time.
For agents, this means:
- Keep short
ttlfor bursty workloads. - Extend lifecycle only when needed.
- Persist progress to the writable RootFS before a filesystem-only pause. Preserve outputs in a retained snapshot or external storage before
hard_ttldeletes the sandbox; writing files inside it alone does not protect against deletion.
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 these patterns:
- 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 an external storage or coordination service when they must cross sandbox identities.
- 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.