Install

Get Nuthatch running.

Embedded mode is a single binary with no external services. Pick whichever route you trust. Every one lands you at the same place: nuthatch init, then nuthatch dev.

v5.3.0 Nuthatch 5.3.0 proves which blocks a validator proposed (RFC-0063 plan C), whoever received their fees, so rotki can book a validator's produced blocks and MEV from a nest alone. All releases

Shell script

Detects your platform, downloads the matching binary from the latest GitHub release, verifies its SHA-256 checksum, and installs it to ~/.local/bin (override with NUTHATCH_INSTALL_DIR). Covers macOS Apple Silicon and Linux x86_64, and Linux arm64 (aarch64-unknown-linux-gnu) from 4.12.0; on any other target it stops and prints the cargo command instead of installing something that will not run, as it does on Linux arm64 while the latest release has no binary for it. No Intel Mac binary is published: on an Intel Mac, build from source with Rust 1.95.0 (below). Both Linux binaries are dynamically linked and need glibc 2.35 or newer and no C++ runtime: Debian 12 and Ubuntu 22.04 qualify. RHEL 9 and Amazon Linux 2023 ship glibc 2.34 and ran 4.0.x; from 4.1.0 they need the source build.

Piping to a shell asks for trust. Read it first: the script is short and on GitHub, or download it, read it, then run it.

Cargo

Build from source straight from the repo, with Rust 1.95.0. This is the only route on a platform without a published binary, Intel Macs included (the Intel build has not been verified on Intel hardware). The toolchain pin is required, not advisory: rust-toolchain.toml does not apply to cargo install --git, and rustc 1.97 hits a dbsp ICE that installs nothing. No prebuilt binary in the trust path.

Or grab a tarball and its .sha256 yourself from the latest GitHub release: nuthatch-aarch64-apple-darwin.tar.gz, nuthatch-x86_64-unknown-linux-gnu.tar.gz, nuthatch-aarch64-unknown-linux-gnu.tar.gz (from 4.12.0), or nuthatch-scaled-x86_64-unknown-linux-gnu.tar.gz for scaled mode.

The graph build

The default binary has no GraphQL route: POST /graphql answers 404. From 4.11.0 every release also carries nuthatch-graph-<target>.tar.gz, built with --features graph and attested like the others, which serves a nest's Graph-dialect GraphQL at /graphql and /subgraphs/id/<deployment>. It is published for aarch64-apple-darwin and x86_64-unknown-linux-gnu, and for aarch64-unknown-linux-gnu from 4.12.0. The installer does not fetch it; download it and its .sha256 from the release. The tarball holds one binary, also named nuthatch, with every command the default one has.

GraphQL here is a partial read surface: exact for a subgraph's event-shaped fields, and a refusal by name for anything else, so it is not a drop-in replacement for a subgraph. A nest needs a graph/schema.graphql (written by nuthatch port-emit) before it answers; without one the route says so. Subgraph fallback has the boundary.

Homebrew planned

macOS and Linuxbrew, once a tap is published.

Docker

Embedded mode needs no Docker at all - that is rather the point. Images are published for anyone who wants one, and for scaled mode, where Postgres replaces the embedded hot store across a fleet.

The image runs dev on the nest mounted at /nest, bound to 0.0.0.0:8288 inside the container, so publish it to loopback as above. :5.3.0 and :latest are the embedded build; pin the version for anything you care about. :5.3.0-scaled carries the Postgres driver and the worker, control and serve --hot-store commands. linux/amd64 only, and no image carries the graph build: on an arm64 Linux host, or to serve GraphQL, use a binary. The compose files live in the repo.

First run

Point it at a contract and go. Public RPC defaults; no key required. Those endpoints are for trying it out, not for keeping it running: for that, point --rpc at your own node or a provider, which may charge for it.

init resolves each contract's ABI (proxies included), scaffolds a nest, and writes a schema.json, an llms.txt, and a Claude Code skill. Pass several addresses to index a multi-contract nest. Omit --chain and init probes all nine built-in chains for the contract's bytecode. --backfill 300 starts 300 blocks behind the tip, so there are rows within seconds; without it dev backfills from the contract's deployment block, which for a contract with a long history wants your own archive-capable RPC. dev follows the tip and serves /tables, /table/{name}, read-only /sql, balances and /metrics on one local endpoint, which nuthatch mcp bridges to an agent.

---

Verify what you downloaded

Every release binary ships with a SHA-256 checksum file. The shell script checks the sum for you; do it yourself for the manual download.

Source, docs, and issues on GitHub →