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

# Sandboxes

Firecracker microVMs claimed from warm pools on the B3OS node, with commands, files, a terminal, ports, snapshots and a scoped API grant.

A sandbox is a Firecracker microVM with its own kernel, claimed from a pool of microVMs that were restored from a snapshot ahead of time. Your request does not wait for a boot. Use one to run code an agent wrote, to give an agent a computer of its own, or to run the agent itself on the node, next to the model the node serves.

## Create a sandbox

**curl**

```bash
    curl -s https://beta-api.b3os.org/v1/sandboxes \
      -H "Authorization: Bearer $B3OS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"template": "base", "vcpu": 2, "memory_mib": 2048, "timeout_s": 900}'
    ```
  **TypeScript**

```ts
    import { B3OS } from "@b3os/sdk";

    const b3os = new B3OS();
    const sandbox = await b3os.sandboxes.createSandbox({ template: "base", vcpu: 2, memory_mib: 2048, timeout_s: 900 });
    console.log(sandbox.id, sandbox.status, sandbox.expires_at);
    ```
  **Python**

```python
    from b3os import B3OS

    b3os = B3OS()
    sandbox = b3os.sandboxes.create_sandbox({"template": "base", "vcpu": 2, "memory_mib": 2048, "timeout_s": 900})
    print(sandbox["id"], sandbox["status"], sandbox["expires_at"])
    ```
  **MCP**

```text
    Start a sandbox and run `python3 -c "import sys; print(sys.version)"` in it.
    ```

    The agent calls `sandbox_create`, then `sandbox_exec` with the sandbox ID and the command, and `sandbox_delete` when it is done.

The sandbox comes back `running`. Its `timing` shows the claim.

| Field | Default | Meaning |
|---|---|---|
| `template` | `base` | The template to start from, by name or `tpl_` ID |
| `snapshot` | none | Restore one of your [snapshots](/sandboxes/snapshots) instead of a template |
| `vcpu` | 1 | Virtual CPUs, up to your plan's maximum (2 in the beta) |
| `memory_mib` | 512 | Memory in MiB, up to 2048 in the beta |
| `disk_gib` | the template's | Disk size |
| `timeout_s` | 300 | Lifetime in seconds from creation or from the last extension; the beta allows up to an hour |
| `on_idle` | `stop` | What happens at `expires_at`: `stop` destroys the sandbox, `pause` keeps it for a later resume |
| `env` | none | Environment variables, returned as given |
| `secrets` | none | Environment variables never returned or logged: a value, or a field of a vault connection |
| `ports` | none | Up to 8 ports to reach from outside; see [ports](/sandboxes/ports) |
| `api` | no access | What code inside may call on B3OS; see [agents in sandboxes](/sandboxes/agents) |
| `egress` | `public` | Where the sandbox's traffic may go: `public`, `allowlist` or `deny` |

## Templates

`GET /v1/sandboxes/templates` lists the templates with their contents and default sizes:

| Template | Contents |
|---|---|
| `base` | Ubuntu 24.04 with Python 3.12, Node 24 and git |
| `code-interpreter` | `base` plus a Jupyter kernel for [`run_code`](/sandboxes/commands#run-code-in-a-kernel), in Python and JavaScript |
| `agent` | `base` plus the Claude Agent SDK, the OpenAI Agents SDK and LangGraph |

## Lifecycle

```mermaid
stateDiagram-v2
  [*] --> running: create
  running --> paused: pause
  paused --> running: resume
  running --> stopped: delete or timeout
  paused --> stopped: delete or timeout
  running --> failed: microVM crashed
```

- **Extend** with `POST /v1/sandboxes/{sandbox_id}/timeout` and a new `timeout_s`, counted from now. It works on running and paused sandboxes.
- **Pause** freezes the vCPUs and keeps memory and disk on the node; **resume** continues exactly where it stopped, with the guest clock corrected. See [snapshots and pausing](/sandboxes/snapshots).
- **Delete** stops the sandbox and destroys its memory and disk. It returns the stopped sandbox with its final usage; snapshots taken from it are kept.
- A stopped sandbox cannot be restarted. Calls that need a running one fail with [`sandbox_not_running`](/errors#sandbox_not_running), whose `current_status` says why.

Each sandbox starts with a fresh identity (new entropy, machine ID and clock), even when many come from one snapshot, so no two sandboxes share random state.

## Networking

A sandbox has no network card. Its outbound traffic leaves through the node's egress guard, which allows the public internet by default and never the node's network, loopback or cloud metadata addresses. Narrow it per sandbox:

```json
{ "template": "base", "egress": { "mode": "allowlist", "allow": ["github.com", "*.githubusercontent.com"] } }
```

`deny` blocks outbound traffic entirely. Inbound traffic reaches a sandbox only through its declared [ports](/sandboxes/ports).

## Inside the sandbox

The environment includes:

| Variable | Value |
|---|---|
| `B3OS_API_URL` | `http://127.0.0.1:7700`, the B3OS API without a key |
| `B3OS_SANDBOX_ID` | The sandbox's `sbx_` ID |
| `B3OS_PROJECT` | Your project ID |
| `B3OS_PORT_BASE_PATH` | `/sbx/<host_id>`, the fixed start of every port preview path |

The B3OS SDK and CLI detect `B3OS_API_URL` and use it on their own.

## Billing and scopes

A running sandbox bills `sandboxes.vcpu_ms` (CPU time it used) and `sandboxes.gib_ms` (allocated memory times wall time). A paused sandbox bills no CPU time. Whether it bills memory while paused is still being settled for the beta; the sandbox's `usage` shows what it was charged.

| Scope | For |
|---|---|
| `sandboxes:write` | Create, delete, pause, resume, snapshot and extend sandboxes |
| `sandboxes:run` | Run commands and code, read and write files, open terminals, read logs, mint port URLs |
| `sandboxes:read` | List and read sandboxes, snapshots and templates |

## Guides

**[Commands, code and files](/sandboxes/commands)**

Exec, streaming output, background processes, run_code, files and a terminal.
  **[Ports and previews](/sandboxes/ports)**

Reach a server in the sandbox through a signed URL.
  **[Snapshots and pausing](/sandboxes/snapshots)**

Pause and resume, save a sandbox, and start new ones from it.
  **[Agents in sandboxes](/sandboxes/agents)**

Grants, the in-sandbox API, secrets from the vault and nested sandboxes.

[Limits and FAQ](/sandboxes/limits) lists the caps and the common questions.