Skip to main content
The a13n logo mark and wordmark inside the boxd card. Agent Foundation (a13n), by Converge AI Labs, is an open-source runtime for building and running AI agents on your own infrastructure. a13n Service runs agents behind an HTTP API and a web Console. a13n Harness is the Python library underneath, which handles tool use, Skills, memory and subagents. Agents work with files and commands in an Environment, and you pick the provider that hosts it. boxd is one of those providers (pull request). Each Environment gets its own boxd machine. Agents use it through a13n’s native Files & Shell tools, stop() hibernates the machine with its memory and disk, and start() wakes it.
The boxd provider is merged into a13n’s main branch. It is not in a release yet: Harness 0.37.2 and the Service release that pins it came out before the merge. It ships with the next Harness release, as the a13n-harness[boxd] extra. Until then, use it from a checkout of converge-ai-labs/agent-foundation.

Set up

1

Install from a checkout

With Python 3.13 and uv:
The machine lifecycle (create, stop, start, destroy) lives in Service. Harness runs commands and file operations on a machine that Service created.
2

Create an API key

A key acts in one organization, and machines are created and billed there.
3

Create a machine and run a command

boxd_env.py
The whole run took about 11 seconds: create, a command, a file write, hibernate, wake, a file read, and delete. File paths start at the recipe’s root, so /notes.txt is /home/boxd/notes.txt on the machine.
Save the state that create() and start() return. It records the machine, and every later call needs it. To give a Harness agent the machine, pass the connector to the agent as in a13n’s Harness environments guide.

Use boxd in Service

Once Service ships with the provider, add it in Console under Workspace settings → Providers → Environment:
  1. Choose boxd. Enter the region (fra or nyc), an optional organization, and your API key.
  2. Create a template with that provider. Its recipe takes the fields below, for example {"size": "2x8"}.
  3. Turn on Files and Shell for an agent and pick the template.
Each instance of the template is one boxd machine. Service creates it, stops it by hibernating it, wakes it on start, and deletes it when you delete the instance.

Configuration

What each machine gets

  • Isolation: every machine is created isolated, with no route to your other machines and no boxd credentials inside.
  • Labels: each machine carries a13n_environment=<environment-id> and a13n_configuration=<fingerprint>. The provider checks them on every lookup, and a retried create finds its machine by them instead of making a second one.
  • No surprise stops: idle hibernation is off unless the recipe sets it, so a ready Environment stays ready. Idle standby, when set, resumes on the next command.
  • Memory kept across stop: stop() hibernates the machine, and start() wakes it with its files and running processes.
  • No expiry: machines need no keepalive. destroy() deletes the exact recorded machine and waits until it is gone. A machine you never destroy stays until you delete it.

Read more