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

# Custom Base Image

> How to build and use a custom Docker base image for your Hive experiment

By default, the Hive runs evaluations inside a stock Docker image (e.g. `python:3.14`). For experiments that need compiled toolchains, large datasets, or non-trivial dependencies, startup time can dominate the evaluation budget. A **custom base image** lets you bake all of that into a single layer so sandboxes start instantly.

## Build your image

A custom base image is a standard Docker image that contains your project's source code and dependencies pre-installed at `/app`. The Hive expects the working directory to be `/app` and your source files to live there.

Here is an example `Dockerfile` from the [`hiverge/project-matmul`](https://github.com/hiverge/project-matmul) project:

```dockerfile theme={null}
FROM python:3.14

COPY *.py *.h *.cpp Makefile /app/
COPY .git /app/.git/

RUN cd /app && make

WORKDIR /app
```

Key points:

* **Source lives in `/app`** — the Hive mounts evolved files into this directory at evaluation time, so your build artifacts, scripts, and evaluator must all be rooted here.
* **Pre-compile** — running `make` (or equivalent) during the build means sandboxes don't waste evaluation time on compilation of unchanged code.

Build the image locally:

```
docker build -t <image-name>:dev .
```

## Push it to the Hive registry

Instead of pushing to a public registry, push the local image directly into the Hive-managed registry with `hive push image`:

```
$ hive push image <image-name>:dev hive:<short-name>:<tag>
✓ Pushed hive:<short-name>:<tag>
```

The first argument is the local image reference you just built; the second is the `hive:{short}:{tag}` reference to store it under.

## Reference it in your configuration

Point your experiment at the pushed image using the `sandbox.base_image` field:

```yaml theme={null}
sandbox:
  base_image: hive:<short-name>:<tag>
```

<Tip>
  Pass `--sync-config hive.yaml` to `hive push image` to have it pin `sandbox.base_image` to the pushed image's digest automatically:

  ```bash theme={null}
  hive push image <image-name>:dev hive:<short-name>:<tag> --sync-config hive.yaml
  ```

  This rewrites the field to `hive:<short-name>:<tag>@sha256:...`, so subsequent experiments pull the exact manifest rather than whatever the mutable tag later resolves to.
</Tip>

## Editing Files

Once the image is pushed and the first experiment is created, likely one will want to create a second experiment with minor modifications, e.g. to the evaluation script.

The process for this is to overlay specific files onto the image, e.g.

```yaml theme={null}
repo:
  source: SOURCE_DIR
  base_image: hive:<short-name>:<tag>
  files:
    - evaluator.py
    - src/foo.cpp
```

will upload the two files `evaluator.py` and `src/foo.cpp` found in `SOURCE_DIR` to the Hive. The Hive will copy the listed files to the Docker image. In the example `evaluator.py` will be copied to `/app/evaluator.py` and `src/foo.cpp` will be copied to `/app/src/foo.cpp`.

## Summary

| Concern                       | Where it lives                           |
| ----------------------------- | ---------------------------------------- |
| Source code & build artifacts | `/app` inside the image                  |
| Git history                   | `/app/.git` inside the image             |
| Runtime source updates        | `sandbox.setup_script` using git         |
| Image reference               | `sandbox.base_image` in your config YAML |

For a complete working example, see [`hiverge/project-matmul`](https://github.com/hiverge/project-matmul).