Repository navigation
Releases
v0.1-RC2
v0.1-RC2 (pre-release)
Second release candidate of the hairspring command line, built from commit c2687b843d615e0b3cce0f211802abeb41fc8c9a.
hairspring --version on these binaries prints:
hairspring 0.1.0 (c2687b8 2026-11-05)
The crate version is still 0.1.0; the commit in brackets is what tells this build apart from v0.1-RC1, which printed
only hairspring 0.1.0. Please quote the whole line in bug reports.
Assets
| File | For |
|---|---|
hairspring-linux-x86_64 |
Linux x86-64, built on Ubuntu 22.04 (glibc) |
hairspring-macos-arm64 |
macOS on Apple silicon |
SHA256SUMS |
SHA-256 of both binaries |
Install with the script in the repository, which downloads the asset for your platform, checks its SHA-256 against
SHA256SUMS, installs it to ~/.local/bin and runs hairspring doctor:
bash scripts/install.sh --version v0.1-RC2Checking a download
Put the binary and SHA256SUMS in the same directory. You do not need to download both binaries.
# Linux
grep ' hairspring-linux-x86_64$' SHA256SUMS | sha256sum -c
# or
sha256sum -c --ignore-missing SHA256SUMS
# macOS
grep ' hairspring-macos-arm64$' SHA256SUMS | shasum -a 256 -c
# or
shasum -a 256 -c --ignore-missing SHA256SUMSEach prints <file>: OK on a match. SHA256SUMS comes from the same place as the binaries, so it catches a corrupted
or truncated download but does not prove who built the binary. To pin a hash you obtained some other way, pass it to
the installer with --sha256.
Upgrading from RC1
The first time an RC2 binary (hairspring CLI, serve, worker or mcp) opens an RC1 results database, it
migrates it from schema version 5 to version 8, in three steps that run in one transaction:
- Version 6 adds no table or column: it sets the stored mode of past sweep runs to
sweep, which RC1 recorded as
search. - Version 7 creates two indexes for the failures list. No table or column changes and no rows are rewritten. The
propertyfilter ofGET /api/failuresnow looks in the 1,000 newest runs, or in the run named byrun=. - Version 8 creates the
run_inputstable and an index onruns, and rewrites no rows. Runs now record a SHA-256
digest of each input they executed with (never the values), for built-in simulated targets only: a Hermit or WASM
run, and any run stored before this version, reads as "not recorded". Nothing serves the digests and nothing compares
runs by them yet.
On SQLite, every write to the database waits during the upgrade, up to the busy timeout, and then fails. On PostgreSQL:
- The migration must be run by the role that owns the tables (it creates indexes and a table).
CREATE INDEXtakes aSHARElock onrunsuntil the migration commits, so every insert or update of a run waits
while it runs. Building the index beforehand with
CREATE INDEX CONCURRENTLY runs_target_created ON runs(target, created_at, seq)avoids the long wait, but the
REFERENCES runsinCREATE TABLE run_inputsstill takes a brief lock onruns.- A role that only reads and writes rows needs
GRANT SELECT, INSERT, DELETE ON <schema>.run_inputs TO <role>, given
by the owner, before it can open a version 8 database. Without it the open is refused, before anything is changed,
with theGRANTto run. - A table or index of a version 7 or 8 name that was built beforehand is kept only if it has the same definition;
otherwise the open is refused and the database stays where it was.
After that, RC1 binaries refuse the database: RC1 prints
error: storage error: database schema version 8 is not supported (expected 5) and exits 2. To go back to RC1,
restore a backup.
Before the first RC2 command:
-
Stop every RC1 server, worker and MCP process that uses the database. An RC1 server left running after the
upgrade keeps storing sweeps assearch, and the migration does not run again to correct them. -
Back up the database. For SQLite (the default is
.hairspring/hairspring.db; use your--dbpath otherwise):sqlite3 .hairspring/hairspring.db ".backup '.hairspring/hairspring-rc1-backup.db'"The
.backupcommand copies a consistent snapshot, including anything still in the write-ahead log. For
PostgreSQL, take apg_dumpof the database. -
Replace the binary, then run any command against the database (for example
hairspring results) to migrate it.
There is no downgrade from version 8 to version 7, 6 or 5. An offline downgrade to version 2 exists for versions 3 to 8
(cargo run -p hairspring-store --example store_downgrade, described in docs/architecture.md). It drops the
trial-tree, coverage, digest-allowance, stored-check and run-inputs tables and the version 7 and 8 indexes, and RC1 would then migrate
the database up to version 5 again with those tables empty, so it is not a way back to the same data. Restore the
backup instead.
Other changes to check when upgrading:
hairspring confirm <run-id> --jsonnow prints a JSON array with one entry per failure. It printed a single object.
For a failure id or a bundle it still prints one object.- A valid token is now refused (
429) while requests without a valid token from the same client address are over
--rate-limit. Behind a reverse proxy, every caller shares the proxy's address unless the proxy is named with
--trusted-proxy; see SECURITY.md. - The server closes a connection that has not sent a request head within 10 seconds (also the idle time between
requests on a kept-alive connection), answers408to a body that has not arrived within 30 seconds, allows at
most 512 open connections (--max-connections) and at most 2 replays at once (--max-replays). It speaks
HTTP/1.1 only. - The run event stream no longer includes worker ids for
readtokens. - A query string that does not parse is answered with a JSON error instead of plain text.
hairspring test(a foreground command) runs only the job of the run it started; queued jobs of other runs are
left to workers.
What changed since RC1
CHANGELOG.md has the full list, including the measurements behind the performance items; the commit log is
git log v0.1-RC1..v0.1-RC2.
Added
- Web UI: an app shell with side navigation and a light/dark theme switch; an overview page with a first-run guide; a
Failures page; run page tabs (Properties, Seeds and trials, Failures, Activity), a coverage chart, a "what this run
shows / does not show" panel, the confirmation ladder and table of checks, and a readable activity log; trial page
navigation, lanes and an output viewer; links and "copy link / copy summary" on failure and trial pages; filters and
Load more on the Runs and Failures pages; start a sweep from the browser (Start run and Start sweep are disabled,
with a one-line reason, for areadtoken); a search box in the top bar; a Workers page with each worker's state,
trust, stated capabilities, held run and last-seen time, and the queue; an optional organisation name
(serve --organisation); a glossary with inline definitions; an offline banner, with polling paused while the tab is
hidden. hairspring gc --older-than 30d: a retention command that reports what it would remove and removes nothing unless
given the--applyline from its own report.hairspring test --sweep --confirmruns the confirmation pipeline on every failure row the sweep stored.serve --trusted-proxy ADDR[,ADDR...]reads the client address fromX-Forwarded-Foron connections from named
proxies only. SECURITY.md describes the limits and how to configure nginx and Caddy.serve --max-connections Nandserve --max-replays N, with request-head and body deadlines.- Token labels: an entry in
--tokens-fileorHAIRSPRING_TOKENSmay carry a label after the role
(token:run ci bot). The label names the caller in the server's log lines for creating a run, starting a replay,
registering a worker and changing a worker's trust, andGET /api/mereturns it to the holder of that token. A
label is not a secret and not proof of identity. Actions taken through MCP over HTTP are not yet logged with the
label. GET /api/me(the caller's role and what it may do),GET /api/search(bounded lookup of ids and names), paging and
filters onGET /api/runsandGET /api/failures, and worker state, held jobs and queue depth onGET /api/workers.- Run inputs: a run of a built-in simulated target records SHA-256 digests of its inputs, and a remote worker reports
them to the newPOST /api/worker/jobs/{job}/inputs. Hermit and WASM runs record none yet; nothing serves or
compares the digests yet (schema version 8). - A Hermit bundle records hashes of the target's command line and working directory; replay warns when either
differs and a miss then exits 3 (inconclusive). - A .NET guest SDK and a .NET language fixture; a Java service fixture with an idempotency race, with a
--k=N
iterations-per-worker argument. - The GitHub Action (
integrations/github-action) can be used from another repository, pinned by commit SHA. It
installs the release binary for the runner (Linux x64, macOS arm64) after checking it againstSHA256SUMS, makes one
run and one report (format:sarif,junitortext), and takessweep/seedsinputs. Behaviour on GitHub's
own runners has not been tested yet. scripts/check-embedded-ui.shchecks that a release binary serves the UI built from the same commit; the release
workflow runs it.- In the repository: CI runs the PostgreSQL tests against a PostgreSQL 16 service container, and
scripts/hermit-upstream-report.sh(with a weekly workflow) prints a read-only report of what changed in upstream
Hermit since the pinned commit.
Changed
hairspring --versionnames the build commit and its date.- Database schema versions 6, 7 and 8 (see "Upgrading from RC1"): sweep runs are stored, and listed, as sweeps, ...
v0.1-RC1
Binaries of the hairspring command line built from v0.1-RC1 (commit f819c1a).
hairspring-linux-x86_64: Linux x86-64, built on Ubuntu 22.04.hairspring-macos-arm64: macOS on Apple silicon.SHA256SUMS: check a download withsha256sum -c SHA256SUMS. The checksums come from the same
place as the binaries, so they catch a corrupted download but do not prove who built it. To pin a
hash you obtained some other way, pass it to the installer with--sha256.
scripts/install.sh --version v0.1-RC1 downloads the right asset, verifies it and installs it.
The process backend needs Linux x86-64 and a separately built Hermit; see docs/quickstart.md.