Getting started

Install it, wrap one command, and read what it tells you. Five minutes, most of them spent waiting on the first run.

A peregrine on a limestone ledge, watching the valley below.

Install

Install the prebuilt binary without Rust:

$ curl -fsSL https://stoop.build/install.sh | sh

By default the installer uses ~/.local/bin. Set STOOP_INSTALL_DIR to another user-owned directory or STOOP_VERSION=v0.1.0 to pin a release. It also supports --help, --dry-run and --uninstall when saved and run locally. STOOP_RELEASE_BASE is for local loopback testing only.

The installer checks the archive against the release's SHA-256 checksum, which detects corruption or a tampered mirror. An attacker who controls the release can change both the archive and checksum. If gh is installed, the installer also verifies GitHub build provenance and fails on verification errors; otherwise it says the check was skipped. Attestation verifies the artifact's claimed build provenance, not that the source or build is safe. Piping the installer into a shell trusts stoop.build and TLS to deliver the script.

To build it yourself instead, from a clone:

$ git clone https://github.com/jwaldrip/stoop && cd stoop
$ cargo build --release      # binary at target/release/stoop

Tracing needs Linux on x86-64 or arm64. On macOS stoop builds and runs the wrapped command untraced, so it never skips and never records. That keeps a workflow portable; the savings happen on Linux runners.

Wrap a command

Put stoop run -- in front of anything you'd run in CI. The first time, there is no proof, so it runs and records:

$ stoop run -- cargo build
stoop: run cargo-46fcb2881638d3cc: no proof yet
stoop: recorded 668 inputs for cargo-46fcb2881638d3cc

Run it again with nothing changed and it skips:

$ stoop run -- cargo build
stoop: skip cargo-46fcb2881638d3cc: 668 inputs unchanged since 1s ago (289ms)

run is the default, so stoop -- cargo build does the same. The exit code is the command's own, and 0 on a skip.

Proofs live in .stoop/ at the repository root. Add it to .gitignore; it is a cache, not source.

Ask before it runs

stoop explain says what would happen without running anything. It exits 0 when the command would be skipped and 1 when it would run, so scripts can branch on it.

$ echo '// tweak' >> src/ignore.rs
$ stoop explain -- cargo build
proof 1 (1s ago):
  changed: src/ignore.rs
stoop: would run cargo-46fcb2881638d3cc: src/ignore.rs changed

Every line above is real output, captured from a fresh clone of stoop building itself on Linux.

Look at what it kept

$ stoop ls
cargo-46fcb2881638d3cc	3 proofs	560 inputs	created 1794951294
$ stoop forget cargo-46fcb2881638d3cc

Each key keeps up to 8 proofs. forget drops all of them for that key.

When it refuses to record

stoop would rather run a command again than skip one it can't vouch for. When a run can't be trusted it says so, runs normally, and writes nothing:

$ stoop run -- sh -c "curl -sI https://example.com | head -1"
stoop: run sh-5347c74b88ffd993: no proof yet
HTTP/2 200
stoop: not recorded: it used the network (connect to 192.168.64.1:53), whose results a file trace cannot see; cover it with --probe, or pass --allow-network to record it anyway

That address is the container's DNS resolver: the first thing curl talked to. Blind spots covers what to do about it.

Then put it in CI

That is where it pays. In GitHub Actions, one defaults block wraps every run: step:

defaults:
  run:
    shell: stoop sh {0}

CI recipes has the full workflow, plus GitLab CI, CircleCI and Buildkite.