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

# Agent Foundation (a13n)

> Give a13n agents a boxd machine as their environment: one isolated machine per Environment, hibernated on stop and woken on start with its memory and disk.

![The a13n logo mark and wordmark inside the boxd card.](https://mintcdn.com/azin/KS-c1q6CF0mBxP9p/images/boxd-x-agent-foundation.png?fit=max\&auto=format\&n=KS-c1q6CF0mBxP9p\&q=85\&s=dceaeba9226dbababe7567ff8d5e5e1c)

[Agent Foundation](https://a13n.dev) (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](https://github.com/converge-ai-labs/agent-foundation/pull/1551)). 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.

> [!NOTE]
>
> 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](https://github.com/converge-ai-labs/agent-foundation).

## Set up

**1. Install from a checkout**

With Python 3.13 and [uv](https://docs.astral.sh/uv/):

```bash theme={"theme":"github-dark"}
git clone https://github.com/converge-ai-labs/agent-foundation
cd agent-foundation
uv sync --package a13n-service --no-dev
```

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**

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

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

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

```python boxd_env.py theme={"theme":"github-dark"}
import asyncio
import os

from a13n_harness.environment.commands import CommandRequest, ShellCommand
from a13n_harness.environment.retention import EnvironmentOutputPolicy
from a13n_service.providers.environments.boxd import BOXD

account = {"region": "fra"}
credential = {"api_key": os.environ["BOXD_API_KEY"]}
recipe = {"size": "2x8", "environment": {"GREETING": "Hello from boxd"}}
ENV_ID = "env-demo"


def connector(state):
    return BOXD.execution.execution_connector(
        recipe, configuration=account, credential=credential, environment_id=ENV_ID, state=state
    )


async def main():
    async with await BOXD.open_provider(configuration=account, credential=credential) as provider:
        state = None
        try:
            state = await provider.create(recipe, environment_id=ENV_ID, operation_id="op-create")

            async with await connector(state).open() as env:
                await env.operations.files.write_text("/notes.txt", "kept while hibernated\n", mode="create")
                result = await env.operations.shell.exec(
                    CommandRequest(
                        command=ShellCommand(profile_id="default", script='echo "$GREETING"; pwd; nproc'),
                        output_policy=EnvironmentOutputPolicy(max_inline_bytes=4096, max_output_bytes=4096, overflow="truncate"),
                    )
                )
                print(result.output.stdout.inline.decode(), end="")

            state = await provider.stop(recipe, environment_id=ENV_ID, state=state, operation_id="op-stop")
            print("after stop:", (await provider.inspect(recipe, environment_id=ENV_ID, state=state)).status)
            state = await provider.start(recipe, environment_id=ENV_ID, state=state, operation_id="op-start")

            async with await connector(state).open() as env:
                print((await env.operations.files.read_text("/notes.txt")).text, end="")
        finally:
            await provider.destroy(recipe, environment_id=ENV_ID, state=state, operation_id="op-delete")
            print("destroyed")


asyncio.run(main())
```

```bash theme={"theme":"github-dark"}
uv run --package a13n-service --no-dev python boxd_env.py
```

```text theme={"theme":"github-dark"}
Hello from boxd
/home/boxd
2
after stop: stopped
kept while hibernated
destroyed
```

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](https://github.com/converge-ai-labs/agent-foundation/blob/main/docs/a13n-harness/environments.md#supply-a-source).

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

| Account setting | Value |
| - | - |
| `region` | Required. `fra` or `nyc`, see [regions](https://docs.boxd.sh/guides/regions.md) |
| `organization` | Optional. Defaults to the API key's organization |
| `api_key` | The credential, a boxd API key |

| Recipe field | Default |
| - | - |
| `size` | The organization's default, or the snapshot's size; `1x4`, `2x8`, `4x16` or `8x32` (vCPU x GiB) |
| `from_snapshot` | None; starts the machine from a boxd [snapshot](https://docs.boxd.sh/guides/snapshots.md) |
| `environment` | None; set on the machine at create and passed to every command. A snapshot restore takes none at create |
| `auto_suspend_timeout_seconds` | `0`, no idle [standby](https://docs.boxd.sh/guides/suspend-resume.md) |
| `auto_hibernate_timeout_seconds` | `0`, no idle hibernation. A hibernated machine needs `start()` |
| `root` | `/home/boxd` |
| `request_timeout_seconds` | `120`, up to `600`; bounds each command and request |

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

* [boxd in a13n's cloud provider guide](https://github.com/converge-ai-labs/agent-foundation/blob/main/docs/environments/cloud-providers.md#boxd)
* [Configuration reference](https://github.com/converge-ai-labs/agent-foundation/blob/main/docs/environments/configuration-reference.md#boxdenvironmentconfiguration)
* [Agent Foundation on GitHub](https://github.com/converge-ai-labs/agent-foundation)
* [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.