Documentation
Images
Images define the sandbox filesystem and installed tools.
Prebuilt Images
Prebuilt images are the fast path: no build job, no dependency install during sandbox create.
| Image | Reference | Includes |
|---|---|---|
| Ubuntu 24.04 | ubuntu-24.04:base | Base Ubuntu image with CA certificates, curl, and git. |
| Python 3.12 | python-3.12:base | Ubuntu image with Python 3.12, pip, venv, curl, and git. |
| Python 3.12 data | python-3.12-data:base | Python 3.12 with numpy, pandas, requests, curl, and git. |
| Node.js 22 | node-22:base | Node.js 22 image with curl, git, and package-manager friendly defaults. |
| Agents | agents:base | Codex CLI, Claude Code, Node.js 22, Python 3.12, git, ripgrep, jq, and build tools. |
Use an Image
String image values are Syva image references. Use a prebuilt ref from this page, a project image ref, or a ref returned by an image recipe build.
const sandbox = await Sandbox.create({
image: "python-3.12:base",
});Public Registry Images
Public Docker and OCI registry images can be used as recipe bases. Pass the registry reference to Image.fromRegistry or Image.from_registry, then pass the resulting recipe to Sandbox.create.
The first launch builds the recipe into a Syva image artifact and waits for it to become ready. Later launches reuse the registered artifact. Do not pass a registry ref like node:22 as a string sandbox image unless that ref is already registered as a Syva image.
const image = Image
.fromRegistry("node:22")
.runCmd("npm install -g pnpm");
const sandbox = await Sandbox.create({ image });Image Recipes
Recipes are immutable. Each method returns a new recipe, which makes refs deterministic and reusable.
const image = Image
.fromRegistry("node:22")
.runCmd("npm install -g pnpm")
.workdir("/workspace");Recipe Builds
A new recipe builds once. Later launches reuse the registered artifact. Build inputs can start from Syva base images or public registry images.
const image = Image
.fromRegistry("node:22")
.runCmd("npm install -g pnpm")
.setStartCommand("pnpm dev");
const sandbox = await Sandbox.create({ image });