Skip to main content
The agent.run() wordmark inside the boxd card. AgentRun, 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). 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.
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.

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

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:
boxd-computer.mjs
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:
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

What each machine gets

  • Isolation: every machine is created isolated, with no route to your other machines and no boxd credentials inside.
  • No network: the egress allowlist 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 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