Crucible

Crucible is continuous integration for chess engines. It watches your engine's git history, builds every commit, plays it against its predecessor under the Sequential Probability Ratio Test, and shows you an Elo timeline so you can see which changes made the engine stronger or weaker.

Existing platforms such as OpenBench are designed for large teams running distributed tests across many volunteer machines. Crucible is for the solo developer who just wants to know whether the last handful of commits helped. Everything runs on one machine, from a single binary, backed by SQLite. See Why Crucible exists for the longer version.

The full documentation lives at https://sb2bg.github.io/crucible, or under docs/ in this repository.

Quick start

Choose either Docker or a local Cargo install. Docker is convenient for a long-running daemon with a bundled build environment; Cargo is usually simpler when your engine already builds on the host or depends on unusual local toolchains.

With Docker:

docker run --rm \
  -v "$PWD:/work" \
  ghcr.io/sb2bg/crucible:latest init

# edit crucible.toml, then:
docker compose up -d

The web dashboard opens at http://localhost:8877. If you bind the dashboard outside the container with web_host = "0.0.0.0", Crucible requires a real server.admin_token.

The published image includes common engine tools for Rust, Go, C/C++, Zig, .NET/C#, Java/Maven, JavaScript/npm, and Python/pip. Haskell, unusual SDK versions, host-specific dependencies, and several incompatible runtimes are often easier with a local install; Docker can still work with a custom image or mounted toolchain. See Docker and Engine runtimes.

With Cargo:

cargo install crucible-chess

This puts a crucible binary on your PATH; run crucible init, add your engine, then run crucible run. The crate is named crucible-chess because plain crucible is taken on crates.io; the binary, library, and command-line interface are unaffected.

Or build from source:

cargo build --release

./target/release/crucible init

./target/release/crucible add \
  --name my-engine \
  --repo https://github.com/you/your-engine \
  --build "make" \
  --binary-path "target/release/my-engine" \
  --branches main,dev \
  --start-from v1.0.0

./target/release/crucible run

The web dashboard opens at http://localhost:8877. Pass --tui to launch the terminal UI alongside the daemon, or run crucible monitor in another shell to attach one to a running instance.

Features

• Continuous SPRT testing of every new commit against its predecessor.
• Elo timeline with confidence intervals and highlighted tagged releases.
• Regression hunts that narrow a good-to-bad range down to the first bad commit.
• Release gates that compare a candidate and baseline against the same external gauntlet.
• NNUE-style training data exported from self-play and from the regression tests the daemon already runs.
• Multi-engine, multi-branch support, with experimental branches kept in their own lane.
• Embedded web dashboard plus an optional terminal UI.
• A single binary, SQLite storage, and no external services.

Documentation

• Why Crucible exists
• Getting started
• Docker
• Recommended workflow
• Configuration reference
• Engine runtimes
• CLI commands
• Scheduling
• Experiments
• Regression hunts
• Release gates
• Training data
• Exporting results
• Dashboards
• Architecture
• CI and releases

Contributing

See CONTRIBUTING.md for the development setup, testing expectations, and project scope. Security issues should follow the private reporting process in SECURITY.md. Notable changes are tracked in CHANGELOG.md.

License

GPL-3.0. See LICENSE.