# 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 four 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` | An isolated runtime instance created from a template. | The agent's working machine for running tools, commands, and sessions. |
| `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 `Context` for process-level interaction patterns.
- Use `Volume` for durable memory.

## Agent Runtime vs Agent Memory

A common confusion is mixing compute state and durable state.

- Runtime state lives in a sandbox process and can disappear when sandbox is paused/deleted.
- Durable state 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`: soft timeout, typically leading to auto-pause.
- `hard_ttl`: hard runtime deadline, leading to runtime cleanup while preserving the sandbox identity.

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 sandbox filesystem as permanent storage.
- 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 sandbox power state and resume behavior before wiring long-lived workflows.
  </Card>
</CardGroup>
