Skip to content

Host setup

The bootstrap script handles the whole daemon-side install on a fresh KVM-capable Linux box. Re-run it any time to pick up upgrades — idempotent.

What the script does

flowchart TD
    Pre[Preflight: sudo? /dev/kvm? supported arch?]
    Apt[apt: python3-venv, iproute2, iptables, e2fsprogs, ...]
    FC[Install latest Firecracker + jailer]
    Layout[/srv/firebox/{kernels,rootfs,templates,vms,tmp,ips}/]
    Kernel[Download CI kernel]
    Root[Download Ubuntu squashfs → build base.ext4 → write /firebox-init]
    Net[fbr0 bridge + 10.42.0.0/24 + NAT + firebox-network.service]
    Perm[user → kvm group, NOPASSWD sudo]
    Pkg[Clone repo → venv → pip install -e firebox[daemon]]
    Tok[Generate /etc/firebox/token + 0640 root:kvm]
    Sys[Install firebox-daemon.service, enable + start]
    Done[Print endpoint + token]

    Pre --> Apt --> FC --> Layout --> Kernel --> Root --> Net --> Perm --> Pkg --> Tok --> Sys --> Done

Run it

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

Or clone first if you want to read it before running:

git clone git@github.com:LovroK23/firebox.git
cd firebox
sudo ./scripts/firebox-host-bootstrap.sh

Flags

sudo ./scripts/firebox-host-bootstrap.sh \
    --user lovrok                   \  # daemon user (default: $SUDO_USER)
    --repo git@github.com:org/firebox.git \  # firebox source
    --ref main                      \  # branch / tag / sha
    --kernel-tag v1.15              \  # Firecracker-CI kernel version
    --port 8765                        # daemon listen port

What's expected at the end

  • firebox-network.service (oneshot, ran at boot — sets up bridge + NAT)
  • firebox-daemon.service (runs uvicorn against /opt/firebox/.venv)
  • /etc/firebox/token — the bootstrap admin token
  • /etc/firebox/tokens.d/ — empty, mode 2770 root:kvm
  • /srv/firebox/ populated with kernel + base.ext4 + scratch dirs

Verify

systemctl status firebox-daemon firebox-network
curl -sS http://localhost:8765/healthz
ls -la /srv/firebox /etc/firebox

From a client:

export FIREBOX_URL=http://your-host:8765
echo "<the-printed-token>" > ~/.firebox/token
firebox doctor

Upgrades

Re-run the bootstrap. It'll:

  • pull the latest Firecracker if a newer release is on GitHub
  • git pull /opt/firebox/repo
  • pip install -e .[daemon] again (picks up dep bumps)
  • restart the systemd unit if its file changed

Existing tokens, sandboxes, templates are untouched.

Tear down

sudo systemctl disable --now firebox-daemon firebox-network
sudo rm /etc/systemd/system/firebox-{daemon,network}.service
sudo rm /usr/local/sbin/firebox-network-setup
sudo iptables -t nat -D POSTROUTING -s 10.42.0.0/24 ! -o fbr0 -j MASQUERADE
sudo ip link del fbr0
sudo rm -rf /srv/firebox /etc/firebox /opt/firebox
sudo rm /etc/sudoers.d/firebox-*
sudo userdel kvm    # only if you don't use kvm group otherwise

Doesn't touch the Firecracker binary in /usr/local/bin — drop those manually if you want.