# 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 `Template` for environment consistency.
- Use `Sandbox` for isolated execution.
- Use the root filesystem for same-sandbox file continuity across pause/resume, and named rootfs snapshots for reusable restore points.
- Use `Context` for 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; it does not preserve process memory or sockets.
- Sandbox0 restores the writable root filesystem checkpoint for paused sandboxes, so files survive pause/resume for the same sandbox identity.
- 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; 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.

<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 |
|--------|----------|----------|
| 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 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.

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