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

ConceptWhat It IsWhy Agent Developers Care
TemplateThe runtime blueprint (image, resources, defaults).Defines your agent's execution environment and startup behavior.
SandboxAn isolated runtime instance created from a template.The agent's working machine for running tools, commands, and sessions.
ContextA process/session inside the sandbox (for example REPL-like or one-shot execution).Controls whether state is preserved across turns or reset each run.
VolumePersistent 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.
ℹ

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: soft timeout, typically leading to auto-pause.
  • hard_ttl: hard deadline, leading to deletion.

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:

PatternBest ForTradeoff
Stateful sessionMulti-step reasoning with intermediate variables/process state.Higher complexity in lifecycle and cleanup.
One-shot executionDeterministic, 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.

What to Learn Next#

If this mental model is clear, move to implementation details:

Sandbox

Lifecycle, contexts, files, network, ports, and runtime operations

Template

Define stable execution environments and warm pools

Volume

Persist agent data across sandbox lifecycles