# Sandboxes (https://www.agentenvframework.com/docs/sandboxes)

> Sandbox = The isolated machine or container that your environment or agent resides in

New to AgentEnv Framework? [Getting Started](https://www.agentenvframework.com/docs/getting-started.md) installs it and runs a first task
in two commands, with no Docker, model or cloud account, and [Core Concepts](https://www.agentenvframework.com/docs/core-concepts.md)
explains environments, agents and tasks. Every provider below runs the same tasks; the default,
`local`, needs only Docker.

## Supported Providers

| Provider                    | A sandbox is                                                                                                                                          | Egress allowlist | Needs                                                              |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | ------------------------------------------------------------------ |
| `local` (default)           | containers on your own Docker                                                                                                                         | no               | Docker                                                             |
| [`modal`](#modal)           | a [Modal](https://modal.com) container for each env service and agent                                                                                 | yes              | a Modal token                                                      |
| [`modal_vm`](#modal)        | a Modal VM with Docker inside, one per env                                                                                                            | yes              | a Modal token                                                      |
| [`coreweave`](#coreweave)   | a [CoreWeave Sandbox](https://docs.coreweave.com/products/sandboxes): a container running an agent's own image, or a VM with Docker inside for an env | yes              | the `coreweave` extra and a CoreWeave or W\&B API key              |
| [`e2b`](#e2b)               | an [E2B](https://e2b.dev) sandbox with Docker inside                                                                                                  | yes              | an E2B API key and template                                        |
| [`sail_vm`](#sail)          | a [Sail](https://docs.sailresearch.com/sailboxes) Sailbox, a root VM with Docker inside                                                               | yes              | the `sail` extra and a Sail API key                                |
| [`tensorlake`](#tensorlake) | a [Tensorlake](https://tensorlake.ai) MicroVM with Docker inside                                                                                      | yes              | the `tensorlake` extra and a Tensorlake API key                    |
| [`tenki`](#tenki)           | a [Tenki Sandbox](https://tenki.cloud/docs/sandbox) Linux VM with Docker inside                                                                       | yes              | the `tenki` extra and a Tenki API key                              |
| [`vercel`](#vercel)         | a [Vercel Sandbox](https://vercel.com/docs/sandbox) with Docker inside                                                                                | yes              | the `vercel` extra and Vercel credentials                          |
| [`smol_vm`](#smol)          | a [SmolVM](https://github.com/smol-machines/smol) microVM on your own machine, with Docker inside                                                     | no               | the `smol` extra, and Apple Silicon macOS or Linux with `/dev/kvm` |
| [`boxd`](#boxd)             | a [boxd](https://docs.boxd.sh) machine, a hardware-isolated VM with Docker running inside                                                             | yes              | the `boxd` extra and a boxd API key                                |
| [`daytona`](#daytona)       | a [Daytona](https://www.daytona.io) sandbox with Docker running inside                                                                                | yes, on Tier 3   | the `daytona` extra and a Daytona API key                          |
| [`boat`](#boat)             | a [boat](https://boat.dev) sandbox, an Ubuntu VM with Docker running inside                                                                           | no               | the `boat` extra and a boat API key                                |
| [`agent37`](#agent37)       | an [Agent37](https://www.agent37.com) VM with Docker running inside                                                                                   | no               | an Agent37 API key                                                 |
| [`lume`](#lume)             | a macOS VM on your own Mac, run by [Lume](https://cua.ai/docs/lume), for macOS computer envs                                                          | no               | an Apple-silicon Mac with Lume, and a logged-in session            |

A `deploy_sandbox` or `deploy_agent` step with a `network_policy` gets a sandbox that only reaches
the hosts the policy allows. A provider that can't enforce the policy refuses the step instead of
creating an open sandbox. To run on a platform that isn't listed, write a [sandbox provider
plugin](https://www.agentenvframework.com/docs/plugins/sandbox-provider-plugins.md).

## Picking a Provider

```toml title=".agentenv/config.toml"
[sandbox]
default       = "local"   # envs and deploy_sandbox steps
agent_default = "local"   # agents
```

A comma-separated value, such as `"sail_vm,e2b"`, is a fallback chain: when one provider can't
create a sandbox, the next one is tried. For a single run, `--sandbox` on `agent-env run`, or
`--env-sandbox` and `--agent-sandbox` on `agent-env task run`, override the config. A provider's
own settings go in `[sandbox.providers.<name>.config]`, with keys given as `secret:` or `env:`
references, never as the key itself.

### Modal

`modal` and `modal_vm` read `MODAL_TOKEN_ID` and `MODAL_TOKEN_SECRET`, or else the active profile
in `~/.modal.toml` that `modal token new` writes, so they need no config table.

### CoreWeave

```bash
pip install 'agentenv-framework[coreweave]'
```

```toml title=".agentenv/config.toml"
[sandbox.providers.coreweave.config]
api_key = "env:CWSANDBOX_API_KEY"   # or wandb_api_key = "env:WANDB_API_KEY"
```

Each env gets a CoreWeave Sandbox with Docker inside, and each agent runs its own image in one of
its own. The [`coreweave`
provider](https://github.com/scaleapi/agentenv-framework/tree/main/src/agent_env/providers/sandbox_providers/coreweave)
covers the rest.

### E2B

`e2b` needs an E2B template with Docker and Compose v2. Build one with the Docker Compose example
in E2B's [Docker guide](https://docs.e2b.dev/template/examples/docker#docker-compose), then set
`base_template` to its name. agent-env builds each sandbox size it needs from that template.

```toml title=".agentenv/config.toml"
[sandbox.providers.e2b.config]
api_key       = "env:E2B_API_KEY"
base_template = "docker-compose"   # the template the guide builds
```

### Sail

```bash
pip install 'agentenv-framework[sail]'
```

```toml title=".agentenv/config.toml"
[sandbox.providers.sail_vm.config]
api_key = "env:SAIL_API_KEY"
```

`agent-env run hello --sandbox sail_vm` checks the setup with no model. Sail injects an agent's
model key and `[model.headers]` at its egress, so neither enters the Sailbox. The [`sail_vm`
README](https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/providers/sandbox_providers/sail_vm/README.md)
covers sizes, auto-sleep, egress and cost.

### Tensorlake

```bash
pip install 'agentenv-framework[tensorlake]'
```

```toml title=".agentenv/config.toml"
[sandbox.providers.tensorlake.config]
api_key = "env:TENSORLAKE_API_KEY"
```

`agent-env run hello --sandbox tensorlake` checks the setup with no model. Sandboxes boot from
`agentenv-dind-host-v1`, a public image with Docker and Compose v2; set `image` to boot your own.
The [`tensorlake`
README](https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/providers/sandbox_providers/tensorlake/README.md)
covers sizes, egress and cost.

### Tenki

```bash
pip install 'agentenv-framework[tenki]'
```

```toml title=".agentenv/config.toml"
[sandbox.providers.tenki.config]
api_key = "env:TENKI_API_KEY"
```

`agent-env run hello --sandbox tenki` checks the setup with no model. Each env and each agent gets
a Linux VM of its own, with Docker inside and a public HTTPS URL for each port it exposes. The
[`tenki`
README](https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/providers/sandbox_providers/tenki/README.md)
covers sizes, egress and cost.

### Vercel

```bash
pip install 'agentenv-framework[vercel]'
```

```toml title=".agentenv/config.toml"
[sandbox.providers.vercel.config]
token      = "env:VERCEL_TOKEN"
team_id    = "your-team-id"
project_id = "your-project-id"
```

`agent-env run hello --sandbox vercel` checks the setup with no model. Set `token`, `team_id` and
`project_id` together, or leave out the table to use the Vercel SDK's own credentials, such as a
`VERCEL_OIDC_TOKEN` from `vercel project token <project>`. Each env and each agent gets a Vercel
Sandbox of its own, with Docker inside and a public `*.vercel.run` URL for each port it exposes.
A request gets the smallest size that covers its CPU and memory, at 2 GB per vCPU and up to 32
vCPUs, and every sandbox has a fixed 64 GB disk. `region` and `failover_regions` pick where
sandboxes run, and egress allowlists take hostnames and CIDR ranges.

### smol machines

```bash
pip install 'agentenv-framework[smol]'
```

`agent-env run hello --sandbox smol_vm` checks the setup with no model. Each env and each agent gets
a SmolVM microVM of its own on your machine, with Docker inside, so it needs no account, API key or
config table, and nothing runs on your host's Docker. It needs Apple Silicon macOS, or Linux with
`/dev/kvm`; on Apple Silicon, build images for `linux/arm64`. The local object and image stores
work as they are: guests fetch local objects, and each VM forwards image pulls to your host's
registry.

### boxd

```bash
pip install 'agentenv-framework[boxd]'
```

```toml title=".agentenv/config.toml"
[sandbox.providers.boxd.config]
api_key = "env:BOXD_API_KEY"
```

`agent-env run hello --sandbox boxd` checks the setup with no model. Each env and each agent gets
its own boxd machine with Docker inside, and the [`boxd`
README](https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/providers/sandbox_providers/boxd/README.md)
covers the rest.

### Daytona

```bash
pip install 'agentenv-framework[daytona]'
```

```toml title=".agentenv/config.toml"
[sandbox.providers.daytona.config]
api_key = "env:DAYTONA_API_KEY"
```

`agent-env run hello --sandbox daytona` checks the setup with no model. Each env and each agent gets
its own Daytona sandbox with Docker inside, and the [`daytona`
README](https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/providers/sandbox_providers/daytona/README.md)
covers the rest.

### boat

```bash
pip install 'agentenv-framework[boat]'
```

```toml title=".agentenv/config.toml"
[sandbox.providers.boat.config]
api_key = "env:BOAT_API_KEY"
```

`agent-env run hello --sandbox boat` checks the setup with no model. Each env and each agent gets
its own boat sandbox with Docker inside, and the [`boat`
provider](https://github.com/scaleapi/agentenv-framework/tree/main/src/agent_env/providers/sandbox_providers/boat)
covers the rest.

### Agent37

```toml title=".agentenv/config.toml"
[sandbox.providers.agent37.config]
api_key = "env:AGENT37_API_KEY"
```

It needs no extra, and `agent-env run hello --sandbox agent37` checks the setup with no model. Each env
and each agent gets its own Agent37 VM with Docker inside, and the [`agent37`
README](https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/providers/sandbox_providers/agent37/README.md)
covers the rest.

### Lume

`lume` runs macOS computers on your own Mac: each deploy boots a clone of the computer's VM bundle in
[Lume](https://cua.ai/docs/lume), so it needs an Apple-silicon Mac with Lume installed and agent-env running in a
logged-in session. It runs macOS computer envs only, at most two at once as Apple's licence allows, and the [`lume`
provider](https://github.com/scaleapi/agentenv-framework/blob/main/src/agent_env/providers/sandbox_providers/lume/provider.py)
covers its settings.