Templates

A template is a writable ext4 rootfs the daemon clones into a fresh overlay every time you spawn a sandbox. They start as a Dockerfile build, end as a file under /srv/firebox/templates/.

Built-in templates

Name	Size	What it has
base	~480 MB	Ubuntu 24.04 minimal (Firecracker-CI rootfs)
browser-use	~6 GB	+ patchright, Chromium, curl_cffi, faster-whisper, Xvfb, x11vnc

base is enough for shell tasks, file processing, scripting. Spin it up when you don't need a browser.

browser-use is the heavy template. First spawn pays for the Chromium download once, every spawn after that is just a sparse copy.

Build your own

Any ARM64 / x86_64 (matching your host) Dockerfile works. From the client side:

firebox template build -t my-template ./examples/jq-demo/Dockerfile
firebox template list
firebox template rm my-template

The build pipeline:

flowchart LR
    DF["Your Dockerfile"]
    CTX["Context dir<br/>(tar streamed via SSH)"]
    DOC["docker build<br/>on the host"]
    EXP["docker export<br/>(container -> tar)"]
    EXT["Truncate + mkfs.ext4<br/>+ extract"]
    INIT["Inject /firebox-init<br/>from base.ext4"]
    OUT["/srv/firebox/templates/<br/>my-template.ext4"]

    DF --> CTX --> DOC --> EXP --> EXT --> INIT --> OUT

The /firebox-init script is copied from the daemon's pristine base rootfs so every template knows how to bring up the network, branch into either an agent or a one-shot cmd.sh, and shut down cleanly.

A minimal Dockerfile

FROM ubuntu:24.04
ENV DEBIAN_FRONTEND=noninteractive PIP_BREAK_SYSTEM_PACKAGES=1

RUN apt-get update && apt-get install -y --no-install-recommends \
        python3 python3-pip iproute2 ca-certificates curl jq \
    && apt-get clean && rm -rf /var/lib/apt/lists/*

# Anything you bake here lives in the rootfs of every sandbox spawned
# from this template — pre-warm pip caches, dropped binaries, models...
RUN pip install --no-cache-dir requests pandas

# Templates can pre-set env vars for everything that runs in the VM
# by writing /etc/firebox-env.d/*.env. firebox-init sources them at
# boot before either /firebox/cmd.sh or /firebox/agent.py runs.
RUN mkdir -p /etc/firebox-env.d && \
    printf '%s\n' \
        'export PYTHONUNBUFFERED=1' \
        > /etc/firebox-env.d/my-template.env

WORKDIR /work

Picking the right size

firebox template build defaults to a 2 GB rootfs. Override:

firebox template build -t fat-template --size 8 ./Dockerfile

Size is the upper bound (sparse), not the actual disk usage. A 2 GB sparse template with 400 MB of real data is 400 MB on disk — but the guest sees 2 GB free for runtime writes.

Using a template

with Sandbox.create(template="my-template", ttl_seconds=300) as sb:
    sb.run("python3 -c 'import requests; print(requests.__version__)'")

firebox sandbox create --template my-template --ttl 300

Template lifecycle on the host

• firebox template build writes /srv/firebox/templates/<name>.ext4
• Existing sandboxes spawned from an older version stay on the old ext4 (sparse-copied at spawn time, independent of the template file)
• firebox template rm deletes the file; future spawns fail until you rebuild
• firebox template list shows what the host knows about

What /firebox-init does inside the VM

flowchart TD
    Boot[Kernel boot] --> Init[/firebox-init/]
    Init --> Mount[mount /proc /sys]
    Mount --> Net{net.env present?}
    Net -- yes --> Cfg[ip addr / route / DNS]
    Net -- no --> Skip
    Cfg --> EnvD[Source /etc/firebox-env.d/*.env]
    Skip --> EnvD
    EnvD --> Branch{Mode?}
    Branch -- agent.py present --> Agent[/exec python3 /firebox/agent.py/]
    Branch -- cmd.sh present --> Batch[Run /firebox/cmd.sh, emit markers, reboot]
    Branch -- neither --> Err[exit 127]

Common patterns

• Pre-warm a Python venv for an agent that does specific work, so cold start is fast.
• Bake credentials never — pass them at runtime via the agent's env or via sb.files.write for short-lived secrets.
• One template per agent role — the same daemon hosts an analytics template, a browser template, an LLM-eval template, etc.