Pre-built binaries and Docker

The Grandine team publishes ready-to-run binaries on GitHub and multi-platform Docker images on Docker Hub. Both are built by the same release workflow from the same source.

Binaries

Binaries are attached to each tagged release on the GitHub releases page. Each release has one file per platform, named grandine-VERSION-PLATFORM:

The binaries are single, self-contained executables built with the compact Cargo profile (release optimizations without debug information). They include the Mainnet, Sepolia, Holesky and Hoodi network configurations.

Builds of the develop branch are not published on GitHub. To run the newest unstable code, use the unstable Docker image or build from source.

Install a binary on Linux

1. Download the binary for your platform from the releases page. Replace VERSION with the release you want, for example 3.0.0:

   VERSION=3.0.0
   curl -LO "https://github.com/grandinetech/grandine/releases/download/${VERSION}/grandine-${VERSION}-linux-x64"
   

2. Make it executable and move it onto your PATH:

   chmod +x "grandine-${VERSION}-linux-x64"
   sudo mv "grandine-${VERSION}-linux-x64" /usr/local/bin/grandine
   

3. Check that it runs:

   grandine --version
   

Grandine builds OpenSSL into the binary, but it uses the system's CA certificates to verify HTTPS connections, for example to a checkpoint sync server. On a minimal Debian or Ubuntu system, install them first:

sudo apt-get install ca-certificates

Verify a download

Releases do not include checksum or signature files, and the binaries are not code-signed. To check a binary, compare its version with the release you meant to download, and download only from the official GitHub repository. If you need full assurance, build from source at the release tag and compare the behavior and version of the result.

macOS and Windows

The macOS binaries are not notarized, so macOS may refuse to open them. Remove the quarantine attribute after downloading:

xattr -d com.apple.quarantine grandine-VERSION-osx-arm64
chmod +x grandine-VERSION-osx-arm64

On Windows, run grandine-VERSION-win-x64.exe from PowerShell or a command prompt. Most examples in this book use Linux paths; adjust them for your system.

Docker

Images are published to Docker Hub as sifrai/grandine. They support linux/amd64 and linux/arm64. The image is based on Ubuntu 24.04, contains the binary at /usr/local/bin/grandine and uses it as its entry point, so the arguments after the image name are passed to grandine.

Tags

Grandine images:

Grandine embedded in Nethermind (see Grandine embedded in Nethermind):

Tip: On Mainnet, use the stable tag. It follows stable releases only, so pre-releases and develop builds never reach it. To control exactly when you update, pin a version tag such as sifrai/grandine:VERSION instead. See Updating Grandine.

Pull and run

docker pull sifrai/grandine:stable
docker run --rm sifrai/grandine:stable --version

The container runs as root, so Grandine's default data directory inside it is /root/.grandine. Mount a host directory there to keep the database across container restarts, and mount the JWT secret:

docker run -d --name grandine \
  --restart unless-stopped \
  -p 9000:9000/tcp -p 9000:9000/udp -p 9001:9001/udp \
  -v $HOME/.grandine:/root/.grandine \
  -v /path/to/jwt.hex:/jwt.hex:ro \
  sifrai/grandine:stable \
  --network hoodi \
  --eth1-rpc-urls http://EL-HOST:8551 \
  --jwt-secret /jwt.hex \
  --checkpoint-sync-url CHECKPOINT-URL \
  --http-address 0.0.0.0

Inside a container, the Beacon Node API must listen on 0.0.0.0 (--http-address 0.0.0.0) to be reachable from outside the container. Publish port 5052 (-p 127.0.0.1:5052:5052) only if you need the API on the host, and do not expose it to the internet.

For a complete setup with an execution client, see the Docker Compose example in Running as a service, or use Eth Docker.

Volumes and paths

NETWORK is the network name, such as mainnet or hoodi. See Default ports and paths.

Grandine bundled with Nethermind

Releases also include archives named grandine-VERSION-nethermind-NETHERMIND_VERSION-PLATFORM.zip, and Docker Hub has matching -nethermind tags (VERSION-nethermind-NETHERMIND_VERSION). These contain a Nethermind release with Grandine embedded as a plugin, so one process runs both the execution and the consensus layer, and Grandine calls Nethermind's Engine API directly. See Grandine embedded in Nethermind.

Command line options

• --version: print the version and exit.
• --help: print all options and exit.
• --data-dir: default $HOME/.grandine. Parent directory for data; the network name is appended.
• --http-address: default 127.0.0.1. Address the Beacon Node API listens on.
• --http-port: default 5052. Port of the Beacon Node API.

See the Command line reference for the full list.