> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orcapods.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandboxes

> Optional per-agent compute environments allocated when a session starts. Surfaced in the dashboard as Environments.

## What is a Sandbox?

A **sandbox** is an optional, isolated **compute environment attached to an agent**. When you configure a sandbox on an agent's [profile](/concepts/profiles), Orca allocates one when a session starts, and the agent's tools run inside it.

<Note>
  In the dashboard, live sandbox leases are shown on the **[Environments](/dashboard/environments)** page. "Sandbox" (the profile setting) and "Environment" (the dashboard surface) refer to the same thing — the concept is named **Environments** in the UI.
</Note>

## With vs. without a sandbox

|           | No sandbox (default / `nil`)     | Sandbox enabled                                                   |
| --------- | -------------------------------- | ----------------------------------------------------------------- |
| Tools     | Legacy **in-process** tools only | Shell tools, script execution                                     |
| Skills    | Instruction-only skills          | Skills that **run scripts**                                       |
| Isolation | Runs in the conductor process    | Isolated per-agent environment                                    |
| State     | None to preserve                 | Filesystem preserved; memory preservation depends on the provider |

If a profile has no sandbox, the agent falls back to the in-process tool set. **Skills that run scripts and any shell tools require a sandbox** — see **[Skills](/concepts/skills)**.

## Configuration

A sandbox is described on the profile by a `SandboxSpec`:

| Field         | Meaning                                                                                                                               |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `provider`    | The sandbox provider to use, e.g. `e2b` or `daytona`.                                                                                 |
| `template`    | The provider-scoped image / template id to boot from.                                                                                 |
| `resources`   | Compute caps: `cpu` (millicores), `memoryMB`, `diskMB`, and a hard wall-clock `timeout`. Zero values mean "use the provider default." |
| `idleTimeout` | Idle TTL — how long an idle sandbox is kept before it is reclaimed.                                                                   |

```json theme={null}
{
  "sandbox": {
    "provider": "e2b",
    "template": "base-python",
    "resources": { "cpu": 1000, "memoryMB": 1024, "diskMB": 2048 },
    "idleTimeout": "10m"
  }
}
```

## Lifecycle: pause and resume

A sandbox is allocated when a session starts. When it goes idle, it can be **paused** rather than destroyed.

```mermaid theme={null}
stateDiagram-v2
    [*] --> Allocated: session starts
    Allocated --> Running: tool call
    Running --> Paused: goes idle
    Paused --> Running: next tool call (fs + memory restored)
    Paused --> Reclaimed: idle TTL elapses
    Reclaimed --> [*]
```

A paused sandbox preserves its filesystem. Providers with a memory-suspend primitive can also preserve process memory; other providers may implement pause as stop/start, which discards memory while retaining disk.

Session-scoped agent-workers account for that fallback in outbound mode: after each run they checkpoint runtime conversation state to sandbox disk, and they restore it before polling for more work after a restart. They also upload a best-effort durable copy to the runner for recovery if the sandbox itself is lost. Once the idle TTL elapses, the lease is reclaimed.

## Related

<CardGroup cols={3}>
  <Card title="Environments" icon="server" href="/dashboard/environments">
    See and manage live sandbox leases.
  </Card>

  <Card title="Profiles" icon="id-card" href="/concepts/profiles">
    Where the sandbox is configured.
  </Card>

  <Card title="Skills" icon="puzzle-piece" href="/concepts/skills">
    Skills that run scripts need a sandbox.
  </Card>
</CardGroup>