Skip to main content
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. AgentEnv 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 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

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

Create an API key

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:
The provider reads the key from this config only, never from the process environment.
4

Run the hello task

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:
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 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:
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 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 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.
  • 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 explains how to raise the cap. The provider’s README covers the rest, including the configuration reference, networking, and cleanup, and AgentEnv’s docs list boxd with its other providers.