Rehearse Cosmos SDK chain upgrades on your own machine.
Features · Install · Quick start · Screenshots · Documentation · Releases
forklab runs a local network of N validators for any Cosmos SDK chain, from a fresh genesis or from mainnet state forked out of a snapshot. Stop nodes, pass proposals, and swap binaries at the upgrade height from one CLI or a live terminal UI, so you can rehearse a chain upgrade before it happens for real.
It runs stock chain binaries and never patches the chain. Chain differences
live in profiles, and two ship built in: simd (the
Cosmos SDK example chain) and xrplevm (XRPL EVM, binary exrpd).
- Fresh or forked labs. Start from the chain's own genesis, or take over mainnet state with your validators holding about 90% of the voting power.
- N validators. Each node gets its own home, ports, and log. Stop one, kill one with SIGKILL, or restart one on another binary.
- Upgrade rehearsal with auto swap.
upgrade schedulesubmits and votes the proposal, then restarts every halted node on the new binary at the plan height. - Consensus you can see. Height, round, step, proposer, and each validator's prevote and precommit, live or as JSON.
- Agent-first CLI. Every command takes
--json, never prompts, and exits with a typed code. - A TUI on top of the CLI. Every screen, form, and action is a
forklab ... --jsoncommand, and the TUI shows it before it runs.
With Go 1.27 or later:
go install github.com/kevinpita/forklab/cmd/forklab@latestOr download a release archive for Linux or macOS (amd64 or arm64) from the
releases page, check it
against checksums.txt, and put forklab on your PATH:
tar xzf forklab_0.1.0_linux_amd64.tar.gz
install forklab ~/.local/bin/
forklab versionWith Nix, run nix run github:kevinpita/forklab. The flake also exports
overlays.default, which adds pkgs.forklab. The package installs shell
completions and the agent skill at share/forklab/.agents/skills/forklab.
The version that the package reports is the commit hash.
Note
A go install build reports its version as dev.
Profiles with git or src binaries build the chain from source, so they need
git and Go on the machine.
forklabWith no lab on disk, forklab opens a wizard that builds the lab create
command as you answer, then offers to bring the lab up. From there, 1-8
switch panels, Ctrl+K opens the command palette, c shows the commands
behind the current panel, and ? lists the keys. See the TUI guide.
forklab lab create demo --profile simd --version 0.53.8 --validators 2
forklab lab up demo
forklab status
forklab node stop 1
forklab gov submit --template text --title "hello" --auto-voteThe simd profile builds simd v0.53.8 from the cosmos-sdk repository the
first time you use it. To rehearse an upgrade, start an xrplevm lab on
11.1.1 and schedule 11.2.0:
forklab lab create xrp --profile xrplevm --version 11.1.1 --validators 2 --chain-id xrplevm_1449999-1
forklab lab up xrp
forklab upgrade schedule 11.2.0 --in 45
forklab upgrade statusTip
Every command accepts --json and prints one {"ok":...} envelope on
stdout, so scripts and agents drive forklab the same way you do. See the
CLI reference.
First run. A seven-step wizard creates your first lab.
Nodes and live logs. The left column holds every panel. The main pane follows the selected node's log.
Consensus. The round in progress, vote bars against the 2/3 mark, each validator's votes, and the peer map.
Automatic swap. Both exrpd nodes halted at the plan height, and the
supervisor restarted them on 11.2.0.
| Page | Covers |
|---|---|
| TUI | Panels, keys, forms, the wizard, themes, the palette, and the command preview |
| CLI reference | Every command, the --json envelope, streams, exit codes, and files |
| Profiles | Profile fields, genesis patches, and binary sources |
| Fork mode | Labs forked from mainnet snapshots |
| Upgrades | Scheduling, automatic and manual swaps, and cancelling |
| Development | Toolchain, recipes, end-to-end tests, and screenshots |