How to build a custom sandbox image from a list of packages

On Runtime, building an image costs nothing. An account without credit stores its first three images free, for as long as you keep them. Without credit, a build counts toward the free usage, for the time the build runs. After that, a stored image costs $0.08 per decimal GB per 30-day month of its accounted storage (rate in force since 23 September 2026, pricing). Every sandbox started from the image has the packages already installed. It does not spend its first minute on pip install.

Build it and start from it

TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime();const image = await runtime.images.build(  { name: "data", recipe: { pip: ["pandas"], apt: ["jq"] } },  { onLog: (line) => console.log(line.text) },);await using sbx = await runtime.sandboxes.create({ image: "data" });console.log(  image.version,  (await sbx.exec("python3 -c 'import pandas; print(pandas.__version__)'")).stdout,);

Pythonfrom withruntime import Runtimeruntime = Runtime()image = runtime.images.build(name="data", recipe={"pip": ["pandas"], "apt": ["jq"]},                             on_log=lambda line: print(line["text"]))with runtime.sandboxes.create(image=image["id"]) as sbx:    print(sbx.exec("python3 -c 'import pandas; print(pandas.__version__)'").stdout)

Terminalimg=$(runtime images build --pip pandas --apt jq --name data)runtime sandboxes create --image "${img}"

build streams the log, waits until the image is ready, and throws with the build's own error if a step fails. images.create queues the same build and returns immediately. Use it for a job that should not wait.

What a recipe takes

The CLI covers the common case with --pip, --apt and --npm. For commands, files or env, use an SDK or a Dockerfile.

Make it start a server too

An image can say what runs when a sandbox starts from it, and when that sandbox counts as ready. The create call returns only once the server listens.

TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime();await runtime.images.build({  name: "api",  recipe: {    pip: ["fastapi", "uvicorn"],    files: [      {        path: "/workspace/main.py",        content:          'from fastapi import FastAPI\n\napp = FastAPI()\n\n@app.get("/")\ndef home():\n    return {"ok": True}\n',      },    ],  },  start: {    command: "uvicorn main:app --host 0.0.0.0 --port 8000",    readyPort: 8000,    readyTimeoutSeconds: 60,  },});const sbx = await runtime.sandboxes.create({ image: "api" });console.log(sbx.info.start); // { state: "ready", readyMs: ... }

start.state is ready, started (no ready check), timeout (the check did not pass within readyTimeoutSeconds, 60 by default, at most 300), or exited (the command ended first). (start and ready commands)

Recipes worth baking

• R, Java or Go for the code interpreter. Otherwise each sandbox installs them the first time it uses them: about 35 seconds for Java or Go, and 90 seconds for R, measured on 23 September 2026. Put them in apt to skip that.
• Docker. commands: ["enable-docker --no-start"] gives every sandbox Docker Engine, Buildx and Compose. Docker starts on the first docker command (Docker in a sandbox).
• Your agent's tools. A coding agent's CLI, linters and test runners. Each task then starts working immediately (coding agent sandbox).

Limits

The build runs in its own Firecracker virtual machine, with the same web access as a sandbox (limits).

Versions, tags and rebuilds

Each build of a name becomes its next version, and takes the tag latest or the tags you give. image on a create takes an id, name, name:tag or name@version. So production can pin data@3 while tests follow data.

A rebuild whose first steps match an earlier build of your account starts from the latest matching checkpoint. An identical build is copied immediately instead of built. Pass cache: false to build every step from scratch (faster rebuilds).

Mistakes to avoid

• Installing packages in every sandbox. Each fresh sandbox then pays for the download and install in running time. Build once.
• Passing both image and snapshot to a create. A sandbox starts from one or the other. A snapshot keeps a whole machine, memory included. An image keeps files.
• Giving a recipe and a Dockerfile together. A build takes exactly one source: a recipe, an image or a dockerfile.
• Forgetting old versions. Stored allocation is charged. Remove versions you no longer need with runtime images rm data@1.

A stored image is charged on its whole file (image storage pricing).

Facts on this page were checked on 26 October 2026.