from bare metal
to a running VM

confirm KVM works

Check that virtualization is enabled and the kernel module is loaded before installing anything else.

ls -l /dev/kvm
lsmod | grep kvm   # kvm_intel or kvm_amd should be listed

If /dev/kvm is missing, enable virtualization (VT-x/AMD-V) in the BIOS/hypervisor and reboot.

install the Firecracker binary

Download the latest release for your architecture and place it somewhere fc-node's findBinary lookup will see — on $PATH, or under /usr/local/bin, /usr/local/sbin, or /opt/firecracker/bin.

ARCH=$(uname -m)
release_url=$(curl -s https://api.github.com/repos/firecracker-microvm/firecracker/releases/latest \
  | grep browser_download_url | grep "${ARCH}.tgz" | cut -d '"' -f4)
curl -L "$release_url" -o firecracker.tgz
tar xzf firecracker.tgz
sudo install -m 0755 release-*/firecracker-*-"${ARCH}" /usr/local/bin/firecracker
firecracker --version

install nftables, WireGuard, and iproute2

These provide the host firewall, the cross-node overlay, and general Linux networking. On Debian/Ubuntu:

sudo apt update
sudo apt install -y nftables wireguard-tools iproute2

On a NixOS host, add to configuration.nix instead:

networking.nftables.enable = true;
environment.systemPackages = with pkgs; [ wireguard-tools iproute2 ];

install Go

curl -LO https://go.dev/dl/go1.25.0.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.25.0.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin
go version

install and configure PostgreSQL

Only needed on the host running fc-orchestrator. Create the database and role the orchestrator expects by default (override with DATABASE_URL):

sudo apt install -y postgresql
sudo -u postgres psql -c "CREATE DATABASE fcorch;"
sudo -u postgres psql -c "CREATE USER fcorch WITH PASSWORD 'fcorch';"
sudo -u postgres psql -c "GRANT ALL ON DATABASE fcorch TO fcorch;"

The orchestrator runs its own schema migrations on startup — no manual SQL beyond creating the database.

build the guest OS image with Nix

The guest is a minimal NixOS built with microvm.nix against the configuration.nix already checked into this project — the same recipe used to build the base image running on this server. Install Nix with flakes enabled first:

sh <(curl -L https://nixos.org/nix/install) --daemon
mkdir -p ~/.config/nix
echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf

Wrap the existing configuration.nix in a flake that pulls in microvm.nix:

# flake.nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.05";
    microvm.url = "github:astro/microvm.nix";
    microvm.inputs.nixpkgs.follows = "nixpkgs";
  };
  outputs = { self, nixpkgs, microvm }: {
    packages.x86_64-linux.firecracker-base =
      (nixpkgs.lib.nixosSystem {
        system = "x86_64-linux";
        modules = [ microvm.nixosModules.microvm ./configuration.nix ];
      }).config.microvm.declaredRunner;
  };
}

Build it, then copy the three artifacts fc-node expects at /opt/firecracker/base/:

nix build .#firecracker-base
sudo mkdir -p /opt/firecracker/base
sudo cp result/vmlinux         /opt/firecracker/base/vmlinux
sudo cp result/initrd          /opt/firecracker/base/initrd
sudo cp result/store.erofs     /opt/firecracker/base/store.erofs

build and run fc-orchestrator

cd fc-orchestrator
go build -o fc-orchestrator .

export DATABASE_URL="postgres://fcorch:fcorch@localhost:5432/fcorch?sslmode=disable"
export LISTEN_ADDR=":8080"
./fc-orchestrator

On startup it connects to Postgres, runs migrations, and starts listening on LISTEN_ADDR — you should see connected to database in the log.

build and run fc-node

cd fc-node
go build -o fc-node .

export NODE_ID="node-1"
export LISTEN_ADDR=":8081"
export NODE_ADDR="<this-host-ip>:8081"
export ORCHESTRATOR_URL="http://<orchestrator-host>:8080"

sudo -E ./fc-node

fc-node must run as root. On startup it loads (or generates) its WireGuard keypair, installs the nftables firewall baseline, and registers itself with the orchestrator — registration blocks until the orchestrator is reachable.