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.
What a host is
Section titled “What a host is”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.
Set it up
Section titled “Set it up”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:
# on the hostsudo bash infra/host/bootstrap.shinstalls Firecracker, Docker, the daemon and the network rules, and writes the daemon’s token to /srv/forkstage/node.token.
Point the CLI at it
Section titled “Point the CLI at it”forkstage host ubuntu@203.0.113.10 --identity ~/.ssh/id_ed25519The 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.
forkstage bake --driver firecrackerforkstage up --driver firecrackerLocal Docker, for comparison
Section titled “Local Docker, for comparison”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.
What you do not get
Section titled “What you do not get”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.