Repository navigation
Installation
This page gets the hairspring command onto your machine, and, if you have a suitable Linux machine, sets up the extra pieces needed to test real programs. If you only want to look around, the first section is all you need.
Hairspring is experimental. The release this guide describes is the pre-release v0.1-RC2. Read Limits-and-Honesty before you rely on a result.
Hairspring has three ways of running a target (see Concepts-and-Vocabulary). They do not all run everywhere.
| Part | macOS (Apple silicon) | Linux x86-64 |
|---|---|---|
The hairspring command, the stored results, the web UI (hairspring serve) |
Yes | Yes |
sim targets (a state machine written against the Rust Sim trait, such as the built-in demos) |
Yes | Yes |
wasm targets |
Yes (the README lists this; this guide does not use it) | Yes |
| The guest SDKs, run natively inside your own program | Yes | Yes |
process targets (an unmodified Linux program, scheduled by Hermit) |
No | Yes, with Hermit and a hardware performance counter |
The reason is Hermit, the third-party deterministic scheduler behind the process backend. It runs on Linux x86-64 only and needs hardware performance counters. Apple silicon cannot run it. The project's own notes say Docker Desktop on a Mac does not help either, and that ordinary cloud virtual machines and containers were not tested and often hide the counters. Only bare metal was tested.
If you are on a Mac, you can still follow Your-First-Run, read the examples, and write and build your own program with an SDK. You cannot run it under Hermit until you have a suitable Linux machine. Troubleshooting shows the exact message you will see if you try.
Release v0.1-RC2 has three files:
| File | What it is |
|---|---|
hairspring-linux-x86_64 |
Linux x86-64, built on Ubuntu 22.04 |
hairspring-macos-arm64 |
macOS on Apple silicon |
SHA256SUMS |
the expected checksum of each binary |
They are on the release page: https://github.com/spiculedata/hairspring/releases/tag/v0.1-RC2. The release is marked as a pre-release. The binary reports its version as hairspring 0.1.0 (c2687b8 2026-11-05): the crate version, then the commit it was built from and that commit's date. The crate version is not v0.1-RC2; the commit is what identifies the build. The earlier pre-release, v0.1-RC1, printed only hairspring 0.1.0.
Upgrading from v0.1-RC1: the first RC2 command migrates an existing results database (schema version 5 to version 8), after which RC1 refuses it with database schema version 8 is not supported (expected 5). Stop RC1 servers and workers and back the database up first (sqlite3 .hairspring/hairspring.db ".backup '.hairspring/hairspring-rc1-backup.db'"); to go back, restore the backup. Version 8 adds a table, run_inputs, in which runs of built-in simulated targets record digests of their inputs; Hermit and WASM runs record none. On PostgreSQL, run the first RC2 command as the role that owns the tables, and give any role that only reads and writes rows GRANT SELECT, INSERT, DELETE ON <schema>.run_inputs TO <role> first; the index it builds takes a SHARE lock on runs, so writes of runs wait until the upgrade commits (the section below describes the same step for version 7). The release notes have the details.
Download the binary for your machine and SHA256SUMS, then check the binary before you run it. On a Mac:
curl -fsSLO https://github.com/spiculedata/hairspring/releases/download/v0.1-RC2/hairspring-macos-arm64
curl -fsSLO https://github.com/spiculedata/hairspring/releases/download/v0.1-RC2/SHA256SUMS
grep macos SHA256SUMS | shasum -a 256 -cYou should see hairspring-macos-arm64: OK. On Linux, swap in hairspring-linux-x86_64 and use sha256sum -c in place of shasum -a 256 -c:
grep linux SHA256SUMS | sha256sum -c(We ran the macOS commands. The Linux checksum file entry and the Linux binary exist on the release, and the check has the same shape, but we did not run the Linux version of the check.)
Then make it executable and put it somewhere on your PATH:
chmod +x hairspring-macos-arm64
mkdir -p ~/.local/bin
mv hairspring-macos-arm64 ~/.local/bin/hairspring
hairspring --versionExpected output:
hairspring 0.1.0 (c2687b8 2026-11-05)
What the checksum does and does not tell you. SHA256SUMS is published in the same place as the binaries. It catches a corrupt or truncated download. It does not prove who built the binary, because anyone who could replace the binary could replace the checksum file too. If you need that, get a hash from a second source you trust and use the installer's --sha256 option (below).
The release binaries include the web UI.
The repository has scripts/install.sh. It downloads the right binary for your platform, verifies its checksum against SHA256SUMS, installs it, and then runs hairspring doctor and hairspring doctor --process-backend so you can see what the machine can do. It never uses sudo, never changes kernel settings, and writes only to its install prefix and its own scratch directory.
You need a clone of the repository to use it:
git clone https://github.com/spiculedata/hairspring
cd hairspring
bash scripts/install.sh --version v0.1-RC2Use bash scripts/install.sh, as above. In the version of the repository we checked, the script files are stored without the executable bit, so typing scripts/install.sh on its own gives permission denied. (chmod +x scripts/*.sh also works.)
Here is the output from a run on an Apple silicon Mac, installing into a scratch directory with --prefix. It was recorded against v0.1-RC1; the release name and the version: line are changed to what RC2 prints, and the RC2 run itself has not been recorded here.
plan: download hairspring-macos-arm64 from release v0.1-RC2 of spiculedata/hairspring, verify its sha256, install to <prefix>/bin
downloading hairspring-macos-arm64 and SHA256SUMS from https://github.com/spiculedata/hairspring/releases/download/v0.1-RC2
sha256 verified: <64 hex digits>
version: hairspring 0.1.0 (c2687b8 2026-11-05)
installed: <prefix>/bin/hairspring
sha256: <64 hex digits>
note: <prefix>/bin is not on your PATH; add it to run 'hairspring' directly
running: hairspring doctor
lock-lease: deterministic over 8 seeds x 200 steps
pubsub-atomic: deterministic over 8 seeds x 200 steps
pubsub-buggy: deterministic over 8 seeds x 200 steps
running: hairspring doctor --process-backend
process backend: prerequisites on this machine
platform FAIL macos aarch64
...
note: this machine cannot run the process backend (details above). The sim and wasm backends are not affected.
The FAIL lines on a Mac are the honest answer, not an installation fault. The script still exits 0.
Options worth knowing (from bash scripts/install.sh --help):
| Option | Meaning |
|---|---|
--prefix DIR |
install to DIR/bin/hairspring; the default is $HOME/.local
|
--version TAG |
download that release instead of building |
--from-source |
build the checkout (the default when you give no --version) |
--sha256 HEX |
also require the downloaded binary to have exactly this hash, which you obtained some other way |
--with-ui |
source builds only: build the web UI first (needs node and npm) |
--require-process-backend |
exit 1 if this machine cannot run the process backend; by default that is reported and the script succeeds |
--dry-run |
check the arguments, platform and tools; download, build and write nothing. With --version TAG it also checks that the release exists: it exits 1 with release TAG not found if not, and only warns if it cannot reach GitHub. Without --version it checks the source-build prerequisites: cargo, a C compiler and linker (cc), and with --with-ui also node and npm. It names what to install (sudo apt-get install -y build-essential on Debian and Ubuntu, xcode-select --install on macOS) and exits 1 if something is missing |
Release assets exist for Linux x86-64 and macOS arm64 only. On any other platform the script tells you to build from source. Exit codes: 0 success, 1 a check or verification failed, 2 usage error.
You need a stable Rust toolchain (https://rustup.rs). From a clone:
cargo build --release -p hairspring-cli
export PATH="$PWD/target/release:$PATH"
hairspring --versionhairspring --version on a source build prints the commit of your checkout and that commit's date, for example hairspring 0.1.0 (<sha7> <date>). A build from a source archive (no .git), or a Docker image built without the HAIRSPRING_BUILD_COMMIT and HAIRSPRING_BUILD_DATE build arguments, prints hairspring 0.1.0 (unknown). The line is the same each time the same commit is built.
On the Mac used for this guide a clean release build took about a minute and a half. For the web UI to be built into the binary, run make ui first (it needs node and npm), or use bash scripts/install.sh --with-ui. Without it, hairspring serve still works, but the page at / is a placeholder.
bash scripts/install.sh with no --version does a source build with cargo build --release --locked and installs to ~/.local/bin.
hairspring targets
hairspring doctorhairspring targets lists the built-in demo targets:
lock-lease sim Lease-based lock service; a paused client writes after its lease expired (split brain)
pubsub-atomic sim Same consumer with atomic check+apply+record (the fix; should pass)
pubsub-buggy sim At-least-once consumer; check, apply and record are separate steps (duplicate effect)
hairspring doctor runs each simulation target on several seeds twice and checks that the same seed gives the same trace:
lock-lease: deterministic over 8 seeds x 200 steps
pubsub-atomic: deterministic over 8 seeds x 200 steps
pubsub-buggy: deterministic over 8 seeds x 200 steps
Now go to Your-First-Run.
A release that uses database schema version 7 adds two indexes to the results database and changes nothing else. Opening an older database with it upgrades it in place.
-
Back up first, and stop every older server and worker that uses the database. See Upgrading-and-Versions.
-
On SQLite there is nothing else to do. The upgrade holds the write lock for its duration, so writers wait.
-
On PostgreSQL, run the first open once as the role that owns the schema's tables (see Troubleshooting if you see
must be owner of table). Writes tofailuresandrun_propertieswait while the two indexes build. On one store of 300,000 failures on one machine this took under a second; expect longer on bigger stores, and do not rely on that figure. -
To avoid the wait on PostgreSQL, build the indexes beforehand, under these names:
CREATE INDEX CONCURRENTLY failures_created ON failures(created_at, seq); CREATE INDEX CONCURRENTLY run_properties_violation ON run_properties(run_id, idx) WHERE status = 'violation';
Hairspring then finds them and only sets the version. A failed concurrent build leaves an invalid index: drop it (
DROP INDEX failures_created) before upgrading.
There is no automatic downgrade. To go back, restore your backup. If you have no backup, stop every server and worker and
set the stored version back to 6 by hand: PRAGMA user_version = 6 on SQLite, UPDATE schema_version SET version = 6 on
PostgreSQL. Version 7 has the same tables and columns as version 6, and a version 6 release ignores the two indexes. We
read this in the architecture document and the code; we did not run it here.
A release that uses database schema version 8 adds one table, run_inputs (the fingerprints of what each run executed
with; see Concepts-and-Vocabulary), and one index on runs. No existing row is rewritten, and runs stored before the
upgrade simply have no fingerprints.
-
Back up first, and stop every older server and worker that uses the database. See Upgrading-and-Versions.
-
On SQLite there is nothing else to do. The upgrade holds the database-wide write lock, so every write waits, up to the 5 second busy timeout, and then fails.
-
On PostgreSQL, run the first open once as the role that owns the schema's tables (see Troubleshooting if you see
must be owner of table). Writes torunswait while the index builds. -
Still on PostgreSQL, before you start anything else after the upgrade, as the owner grant every other role that uses the database the new table:
GRANT SELECT, INSERT, DELETE ON <schema>.run_inputs TO <role>;
A role without those three rights is refused when it opens the database, before anything is changed, with this statement in the message (see Troubleshooting). The owner and superusers need nothing.
-
To avoid the long wait on PostgreSQL, build the index beforehand (PostgreSQL only; the SQLite index is on
runs(target, created_at)and is created for you):CREATE INDEX CONCURRENTLY runs_target_created ON runs(target, created_at, seq);
Hairspring then finds it. That avoids the long wait, not all of it: creating the new table still takes a brief lock on
runs. A failed concurrent build leaves an invalid index: drop it (DROP INDEX runs_target_created) before upgrading.
If a table or index of one of these names already exists with a different definition, Hairspring refuses to open, rolls the whole upgrade back and leaves the database at version 7, saying which object to rename or drop.
There is no automatic downgrade. To go back, restore your backup. If you have no backup, stop every server and worker,
drop run_inputs and runs_target_created if you wish, and set the stored version back to 7 by hand: PRAGMA user_version = 7 on SQLite, UPDATE schema_version SET version = 7 on PostgreSQL. A version 7 release ignores the new
objects. We read this in the architecture document and checked the upgrade and the refusals with tests against scratch
SQLite and PostgreSQL databases; we have not run it against a long-lived store.
Skip this section until you have a Linux x86-64 machine you can set up. Everything here is copied from the project's scripts and documentation; we could not run it on the Mac used to write this guide. The Mac-side behaviour of the same scripts is shown where we ran it.
| Need | Why |
|---|---|
| Linux on x86-64, on bare metal or a virtual machine that passes the CPU's performance counters through | Hermit counts hardware events to schedule threads deterministically. Ordinary cloud VMs and containers were not tested and often do not expose the counters |
kernel.perf_event_paranoid low enough for your user, or run as root |
opening a hardware counter |
kernel.yama.ptrace_scope of 0 or 1, or run as root (2 needs root; 3 disables tracing) |
Hermit traces the program |
| Linux 6.9 or newer (recommended) | older kernels take a slower tracing path; schedules are not affected, timeouts may be |
To build Hermit: git, a C compiler, pkg-config, libunwind and liblzma development files, and rustup
|
Hermit is built from source; there is no binary download |
The scripts never use sudo, never change a kernel setting and never install system packages. When a setting is in the way they name it and leave the decision to you. Lowering a security setting is a trade-off for the owner of the machine.
Privileges. The project's measurements ran Hermit as root. Running it as an unprivileged user was not tested for the quickstart. In one of the write-ups, ten probe runs as an unprivileged user stopped at the user-namespace uid mapping, which is why those runs used root. Plan to run as root, and read what you are running first.
bash scripts/install-hermit.sh checkThis is read-only. It exits 0 if the machine can run Hermit and 1 if it cannot, listing the reasons. On the Mac used for this guide it printed:
Hermit host check (read-only: nothing on this machine is changed)
platform FAIL Darwin arm64
result: CANNOT RUN Hermit on this machine:
- Hermit runs only on Linux; this is Darwin.
bash scripts/install-hermit.sh install --install-toolchain--install-toolchain lets the script run rustup toolchain install nightly-2026-07-12 for you. Without it, a missing toolchain is an error that prints the command. Use --dry-run first to see the plan; it verifies the pins and the build prerequisites and builds nothing.
Hermit is a third-party project that Hairspring does not control. The installer builds a pinned fork at a pinned commit, with one small patch. The pins live in one file, scripts/hermit.pin, which the installer reads; it stops with an error if the file is missing or malformed. What it uses and checks:
- the fork is
github.com/spiculedata/hermit(a fork ofrrnewton/hermit), checked out at one commit and verified after checkout; - the replay patch,
examples/glibc-condlock/experiment/patches/hermit-25781c5-replay-backport.diff, is verified by its sha256 before anything is cloned, and must apply; - the build uses the Rust toolchain
nightly-2026-07-12andcargo build --release --locked; - the built binary is checked:
hermit --versionruns,--helplists--log, andhermit run --helplists the flags the Hairspring backend passes.
It installs below ~/.local/share/hairspring/hermit by default, prints the sha256 of the binary, and records it with the pins in a hermit.provenance file beside it. A rebuild is not expected to give the same sha256 as anyone else's, so a recording made with one Hermit build is tied to that build. Bundles record the Hermit executable's hash for this reason.
export HAIRSPRING_HERMIT="$HOME/.local/share/hairspring/hermit/bin/hermit"If HAIRSPRING_HERMIT is unset, Hairspring looks for hermit on your PATH.
hairspring doctor --process-backendThis looks at the machine, not at any target. It reports whether Hermit was found (with its version and sha256), whether a hardware counter can be opened, the ptrace restriction, the kernel, and the C library and loader files. The last line is either result: ok: ... or result: CANNOT RUN the process backend on this machine: followed by one line per reason.
| Exit code | Meaning |
|---|---|
| 0 | the prerequisites are met. The last line says: a generic hardware branch counter was opened and Hermit answered --version; no program has been run under Hermit, so this does not show that Hermit works here |
| 4 | the machine cannot run the process backend; the reasons follow the CANNOT RUN line. Four is deliberately not 1, because 1 means a property was violated |
The rows it prints are platform, kernel, hermit, perf counters, ptrace, loader / libc, and a container row when it detects Docker or Podman. Each row is ok, note or FAIL. Only a FAIL stops the result being ok.
This is what it printed on the Mac used for this guide (exit code 4):
process backend: prerequisites on this machine
platform FAIL macos aarch64
kernel note release could not be read
hermit FAIL not found
perf counters FAIL not checked: no hardware counter was opened
ptrace ok no Yama restriction
loader / libc ok C library version unknown; no loader files could be read
result: CANNOT RUN the process backend on this machine:
- the process backend needs Linux: Hermit does not run on this operating system. The sim and wasm backends work here.
- Hermit was not found: HAIRSPRING_HERMIT is unset and `hermit` is not on PATH. Build it with scripts/install-hermit.sh and point HAIRSPRING_HERMIT at the result.
- no hardware performance counter was opened on this machine (the probe did not run, which happens off Linux x86-64), so the process backend cannot be said to be runnable.
What to do about each blocker is in Troubleshooting. A passing doctor --process-backend is necessary, not sufficient: the first real run is the real test.
Hermit's replay behaviour depends on the machine it runs on: its CPU, kernel and dynamic loader. If you move from one machine to another, expect to record again. See Sweeps-and-Confirmation for how Hairspring tells you when a replay is not comparable.
Your-First-Run is a guided first run that works on a Mac or on Linux.
Understand
- What-is-Hairspring
- Concepts-and-Vocabulary
- How-Deterministic-Simulation-Works
- Sweeps-and-Confirmation
- Limits-and-Honesty
Use
- Installation
- Your-First-Run
- Running-Your-Own-Software
- Guest-SDKs-by-Language
- Examples-Overview
- Hairspring-in-CI
- Operate-a-Server
- Upgrading-and-Versions
- Troubleshooting
Reference