Skip to main content
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 project: 
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: 
sandbox:
  base_image: hive:<short-name>:<tag>
Pass --sync-config hive.yaml to hive push image to have it pin sandbox.base_image to the pushed image’s digest automatically:
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.

​
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. 
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

ConcernWhere it lives
Source code & build artifacts/app inside the image
Git history/app/.git inside the image
Runtime source updatessandbox.setup_script using git
Image referencesandbox.base_image in your config YAML
For a complete working example, see hiverge/project-matmul.