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

# Sandbox runtime for agents

> Plug boxd in as the execution layer. Each task, workspace, or session runs in its own VM.

Your coding agent runs anywhere -- a laptop, a server, a serverless function -- and plugs boxd in as the execution layer underneath it. Each task gets its own VM with real Linux, persistent disk, fork on retry, and sub-ms resume. The agent never has to live on the box; the box just shows up when work arrives.

## Two ways to wire an agent

Both are first-class. Pick the one that matches how your agent is structured.

|                        | Agent inside the VM                        | Sandbox runtime                         |
| ---------------------- | ------------------------------------------ | --------------------------------------- |
| Where the agent lives  | On the VM                                  | On your laptop, server, or function     |
| How it talks to the VM | `claude` / `opencode` / `boxd` CLI on PATH | boxd SDK (TypeScript or Python)         |
| One VM is              | One agent session                          | One task / workspace / session          |
| Best for               | Interactive sessions, fan-out from inside  | Pluggable backend in an agent framework |
| See                    | [Agent sandboxes](/agents/agent-sandboxes) | This page                               |

## Why a per-task VM

* **Isolation.** Real KVM microVM with its own kernel. The agent has root inside it and no path to the host or to other sandboxes. Run untrusted code, `rm -rf /`, kernel modules, nested Docker. None of it touches anything outside the box.
* **Persistence.** The 100 GB disk survives across exec calls. Install the toolchain once; reuse it for the rest of the session. Suspend the VM between turns and the filesystem and running processes wait for the next prompt.
* **Sub-ms resume.** Warm-suspended VMs wake instantly. The agent can park a task, do something else, and pick up where it left off without paying cold-start tax.
* **Fork on retry.** Snapshot the workspace before a destructive step. If the model goes sideways, fork the parent and re-run. The parent is untouched.
* **Scale-out.** \~30ms boot, \~160ms fork. Run a hundred agent tasks in parallel without queuing them through one machine.

## What the integration looks like

The shape is small. One VM per unit of work, exec commands into it, optionally suspend between turns, destroy when done.

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={"theme":"github-dark"}
    import { Boxd } from "@boxd-sh/sdk";

    const boxd = new Boxd();                    // reads BOXD_API_KEY

    // One VM per task / workspace / session
    const machine = await boxd.machines.create({ name: `task-${id}` });
    await boxd.machines.waitUntilReady(machine.id);

    await boxd.machines.exec(machine.id, { command: ["bash", "-lc", "git clone ..."] });
    await boxd.machines.exec(machine.id, { command: ["bash", "-lc", "npm test"] });

    // Warm-suspend between agent turns -- sub-ms resume on the next call
    await boxd.machines.pause(machine.id);
    await boxd.machines.resume(machine.id);

    // Clean up
    await boxd.machines.delete(machine.id);
    await boxd.close();
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"theme":"github-dark"}
    from boxd import Boxd

    boxd = Boxd()                          # reads BOXD_API_KEY

    # One VM per task / workspace / session
    machine = boxd.machines.create(f"task-{id}")
    boxd.machines.wait_until_ready(machine.id)

    boxd.machines.exec(machine.id, ["bash", "-lc", "git clone ..."])
    boxd.machines.exec(machine.id, ["bash", "-lc", "npm test"])

    # Warm-suspend between agent turns -- sub-ms resume on the next call
    boxd.machines.pause(machine.id)
    boxd.machines.resume(machine.id)

    # Clean up
    boxd.machines.delete(machine.id)
    ```
  </Tab>
</Tabs>

## Patterns

### One VM per workspace

Long-running, persistent. The workspace ID maps to a VM name; the VM warm-suspends between turns and resumes sub-ms when the next prompt arrives. The agent never sees the suspension. Repo state, installed deps, and running services all survive.

### One VM per task

Short-lived. Fork from a [golden](/cloud-dev-boxes/fork-from-a-golden) when the task starts, run the agent, destroy on completion. The golden ships with the toolchain and the repo pre-installed so cold-start is \~160ms instead of "wait for `npm install`".

### Fork on retry

Snapshot before a destructive step. If the agent goes off the rails, fork the parent again and re-run with a different prompt. The parent is untouched and you can compare multiple attempts side-by-side at `https://try-1.boxd.sh`, `https://try-2.boxd.sh`, etc.

## FAQ

<AccordionGroup>
  <Accordion title="How is this different from Agent sandboxes?">
    [Agent sandboxes](/agents/agent-sandboxes) is the pattern where the agent itself runs INSIDE the VM (Claude Code, Codex, OpenCode CLI on the image, driven via `boxd machine exec`). This page is the pattern where the agent runs OUTSIDE and uses boxd as its execution backend. Same VMs, same primitives, different wiring.
  </Accordion>

  <Accordion title="Why not just run a container per task?">
    Containers share a kernel. An agent with root inside a container can install kernel modules, run `systemd`, nest Docker, or break the host. A microVM gives you all of that and contains it. Cold start is in the same ballpark too -- 30ms boot, 160ms fork.
  </Accordion>

  <Accordion title="What about idle cost when the agent isn't running?">
    Auto-hibernate kicks in after 4 hours of no inbound traffic (configurable): the VM snapshots to disk, costs effectively nothing, and wakes in \~85ms on the next request. For tighter idle windows, enable auto-suspend (`boxd machine config set NAME auto-suspend.timeout SECS`) -- near-zero cost while suspended, sub-ms resume. The agent doesn't notice either.
  </Accordion>

  <Accordion title="How do I persist state across agent sessions?">
    Two options. Keep the VM warm-suspended (sub-ms resume, full state including running processes). Or fork from a golden each time (\~160ms, gets a copy of whatever the golden has installed). [Fork from a golden](/cloud-dev-boxes/fork-from-a-golden) covers the second pattern.
  </Accordion>

  <Accordion title="How many VMs can I run in parallel?">
    Ten per account by default, extendable on request. Each gets 2 vCPU, 8 GiB RAM, 100 GB disk.
  </Accordion>
</AccordionGroup>

## Next

<Columns cols={2}>
  <Card title="TypeScript SDK" icon="https://mintcdn.com/azin/Ax1V0serIwQf0x_2/images/icons/typescript.svg?fit=max&auto=format&n=Ax1V0serIwQf0x_2&q=85&s=64245fab67d3a1e63744bc4e6c1f955b" href="/reference/typescript-sdk" width="16" height="16" data-path="images/icons/typescript.svg">
    Full SDK reference. Machines, snapshots, disks, and the rest.
  </Card>

  <Card title="Python SDK" icon="https://mintcdn.com/azin/Ax1V0serIwQf0x_2/images/icons/python.svg?fit=max&auto=format&n=Ax1V0serIwQf0x_2&q=85&s=50aa9d4f66d47baaef6fd6846b681b78" href="/reference/python-sdk" width="16" height="16" data-path="images/icons/python.svg">
    Same SDK shape in Python, sync and async.
  </Card>

  <Card title="Suspend & resume" icon="https://mintcdn.com/azin/Ax1V0serIwQf0x_2/images/icons/moon-stars.svg?fit=max&auto=format&n=Ax1V0serIwQf0x_2&q=85&s=58518b62c4c44197c707ca00e1fd628e" href="/how-it-works/suspend-resume" width="16" height="16" data-path="images/icons/moon-stars.svg">
    How warm-suspend and sub-ms wake actually work.
  </Card>

  <Card title="Fork from a golden" icon="https://mintcdn.com/azin/Ax1V0serIwQf0x_2/images/icons/copy.svg?fit=max&auto=format&n=Ax1V0serIwQf0x_2&q=85&s=f3623fe516eebf87b33b3a1022852286" href="/cloud-dev-boxes/fork-from-a-golden" width="16" height="16" data-path="images/icons/copy.svg">
    Per-task copies of a pre-installed app.
  </Card>
</Columns>