Custom Docker Image

You can bring your own Docker image to run sandboxes with a pre-configured environment — dependencies, runtimes, and tooling already installed.

Using a public image

Any image on Docker Hub or a public registry works out of the box. Pass the image field to getOrCreateSandbox:

import { getOrCreateSandbox } from "hive";

const sandbox = await getOrCreateSandbox("python-sandbox", {
  image: "python:3.12-slim",
  entrypoint: "tail -f /dev/null",  // keep container alive
  fs: [{ backend: "local", mount: "/workspace", acls: [{ path: "/workspace/**", access: "rw" }] }],
});

import { getOrCreateSandbox } from "hive";

const sandbox = await getOrCreateSandbox("python-sandbox", {
  image: "python:3.12-slim",
  entrypoint: "tail -f /dev/null",  // keep container alive
  fs: [{ backend: "local", mount: "/workspace", acls: [{ path: "/workspace/**", access: "rw" }] }],
});

If the image's default CMD or ENTRYPOINT exits immediately (as is common with language runtime images), the container will stop. Use entrypoint to keep it running — see The entrypoint field below.

Custom Dockerfile

Build an image with exactly the tools you need and reference it by tag.

FROM ubuntu:24.04

RUN apt-get update && apt-get install -y \
  python3 python3-pip nodejs npm git \
  && rm -rf /var/lib/apt/lists/*

CMD ["tail", "-f", "/dev/null"]

FROM ubuntu:24.04

RUN apt-get update && apt-get install -y \
  python3 python3-pip nodejs npm git \
  && rm -rf /var/lib/apt/lists/*

CMD ["tail", "-f", "/dev/null"]

Build the image locally:

docker build -t my-sandbox:latest .

docker build -t my-sandbox:latest .

Then pass the tag to getOrCreateSandbox:

import { getOrCreateSandbox } from "hive";

const sandbox = await getOrCreateSandbox("dev", {
  image: "my-sandbox:latest",
  fs: [{ backend: "local", mount: "/workspace", acls: [{ path: "/workspace/**", access: "rw" }] }],
});

import { getOrCreateSandbox } from "hive";

const sandbox = await getOrCreateSandbox("dev", {
  image: "my-sandbox:latest",
  fs: [{ backend: "local", mount: "/workspace", acls: [{ path: "/workspace/**", access: "rw" }] }],
});

The image must be accessible to the Docker daemon running the Hive controller. For a remote controller, push the image to a registry the controller can pull from:

docker build -t your-org/my-sandbox:latest .
docker push your-org/my-sandbox:latest

docker build -t your-org/my-sandbox:latest .
docker push your-org/my-sandbox:latest

The entrypoint field

entrypoint overrides the container's CMD/ENTRYPOINT. The most common use is keeping the container alive when the image's default command exits right away:

const sandbox = await getOrCreateSandbox("python-sandbox", {
  image: "python:3.12-slim",
  entrypoint: "tail -f /dev/null",
  fs: [{ backend: "local", mount: "/workspace", acls: [{ path: "/workspace/**", access: "rw" }] }],
});

const sandbox = await getOrCreateSandbox("python-sandbox", {
  image: "python:3.12-slim",
  entrypoint: "tail -f /dev/null",
  fs: [{ backend: "local", mount: "/workspace", acls: [{ path: "/workspace/**", access: "rw" }] }],
});

If you build your own image and set a long-running CMD (such as ["tail", "-f", "/dev/null"]), you can omit entrypoint entirely.

Immutability after initialization

image and env are set at creation time and cannot be changed after the sandbox is initialized. getOrCreateSandbox will return the existing sandbox if one already exists with the given id, ignoring any updated image or env values in the config.

To switch to a different image, shut down the existing sandbox first and create a new one with a different id, or wait for it to expire.

Next: Remote File Systems