OCI Image

Any OCI image is supported, such as Docker, Podman, or Buildah builds. The CLI's hiver bundle command wraps the Hiver runtime inside your image so it can run as a sandbox, your Dockerfiles need no special configuration.

Bundle an existing image

Point hiver bundle at any image from a registry and give the result a tag:

hiver bundle python:3.13-alpine --tag python

hiver bundle python:3.13-alpine --tag python

Then reference the tag as image when you provision:

index.ts

import { getOrCreateSandbox } from "@hiver.sh/client";

const sandbox = await getOrCreateSandbox("py", { image: "python" });

import { getOrCreateSandbox } from "@hiver.sh/client";

const sandbox = await getOrCreateSandbox("py", { image: "python" });

Bring your own Dockerfile

Set up the environment however you normally would, then bundle the build context (a path instead of an image reference):

Dockerfile

FROM python:3.12-slim

WORKDIR /workspace
RUN pip install requests numpy pandas

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

FROM python:3.12-slim

WORKDIR /workspace
RUN pip install requests numpy pandas

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

hiver bundle ./my-image --tag data-tools

hiver bundle ./my-image --tag data-tools

If the image's default CMD/ENTRYPOINT exits immediately (common with language runtime images), the container stops as soon as it starts. Keep it alive by running a long-lived process, CMD ["tail", "-f", "/dev/null"] in the image, or the entrypoint config field when you provision.

index.ts

const sandbox = await getOrCreateSandbox("data", {
  image: "data-tools",
  entrypoint: "tail -f /dev/null",
});

const sandbox = await getOrCreateSandbox("data", {
  image: "data-tools",
  entrypoint: "tail -f /dev/null",
});

Build a harness image

To run a long-lived service inside the sandbox, like the Claude Agent SDK server, EXPOSE its port and start it as the entrypoint. Build on hiversh/agent-cli, which already has the agent CLIs installed:

agent/Dockerfile

FROM node:22-slim

ENV IS_SANDBOX=1
WORKDIR /app

COPY package.json .
RUN npm install
COPY server.ts .

EXPOSE 3000
CMD ["npx", "tsx", "server.ts"]

FROM node:22-slim

ENV IS_SANDBOX=1
WORKDIR /app

COPY package.json .
RUN npm install
COPY server.ts .

EXPOSE 3000
CMD ["npx", "tsx", "server.ts"]

Bundle it:

hiver bundle ./agent --tag my-agent

hiver bundle ./agent --tag my-agent

Then provision from the tag and reach the service through the proxy, getPorts lists exposed ports, and proxyUrl(port) builds a URL that routes to the process inside:

index.ts

const sandbox = await getOrCreateSandbox("my-agent", { image: "my-agent" });

console.log(await sandbox.getPorts()); // [3000]
const res = await fetch(`${sandbox.proxyUrl(3000)}health`);
console.log(await res.text());

const sandbox = await getOrCreateSandbox("my-agent", { image: "my-agent" });

console.log(await sandbox.getPorts()); // [3000]
const res = await fetch(`${sandbox.proxyUrl(3000)}health`);
console.log(await res.text());

Multi-platform builds

Produce an image for multiple architectures in one bundle:

hiver bundle ./agent --tag my-agent --platform linux/amd64,linux/arm64

hiver bundle ./agent --tag my-agent --platform linux/amd64,linux/arm64

See the CLI reference for all bundle options.

Next: Mocking