# 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 process/session inside the sandbox (for example REPL-like or one-shot execution). | Controls whether state is preserved across turns or reset each run. |
| `Volume` | Persistent storage decoupled from sandbox lifecycle. | Keeps knowledge, artifacts, and checkpoints across sandbox recreation. |

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.

<Callout variant="info">
Design for restartability: assume any sandbox can be replaced, and your agent should still continue from persisted checkpoints.
</Callout>

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

| Pattern | Best For | Tradeoff |
|--------|----------|----------|
| Stateful session | Multi-step reasoning with intermediate variables/process state. | Higher complexity in lifecycle and cleanup. |
| One-shot execution | Deterministic, idempotent, task-based jobs. | No in-process continuity between runs. |

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

<CardGroup>
  <Card title="Overview" href="/docs/sandbox" cta="Continue">
    Learn the sandbox lifecycle and the runtime APIs available to each isolated environment.
  </Card>

  <Card title="Pause And Resume" href="/docs/sandbox/pause-resume" cta="Continue">
    Control checkpointed pause and resume behavior before wiring long-lived workflows.
  </Card>
</CardGroup>
