Skip to main content
An episode is one sandbox. Prepare the environment once, save it as a saved snapshot, and start each episode from it. Delete the sandbox when the episode ends. The next episode starts from the same clean state.

1. Prepare the environment

Install the task’s dependencies and fixtures in one sandbox. Then save it under a name:
  • Use one saved snapshot per environment version: task-env-v1, task-env-v2. A saved snapshot does not change after you save it.
  • Docker images: a saved snapshot keeps only the images that a container uses. Run docker create --name keep-<x> <image> for each image. See What a snapshot saves.
  • 10 saved snapshots are free. Each one more costs $0.056 a day from the wallet. See Saved snapshots.

2. Run episodes in parallel

This Python script starts one sandbox per episode from the saved snapshot, runs the episode, reads the score and deletes the sandbox. It paces the starts to the minute limit of the $20 plan.
run_episodes.py
  • exec_command waits at most 600 seconds. For a longer episode, start it with detached=True and poll command_status. See Python SDK.
  • ttl_seconds=3600 stops a sandbox after one hour if your script crashes before the delete.
  • In asyncio code, wrap each call in asyncio.to_thread. The SDK is synchronous.

Fork instead of a saved snapshot

boat fork <id> (or fork in the API) also copies a sandbox. Use it to branch one episode mid-way, for example to try several actions from the same state.
  • A fork copies the newest snapshot of its source. If the source keeps running, later forks get later states.
  • A fork of a running sandbox uses its last background snapshot. Files written after it can be missing. Stop the source first for an exact copy.
For a fixed start state, use a saved snapshot. See Resume and fork.

Limits

  • On the $20 plan, the hour limit (60) sets the pace: 100 episodes take about 100 minutes to start. On the $100 plan (210 per hour), they take about 29 minutes. The day limit caps a long run.
  • A start above the limit fails with 429 rate_limited, names the window, and does not count. The API sends a Retry-After header.
  • An organization on the $2000 plan multiplies these numbers by its seats. Below it, each extra seat adds 20%.
  • --fail-fast (fail_fast=True) answers in about 1.5 seconds when no machine is free, instead of waiting.
All limits and how to raise them: Limits.

Cost

boat bills each second that a sandbox runs. A deleted sandbox costs nothing. Model calls are extra when an agent runs in the sandbox. See Pricing and AI credentials.

Agents in the episode

To run Claude Code, Codex or another harness in each sandbox, send a prompt to the sandbox and wait for it. See Integrated agents and Python SDK. To keep your model keys out of the sandboxes, use the AI credentials proxy. For episodes that other people or untrusted code control, create the sandboxes with no_env=True. They then get none of your secrets.

AgentEnv

AgentEnv runs its environments and agents on boat with its built-in boat sandbox provider. See AgentEnv.

Harbor and Terminal-Bench

  • Harbor runs on boat through the Harbor adapter (harbor run -e harbor_box_environment:BoxEnvironment).
  • Terminal-Bench 2.0 does not run through that adapter today. Each of its tasks names a prebuilt Docker image, and the adapter refuses tasks with a Docker image.
  • To run a Terminal-Bench style task on boat now, install its dependencies in a saved snapshot (step 1) and run the task’s test script with boat exec.

Clean up

List what is still running, and delete what your run left: