Skip to content

Self-hosting a host

The hosted service is the simple path. If you want forks on hardware you control, the CLI can drive a host of your own directly, without the control plane.

A Linux machine with KVM (bare metal, or a VM with nested virtualisation), running forkstage-node: the daemon that boots Firecracker microVMs, bakes snapshots and forks them. Optionally forkstage-edge, which gives forks public addresses under a wildcard domain with TLS.

Requirements: Ubuntu 24.04, /dev/kvm, an XFS or ext4 data disk, outbound internet for image pulls, and SSH access with sudo for the user you connect as.

The repository’s infra/host/ folder has the bootstrap script, the systemd units and the build scripts for the guest kernel and root filesystem. In short:

Terminal window
# on the host
sudo bash infra/host/bootstrap.sh

installs Firecracker, Docker, the daemon and the network rules, and writes the daemon’s token to /srv/forkstage/node.token.

Terminal window
forkstage host ubuntu@203.0.113.10 --identity ~/.ssh/id_ed25519

The CLI fetches the daemon’s token over SSH once and keeps it in ~/.forkstage/config.json. From then on, with --driver firecracker (or by default when you are not signed in to the hosted service), bake, up, exec, sh, test and down go to that host through SSH tunnels. Forks’ ports are forwarded to your machine, so FORKSTAGE_URL and DATABASE_URL point at 127.0.0.1.

Terminal window
forkstage bake --driver firecracker
forkstage up --driver firecracker

Without a host and without signing in, forkstage up runs the stack in Docker on your machine (--driver local). No snapshots, no 100 ms forks, but the same recipe and the same commands, which makes it a good way to check a recipe before baking.

Self-hosted mode has no dashboard, no GitHub App and no proofs in a workspace; proofs stay in ~/.forkstage/proofs and forkstage proof <id> prints them. Those need the control plane, which is not open-sourced yet.