#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:

The key idea is separation of concerns:

• Use Template for environment consistency.
• Use Sandbox for isolated execution.
• Use the root filesystem for same-sandbox file continuity across pause/resume.
• Use Context for process-level interaction patterns.
• Use Volume for 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 deleted.
• 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.

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 ttl for 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:

In practice, many agents combine both:

• Stateful loop during active reasoning.
• One-shot jobs for isolated tools or side effects.

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.

Next Steps#