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

# Scale AI AgentEnv

> Run every AgentEnv environment and agent on its own boxd machine, with Docker inside.

![Scale's logo over the line Scale AI runs on boxd, and five bars, one for each AgentEnv run, each ending in a judge score of 1.0.](https://mintcdn.com/azin/AymzL8ysAYlTuEv-/images/boxd-x-agentenv.png?fit=max\&auto=format\&n=AymzL8ysAYlTuEv-\&q=85\&s=100e5ead8a44bbf24595e30b67a68db9)

[AgentEnv](https://www.agentenvframework.com) is Scale AI's open-source framework for building, deploying, and running agentic environments and the tasks that grade agents inside them. An environment is a containerized server: AgentEnv builds it into an image, deploys it behind a gateway, points an agent at it, and scores what the agent did.

The [boxd provider](https://github.com/scaleapi/agentenv-framework/pull/263) gives each environment and each agent its own boxd machine, a hardware-isolated Linux VM with Docker running inside and an HTTPS URL for each port. AgentEnv's Docker flows run on it unchanged, from the gateway's `docker-compose` to an agent's `docker run`.

## Set up

**1. Install AgentEnv with the boxd extra**

```bash theme={"theme":"github-dark"}
pip install 'agentenv-framework[boxd]'
```

In a uv project, use `uv add 'agentenv-framework[boxd]'`.

**2. Create an API key**

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

Machines are created and billed in the key's organization. For a shared deployment, keep the key in your secret store and reference it as `secret:boxd_api_key` instead.

**3. Add the provider to your config**

In `.agentenv/config.toml`:

```toml theme={"theme":"github-dark"}
[sandbox.providers.boxd.config]
api_key = "env:BOXD_API_KEY"
```

The provider reads the key from this config only, never from the process environment.

**4. Run the hello task**

```bash theme={"theme":"github-dark"}
agent-env run hello --sandbox boxd
```

The bundled `hello` task starts a boxd machine, loads a file into it, and checks it. It needs no model.

To run every environment and agent on boxd without the flag, make it the default in the same file:

```toml theme={"theme":"github-dark"}
[sandbox]
default       = "boxd"   # environments
agent_default = "boxd"   # agents
```

`agent-env task run` also takes `--env-sandbox boxd` and `--agent-sandbox boxd` to choose per run, and `agent-env -v` logs each machine as it starts.

## Start every machine from a snapshot

A machine booted from boxd's image builds or pulls every image its environment needs. Boot it from a [snapshot](https://docs.boxd.sh/guides/snapshots.md) of a machine that already has them, and those builds become cache hits. The provider's README measured the `echo-mcp` bundle's `deploy_env` going from about 117 seconds to 47.

Keep one run's machines up, clear the environment's machine down to its images, and save it:

```bash theme={"theme":"github-dark"}
agent-env -v run my-bundle --sandbox boxd --keep
boxd machine exec agentenv-… -- sudo sh -c 'docker rm -f $(docker ps -aq); docker volume prune -af; docker network prune -f'
boxd snapshots save agentenv-… agentenv-warm
```

The `boxd machine started` log line names the machine. Stop the run with Ctrl-C, then set `snapshot = "agentenv-warm"` under `[sandbox.providers.boxd.config]`. A snapshot keeps memory and disk, so clearing the containers and volumes first stops every new machine from restoring them.

## What each machine gets

* **A size:** the smallest of boxd's four [machine sizes](https://docs.boxd.sh/guides/machine-specs.md) that covers the request's CPU and memory. AgentEnv's default of 1 vCPU and 8 GiB runs on 2 vCPU / 8 GiB.
* **A deadline:** AgentEnv's `timeout` becomes the machine's [delete-after](https://docs.boxd.sh/guides/delete-after.md) timer, so boxd deletes the machine even when a crashed run never tears it down.
* **Isolation:** every machine is created isolated, with no peers on your organization's network and no in-machine `boxd` CLI, metadata endpoint, or account integrations.
* **Egress control:** an allowlist set in AgentEnv is enforced outside the machine, so one list covers `dockerd` and every container. See [Egress control](https://docs.boxd.sh/guides/egress).
* **Public ports:** each exposed port gets its own URL, `https://p<port>.<machine>.boxd.sh`.

Each environment and each agent is one machine, so a task with one of each runs on two. An organization holds up to 50 machines by default, enough for 25 such tasks at once, and 2 until it adds a payment method. [Resources and limits](https://docs.boxd.sh/guides/resources.md) explains how to raise the cap.

The [provider's README](https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/providers/sandbox_providers/boxd/README.md) covers the rest, including the configuration reference, networking, and cleanup, and [AgentEnv's docs](https://www.agentenvframework.com/docs/sandboxes#boxd) list boxd with its other providers.


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