Fetch, verify, and exec the exact artifact a descriptor pins. A .binrun descriptor is a small executable file that names one release — version, per-platform sha256s, provider — and binrun materializes it into a content-addressed cache and process-replaces into it, so a tool can never drift from the version its plugin shipped against.

brew install yasyf/tap/binrun
curl -fsSO https://raw.githubusercontent.com/yasyf/binrun/main/docs/examples/cc-review.binrun
binrun cc-review.binrun --version

go install github.com/yasyf/binrun/cmd/binrun@latest

$ binrun cc-review.binrun --version
v0.25.0

The first run downloads the pinned release asset, verifies its sha256 and size, and unpacks it into the cache; every run after that execs straight from disk. The --version went to cc-review, not to binrun. After the descriptor argument, binrun interprets nothing.

Driving with an agent? Paste this:

Install binrun (`brew install yasyf/tap/binrun`), write a `.binrun` descriptor
pinning my project's current release (version, per-platform asset names,
sha256s, sizes), and change the plugin's bin/ wrapper to
`exec binrun <descriptor> "$@"`.

A plugin wrapper that installs "the latest release" breaks the moment the registry moves ahead of everything else on the machine, and the tool and its host then disagree on versions until a human intervenes. Pin the release in a descriptor committed next to the wrapper instead:

#!/bin/sh
exec binrun "$(dirname "$0")/../descriptor/cc-review.binrun" "$@"

The wrapper always runs the version the plugin was released with. Upgrades happen by shipping a new descriptor, not by whatever releases/latest says at invocation time.

fetch materializes without executing, and resolve prints where the artifact landed — both are for wiring into session-start hooks and build scripts:

$ binrun -- fetch cc-review.binrun
$ binrun -- resolve cc-review.binrun
/Users/USER/.daemonkit/cache/94/941e2a99a0044153bcd49fcf1174e51a91e792b7312119363f41ccfc2304e78e/cc-review

The cache is content-addressed by the verified digest, so a corrupted or truncated download can never occupy the final path, and a second fetch of the same digest is a no-op that works offline.

binrun's own release workflow renders its descriptor from goreleaser's output — scripts/render-descriptor.sh fills the version, asset names, sizes, and sha256s from dist/ plus checksums.txt, validates it with binrun -- parse, and uploads it as a release asset. Copy that job into any repo that releases binaries and its consumers get a descriptor per release for free.

binrun -- gc --keep 2

keeps the newest two cached versions of each artifact and removes the rest. Damaged cache entries (missing metadata) are always reclaimed.

A descriptor is #!/usr/bin/env binrun followed by JSON — executable, diffable, and pinned. The committed example at docs/examples/cc-review.binrun is real and runnable:

{
  "schema": 1,
  "name": "cc-review",
  "kind": "release-binary",
  "version": {"static": "0.25.0"},
  "platforms": {
    "macos-aarch64": {
      "size": 11096686,
      "hash": "sha256",
      "digest": "941e2a99a0044153bcd49fcf1174e51a91e792b7312119363f41ccfc2304e78e",
      "format": "tar.gz",
      "path": "cc-review",
      "providers": [
        {"type": "github-release", "repo": "yasyf/cc-review", "tag": "v0.25.0", "name": "cc-review_0.25.0_darwin_arm64.tar.gz"}
      ]
    }
  }
}

A version.command descriptor asks a locally installed binary what version to run — the pattern for a Python tool that must match a signed host app build-for-build. Dynamic versions are only valid for python-tool and signed-app, where an independent integrity gate (registry hashes, code signing) backs the artifact; a dynamic release-binary has no such gate and fails validation.

binrun FILE [args…] resolves the descriptor and execs the artifact with args — process replacement, so the artifact's exit code, signals, and streams are binrun's. Management verbs live behind --:

Exit codes: 0 on success; every binrun-domain failure exits 1 with a one-line message. When the artifact runs, its own exit code passes through untouched. binrun never exits 2 — in the ecosystem it serves, 2 is a hook's blocking verdict and belongs to the artifact alone.

Status: pre-1.0. Descriptor schema 1 is stable; a schema bump makes an old runner fail loudly rather than guess.

Licensed under PolyForm-Noncommercial-1.0.0.