Skip to content

Installation

Tom Barber edited this page Nov 6, 2026 · 7 revisions

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.

What works where

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.

Option 1: a release binary

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 -c

You 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 --version

Expected 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.

Option 2: the installer script

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-RC2

Use 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.

Option 3: build from source

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 --version

hairspring --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.

Check the install

hairspring targets
hairspring doctor

hairspring 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.

Upgrading to schema version 7

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.

  1. Back up first, and stop every older server and worker that uses the database. See Upgrading-and-Versions.

  2. On SQLite there is nothing else to do. The upgrade holds the write lock for its duration, so writers wait.

  3. 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 to failures and run_properties wait 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.

  4. 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.

Upgrading to schema version 8

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.

  1. Back up first, and stop every older server and worker that uses the database. See Upgrading-and-Versions.

  2. 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.

  3. 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 to runs wait while the index builds.

  4. 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.

  5. 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.

The process backend: Hermit on Linux x86-64

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.

What the machine needs

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.

Step 1: ask whether this machine can run Hermit at all

bash scripts/install-hermit.sh check

This 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.

Step 2: build the pinned Hermit

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 of rrnewton/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-12 and cargo build --release --locked;
  • the built binary is checked: hermit --version runs, --help lists --log, and hermit run --help lists 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.

Step 3: tell Hairspring where Hermit is

export HAIRSPRING_HERMIT="$HOME/.local/share/hairspring/hermit/bin/hermit"

If HAIRSPRING_HERMIT is unset, Hairspring looks for hermit on your PATH.

Step 4: hairspring doctor --process-backend

hairspring doctor --process-backend

This 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.

A note on moving machines

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.

Next

Your-First-Run is a guided first run that works on a Mac or on Linux.

Clone this wiki locally