Skip to content

Quickstart

Five minutes from zero to a sandbox you can drive from anywhere.

Prerequisites

  • A Linux box with KVM exposed (/dev/kvm exists). Bare metal, dedicated server, or a VPS that allows nested virtualization.
  • A laptop or other server you want to call from.

If /dev/kvm doesn't exist, the host can't run microVMs — most cloud shared instances (Hetzner Cloud, Oracle A1) are out. Hetzner dedicated, OVH bare metal, your own homelab, etc. all work.

1. Install the daemon on your host

ssh user@your-host
curl -fsSL https://raw.githubusercontent.com/LovroK23/firebox/main/scripts/firebox-host-bootstrap.sh \
  | sudo bash

The script:

  • installs Firecracker + jailer
  • downloads kernel + Ubuntu rootfs
  • builds base.ext4
  • sets up fbr0 bridge and NAT
  • creates a venv at /opt/firebox/.venv
  • generates /etc/firebox/token
  • enables the firebox-daemon systemd unit

It prints the daemon URL and admin token at the end. Copy the token now.

2. Configure your client

On a different machine — laptop, agent server, anywhere with Python 3.10+:

pip install git+ssh://git@github.com/LovroK23/firebox.git

mkdir -p ~/.firebox
echo "<the-token-from-step-1>" > ~/.firebox/token
chmod 600 ~/.firebox/token

export FIREBOX_URL=http://your-host:8765
firebox doctor

Expected output:

✓ python                 3.11.x
• FIREBOX_URL            http://your-host:8765
✓ auth token             file ~/.firebox/token (49 bytes)
✓ daemon /healthz        {"ok":true,"ts":...}

3. First sandbox

firebox sandbox create --ttl 60
# → ad0c1f29

firebox sandbox run ad0c1f29 "uname -a; df -h /"
firebox sandbox close ad0c1f29

from firebox.sandbox import Sandbox

with Sandbox.create(ttl_seconds=60) as sb:
    r = sb.run("uname -a; df -h /")
    print(r.stdout)
# closed automatically on context exit

Drop into ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "firebox": {
      "command": "python3",
      "args": ["-m", "firebox.mcp.server"],
      "env": {
        "FIREBOX_URL": "http://your-host:8765",
        "FIREBOX_TOKEN": "<token>"
      }
    }
  }
}

Restart Claude Desktop. The 22 firebox tools appear in the model's toolbox automatically.

4. A real example — open a page in headless Chrome

from firebox.sandbox import Sandbox

with Sandbox.create(template="browser-use", mem_mib=2048, ttl_seconds=300) as sb:
    sb.browser.start()                                    # stealth on by default
    sb.browser.navigate("https://news.ycombinator.com")
    titles = sb.browser.text_all(".titleline > a")[:5]
    for t in titles:
        print("•", t)

The browser-use template ships with Playwright + patchright + curl_cffi + faster-whisper. First spawn pulls 6 GB of rootfs once, then sandboxes boot in ~1.5 s.

What next?