> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boat.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# AgentEnv

> Run AgentEnv RL environments and agents on boat sandboxes with the built-in boat sandbox provider: install, config, a first run, sizes and what the provider refuses.

[AgentEnv](https://www.agentenvframework.com/) is an open-source framework from engineers at Scale AI. You use it to build RL environments, and to run and grade agents inside them.

AgentEnv has a built-in `boat` sandbox provider. With it, each environment and each agent runs in its own boat sandbox: an Ubuntu VM with Docker inside.

```
agent-env run ──> boat provider ──> one boat sandbox per env, one per agent
```

## Set it up

You need Python 3.11.4 or later and a boat account. For the trial, see [Free trial](https://docs.boat.dev/free-trial.md).

**1. Get a boat API key**

Create a key on the [API keys](https://docs.boat.dev/api-keys) tab of the dashboard, or run `boat api-key create agentenv --preset ci`. Keep it in an environment variable:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
export BOAT_API_KEY=boat_...
```

**2. Install AgentEnv with the boat extra**

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
pip install 'agentenv-framework[boat]'
```

**3. Configure the provider**

Add the key reference to your AgentEnv config. Use `env:` or `secret:`, never the key itself:

```toml title=".agentenv/config.toml" theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
[sandbox.providers.boat.config]
api_key = "env:BOAT_API_KEY"
```

**4. Check your setup**

Run the built-in hello task on boat. It needs no model:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
agent-env run hello --sandbox boat
```

## Use boat for your runs

Make boat the default for environments, agents or both:

```toml title=".agentenv/config.toml" theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
[sandbox]
default = "boat"        # envs and deploy_sandbox steps
agent_default = "boat"  # agents
```

To choose boat for one run only, pass a flag:

| Command | Flag |
| - | - |
| `agent-env run` | `--sandbox boat` |
| `agent-env task run` | `--env-sandbox boat`, `--agent-sandbox boat` |

A comma-separated value, for example `"boat,local"`, tries the next provider when one fails to create a sandbox.

## What happens on boat

| AgentEnv step | What happens on boat |
| - | - |
| Create an env or agent | Creates a sandbox of the smallest size that fits the request, and waits until it is ready. |
| Exposed ports | boat hosts each port on a public HTTPS URL. |
| Run ends | AgentEnv deletes the sandbox. |
| Run crashes or is cancelled | The provider finds the sandbox by its label and deletes it. |
| Nothing deletes it | boat stops the sandbox at the AgentEnv timeout, 2 hours by default. |

Each sandbox is a [no-env sandbox](https://docs.boat.dev/environments.md#safe-for-third-parties). It gets none of your secrets, credentials or private repositories, and it cannot act on your account or on other sandboxes. Snapshots are off, so a stopped sandbox keeps no disk.

### Sizes

AgentEnv asks for CPU, memory and disk. The provider picks the smallest boat size that covers all three:

| Size | vCPU | Memory | Disk |
| - | - | - | - |
| `small` | 2 | 4 GiB | 51 GB |
| `default` | 4 | 8 GiB | 51 GB |
| `large` | 8 | 16 GiB | 111 GB |
| `xlarge` | 16 | 32 GiB | 251 GB |

A request bigger than `xlarge` fails. See [Machines](https://docs.boat.dev/machines.md).

### Labels

Every sandbox carries the label `agentenv.managed=true`. AgentEnv attribution (for example `[sandbox.attribution]` in its config) becomes `agentenv.attr.*` labels. Use them to find a run's sandboxes and to join [sandbox usage](https://docs.boat.dev/api/reference/sandboxes/get-sandbox-usage.md) to your runs.

## Limits

When boat refuses a create because a [start limit](https://docs.boat.dev/limits.md) is full, the provider waits and tries again. It makes up to 6 attempts. Keep the number of envs and agents that start at the same time under your limits.

## Not available

The provider refuses these with an error. It never creates a sandbox that is less isolated than you asked for.

* An `image` override. Every sandbox boots the standard boat image. See [Base image and tools](https://docs.boat.dev/machines/tools.md).
* A `network_policy` that restricts egress. boat has no egress allowlist yet.

## Configuration

| Key | Default | Description |
| - | - | - |
| `api_key` | none (required) | boat API key, as `env:NAME` or `secret:NAME`. |
| `api_url` | `https://boat.dev/api/v1` | API base URL. |

## Resources

> **[AgentEnv sandboxes](https://www.agentenvframework.com/docs/sandboxes#boat)**
>
> The boat provider in the AgentEnv docs.

> **[Source on GitHub](https://github.com/scaleapi/agentenv-framework)**
>
> The AgentEnv framework and its providers.

> **[Evals and RL environments](https://docs.boat.dev/evals)**
>
> Run many eval episodes on boat: saved snapshots, forks, limits and cost.

> **[API keys](https://docs.boat.dev/api-keys)**
>
> Create the key that the provider needs.


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