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:
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:

​
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:
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:
Pass --sync-config hive.yaml to hive push image to have it pin sandbox.base_image to the pushed image’s digest automatically:
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.
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

For a complete working example, see hiverge/project-matmul.