Templates

Pre-built rootfs images for common use cases. Templates boot in under a second from cached snapshots.

Built-in templates

claude-code

The primary product template. Everything Claude Code needs in a single image.

Property	Value
Base image	debian:bookworm-slim
Default vCPU	2
Default memory	2048 MiB

Pre-installed:

• Claude Code CLI (@anthropic-ai/claude-code@latest)
• Node.js 22 LTS
• Rust (stable toolchain via rustup)
• Python 3 + uv
• Git, curl, jq, ripgrep, fd-find, openssh-client, build-essential

with client.sandbox(image="claude-code", memory_mib=2048) as sb:
    result = sb.exec(["claude", "--print", "Explain this codebase"])

python

Minimal Python environment with uv for fast package management.

Property	Value
Base image	debian:bookworm-slim
Default vCPU	2
Default memory	512 MiB

Pre-installed:

• Python 3 + pip + venv
• uv (fast Python package installer)
• Git, curl, ca-certificates

with client.sandbox(image="python") as sb:
    sb.exec(["uv", "pip", "install", "pandas", "numpy"])
    result = sb.exec(["python", "-c", "import pandas; print(pandas.__version__)"])

nodejs

Minimal Node.js environment.

Property	Value
Base image	debian:bookworm-slim
Default vCPU	2
Default memory	512 MiB

Pre-installed:

• Node.js 22 LTS + npm
• Git, curl, ca-certificates

with client.sandbox(image="nodejs") as sb:
    sb.exec(["npm", "init", "-y"])
    sb.exec(["npm", "install", "express"])

Template comparison

Template	Languages	Default memory	Use case
claude-code	Node.js, Rust, Python	2048 MiB	Claude Code sessions, multi-language tasks
python	Python	512 MiB	Data science, scripting, ML tasks
nodejs	Node.js	512 MiB	Web development, tooling

Custom templates

Build your own templates from a Containerfile. The template system uses Podman to build an ext4 rootfs that Firecracker boots directly.

How it works

1. You define a TemplateSpec -- name, base image, apt packages, setup commands, and environment variables.
2. The template builder generates a Containerfile and builds via Podman.
3. The result is an ext4 rootfs image cached locally (or in MinIO for distributed deployments).
4. VMs boot from the cached rootfs snapshot. Session writes go to a CoW overlay.

Layer stack

+---------------------------+
| Session diff (CoW/NBD)    |  ← per-session writes (pip install, git clone)
+---------------------------+
| Template snapshot          |  ← pre-built rootfs with your deps
+---------------------------+
| Base rootfs (Debian)      |  ← guest-agent + kernel essentials
+---------------------------+

Example: ML template

A custom spec that pre-installs PyTorch and Jupyter:

{
  "name": "python-ml",
  "base_image": "docker.io/library/debian:bookworm-slim",
  "apt_packages": ["python3", "python3-pip", "python3-venv", "git", "curl"],
  "setup_commands": [
    "pip install torch numpy pandas jupyter --break-system-packages"
  ],
  "env": { "PYTHONDONTWRITEBYTECODE": "1" },
  "vcpu": 2,
  "memory_mib": 2048
}

Templates are content-addressable -- two identical specs produce the same hash, so rebuilds are free.

Generated Containerfile

The spec above produces roughly:

FROM docker.io/library/debian:bookworm-slim

RUN apt-get update && apt-get install -y --no-install-recommends \
    python3 python3-pip python3-venv git curl && \
    rm -rf /var/lib/apt/lists/*

RUN pip install torch numpy pandas jupyter --break-system-packages

ENV PYTHONDONTWRITEBYTECODE="1"

RUN mkdir -p /workspace
WORKDIR /workspace

COPY target/agent /sbin/agent