---
title: Add toolchains
description: Give every attempt the toolchain the agent needs.
---
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reeval.ai/llms.txt
> Use this file to discover all available pages before exploring further.

reeval's sandbox image has Node, Git, and the harness. When the agent needs another toolchain, add it to the image so every attempt starts with it installed. For more information about commands that run before each attempt, see [Setup commands](/configuration/environments/setup-commands).

## Start from a base image

To start with a Debian- or Ubuntu-based image, in the `evals/environments.ts` file, pass `from` to `docker()`. On the first run, reeval installs Node, Git, and the harness in the image and caches the result:

```ts title="evals/environments.ts"
import { defineEnvironment } from '{{ pkg }}'
import { docker } from '{{ pkg }}/sandbox'

export const python = defineEnvironment('python', {
  sandbox: docker({ from: 'python:3.12-slim', id: 'python' }),
})
```

The image needs `apt-get` and glibc. The `id` names the cell in results. Without it, the cell is `docker:python:3.12-slim`. For an image that already contains the harness, pass `image`, and reeval uses that image unchanged. For more information about every `docker()` option, see [Docker sandbox](/configuration/sandboxes/docker).

For a runnable project, see [`with-python-image`](https://github.com/invertase/reeval/tree/main/examples/with-python-image).

## Choose another setup

- To copy files into the image, build it from a Dockerfile that starts `FROM ${REEVAL_BASE}` with [`dockerfile`](/reference/options#docker). For a runnable project, see [`with-dockerfile`](https://github.com/invertase/reeval/tree/main/examples/with-dockerfile).
- To add packages to the image, list shell commands in [`install`](/reference/options#docker), which combines with `from`. For a runnable project, see [`with-docker-install`](https://github.com/invertase/reeval/tree/main/examples/with-docker-install).

## Prebuild images

A run builds the images its sandboxes are missing before the first attempt. To build them before `reeval run`, run `reeval image build`:

```bash
npx reeval image build
```

The command builds every image the planned evaluations need. It exits with code 2 when every failed build failed on the config, such as an `image` tag that doesn't resolve, and with code 3 otherwise. It takes the same filters and `--profile` as `reeval run`. To list each image's status without building, add `--dry-run`:

```bash
npx reeval image build --dry-run
```

Each image step prints with a mark and status word:

| Mark | Status | Meaning |
| :--- | :--- | :--- |
| `✓` | `ready` | Built, on an unchanged base |
| `+` | `to build` | The next run or `reeval image build` builds it |
| `~` | `stale` | A `from` tag moved upstream, and `reeval image build` rebuilds it |
| `✗` | `missing` | An `image` or `from` tag that doesn't resolve |

To rebuild every image and pull each base again, add `--force`. To remove the images reeval built that nothing tags any more, along with the debug data in the `.reeval/debug` directory, run `reeval clean --images`:

```bash
npx reeval clean --images
```

## Troubleshooting

An image that fails to build fails every attempt on it with an infrastructure error, not a failed assertion. Use the symptom to choose what to check and what to do next:

| Symptom | Check | Next action |
| :--- | :--- | :--- |
| `reeval needs a Debian or Ubuntu based image (glibc and apt-get)` | The `from` image, or the Dockerfile's `FROM`, has no `apt-get` | Start from a Debian or Ubuntu variant, such as `python:3.12-slim` |
| `Building docker/sqlite/Dockerfile failed: a RUN step exited 1` | The `RUN` line's output, in the message's last lines | Fix the line, then run `npx reeval image build` again |
| `✗ from … (missing: doesn't resolve: …)` in the `--dry-run` listing | The tag exists, and the registry allows the pull | Fix the tag, or log in to the registry with the container CLI |