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

# AgentRun

> Give AgentRun agents a boxd machine as their computer: an isolated microVM with no network, deleted when the computer is released.

![The agent.run() wordmark inside the boxd card.](https://mintcdn.com/azin/YgZNOc02fe3RwN8T/images/boxd-x-agentrun.png?fit=max\&auto=format\&n=YgZNOc02fe3RwN8T\&q=85\&s=07aab0a33d809aa387a56bb15004c340)

[AgentRun](https://agentrun.ai), by Parcha, is an open-source platform for running agents on Claude Code, Codex, OpenCode or pi. It adds durable runs, learning between runs, approvals and spend caps. Each agent can get a computer for its work: a sandbox, a Linux desktop, a phone or a browser, from the provider you pick.

boxd is one of those providers ([pull request](https://github.com/Parcha-ai/agentrun/pull/3035)). Each computer is an isolated boxd machine running Ubuntu 24.04, as a sandbox or as a desktop. It lives in `@parcha/agentrun-computer`, AgentRun's computer package.

> [!NOTE]
>
> The boxd provider is merged into AgentRun's main branch. It is not in a release yet: 0.1.0-beta.41 came out before the merge. It ships with the next release. Until then, use it from a checkout of [Parcha-ai/agentrun](https://github.com/Parcha-ai/agentrun).

## Set up

**1. Build from a checkout**

With Node 24 and Go on your PATH (the build fetches Go 1.24 when yours is older):

```bash theme={"theme":"github-dark"}
git clone https://github.com/Parcha-ai/agentrun
cd agentrun
npm ci
npm run build -w @parcha/agentrun-computer
npm run build:daemon -w @parcha/agentrun-computer
```

`build:daemon` builds `computerd`, the small program AgentRun runs in every computer. The boxd SDK, `@boxd-sh/sdk`, comes with the checkout's dev dependencies. In your own app, install it next to the package.

**2. Create an API key**

```bash theme={"theme":"github-dark"}
boxd auth keys create agentrun --org <your-org>
export BOXD_API_KEY=bxd_...
export BOXD_ORG=<your-org>
```

Machines are created and billed in the key's organization.

**3. Create a computer and run a command**

In the checkout, save this as `boxd-computer.mjs`:

```js boxd-computer.mjs theme={"theme":"github-dark"}
import { providerFor } from "@parcha/agentrun-computer";

const boxd = await providerFor("boxd", {
  apiKey: process.env.BOXD_API_KEY,
  org: process.env.BOXD_ORG,
  region: "fra",
});

const made = await boxd.create(
  { image: "default", lifetimeMs: 600_000, network: "none" },
  { requestId: `docs-${Date.now()}` },
);
if (!made.ok) throw new Error(made.error.message);
console.log("computer", made.value.id);

try {
  const connected = await boxd.connect(made.value);
  if (!connected.ok) throw new Error(connected.error.message);
  const ran = await connected.value.client.call("exec.run", {
    argv: ["sh", "-c", ". /etc/os-release; echo $PRETTY_NAME; uname -m; curl -sS -m 5 https://example.com >/dev/null || echo offline"],
    timeoutMs: 10_000,
  });
  if (!ran.ok) throw new Error(ran.error.message);
  console.log(ran.value.exitCode, Buffer.from(ran.value.stdout, "base64").toString());
  await connected.value.close();
} finally {
  const released = await boxd.release(made.value, "delete");
  console.log("released", released.ok);
}
```

```bash theme={"theme":"github-dark"}
node boxd-computer.mjs
```

```text theme={"theme":"github-dark"}
computer <machine-id>
0 Ubuntu 24.04.5 LTS
x86_64
offline

released true
```

The whole run took about 8 seconds: create, a command, and delete. `network: "none"` means the computer reaches nothing, so `curl` fails.

## Use boxd in AgentRun's server

AgentRun's server, serve, picks an agent's computer with one setting in its definition, set in the console under **Settings → Computers**:

```json theme={"theme":"github-dark"}
{ "computer": { "kind": "desktop", "provider": "boxd" } }
```

Save `BOXD_API_KEY` there, with `BOXD_ORG` and `BOXD_REGION` optional, or set them in the server's environment. A key in the environment wins over the saved one.

* **Desktops:** serve runs a boxd desktop. The first one builds a desktop snapshot in your organization, `agentrun-desktop-<hash>`, on a build machine that is deleted after the build. Later desktops start from that snapshot. Delete the snapshot with `boxd snapshots remove` and the next desktop builds it again.
* **Sandboxes:** serve mounts the run's folder into a sandbox, and the boxd provider takes no mount yet. So serve refuses a boxd sandbox for now. The provider itself makes sandboxes, as in the example above.

## Configuration

| Option | Default |
| - | - |
| `apiKey` | Required. The provider reads no environment variable itself |
| `org` | The API key's organization |
| `region` | The API's default [region](https://docs.boxd.sh/guides/regions.md); `fra` or `nyc` |
| `vcpu`, `memory` | The organization's default; `1` and `4G`, `2` and `8G`, `4` and `16G`, or `8` and `32G`. Set both or neither. A desktop keeps its snapshot's size |
| `kind` | `linux`; `desktop` starts from the desktop snapshot |
| `maxLifetimeMs` | 24 hours, at most 30 days |
| `daemonUser` | `2510:2510`; never root, never the image's own user |

## What each machine gets

* **Isolation:** every machine is created [isolated](https://docs.boxd.sh/use-cases/sandboxes.md#cut-off-from-your-fleet-by-design), with no route to your other machines and no boxd credentials inside.
* **No network:** the [egress allowlist](https://docs.boxd.sh/guides/egress-allowlist.md) is set to `none` once the machine is ready, and `computerd` runs in a network namespace of its own.
* **No surprise sleep:** idle standby and hibernation are off, so a long command with no network traffic keeps running.
* **A delete timer:** boxd's [delete timer](https://docs.boxd.sh/guides/delete-after.md) ends every machine `maxLifetimeMs` plus 5 minutes after it was made, even when the server that made it is gone. `release(..., "delete")` deletes it at once.
* **Labels:** the provider finds its machines by their labels, and a retried create finds the machine it already made instead of making a second one.

## Read more

* [boxd in the computer package's README](https://github.com/Parcha-ai/agentrun/tree/main/packages/computer#boxd): the mapping, the desktop snapshot and the conformance runs
* [Computers in serve's README](https://github.com/Parcha-ai/agentrun/tree/main/packages/serve#computers)
* [AgentRun on GitHub](https://github.com/Parcha-ai/agentrun)
* [Sandboxes on boxd](https://docs.boxd.sh/use-cases/sandboxes.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.