# Nimbus Eth2 is a consensus client designed for small machines

> Nimbus-eth2 is the Nim implementation of the Ethereum Beacon Chain, optimised for embedded and resource restricted devices including Raspberry Pi, and used on servers when low resource use matters. The repository also ships a block simulator and a local network simulation that let you exercise consensus code without a network.

**status-im/nimbus-eth2** — Nim implementation of the Ethereum Beacon Chain

- Repository: https://github.com/status-im/nimbus-eth2
- Website: https://nimbus.guide
- Stars: 666 · Forks: 349
- Language: Nim
- License: NOASSERTION
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/status-im-nimbus-eth2

## A consensus client whose target is the Raspberry Pi

Nimbus-eth2 is described as an extremely efficient consensus layer, eth2, client implementation, and the README is direct about what that efficiency is for. It is optimised for embedded systems and resource restricted devices, including Raspberry Pis, and the same low resource usage makes it a reasonable choice for any server or desktop, where the argument simply becomes that it takes up fewer resources.

That is an unusual positioning for a blockchain client, where the default expectation is a large machine and a lot of memory. The implementation language is Nim, the repository is status-im/nimbus-eth2, and it is the consensus layer only, with the execution client living in a separate project, status-im/nimbus-eth1, and the rules it implements are the ethereum/consensus-specs stable specifications.

The project is not a research prototype. The release history shows v26.10.1 published on 2026-10-16 and v26.10.0 on 2026-10-04, plus a nightly build from the unstable branch on 2026-10-20, and the last push was on 2026-10-20. The default branch is named stable, which is a deliberate choice with consequences, as the branch guide explains.

The licence is dual. The README carries badges for both Apache 2.0 and MIT, and the repository has a LICENSE-APACHEv2 file and a LICENSE-MIT file, and the Dockerfile header says the software is licensed under either of the two, at your option. That is a permissive, no-fee grant, and it is worth noticing that the project record lists the licence as one GitHub could not classify, so the two files in the repository are the authority.

## Three branches, and the difference matters

The branch guide in the README is short and it is the most operationally important section for anyone running a node.

The stable branch is the latest stable release and the README marks it as recommended for most users. The testing branch is a pre-release branch with features and bugfixes slated for the next stable release, and it is described as suitable for use on testnets and for adventurous users who want to live on the edge. The unstable branch is the main development branch against which pull requests are merged, and the README says that if you want to contribute to Nimbus, you should start there.

Three branches with three audiences is a reasonable convention for a project that has to support both operators and contributors, but it means a node operator has an actual decision to make rather than a single default. The recent release list shows the project publishes tagged versions from the stable line, and separately a nightly build from the unstable branch, so the two tracks are visible in the release feed.

The README also points at a migration guide for people coming from another client, and a separate page for advanced migration options. That is a sign of a project that expects operators to switch between clients, which is a reasonable expectation in a network where client diversity is a design goal.

For documentation, the project points at the Book at nimbus.guide, and specifically at the Quickstart page for connecting to either mainnet or the Hoodi testnet.

## The block simulator runs the state transition with no network at all

The researchers section is where this repository is more interesting than a client binary, and the block simulator is the clearest example.

The README says the block simulator can quickly run the Beacon chain state transition function in isolation, without networking and without slot time delays. Those two omissions are the point. The state transition is the part of consensus that turns a block into a new state, and it is the part you want to exercise when you are testing a change, measuring a scenario, or looking for a bug. Removing the network removes the nondeterminism of peers, and removing slot time means a run of a thousand slots finishes in a fraction of the real time.

The build and run commands are given, with a note that the release flag speeds it up substantially and allows longer runs in reasonable time:

```bash
# build and run the block simulator, then display its help ("-d:release" speeds it
# up substantially, allowing the simulation of longer runs in reasonable time)
make NIMFLAGS="-d:release" block_sim
build/block_sim --help
```

The repository root gives a hint of how much machinery sits behind this. There are benchmarks/ and research/ directories, an nfuzz/ directory for fuzzing, a grafana/ directory, a kurtosis-network-params.yml for running networks as infrastructure as code, a wasm/ directory, and a Makefile that carries per-run variables such as VALIDATORS, NODE_ID, BASE_PORT, BASE_REST_PORT and BASE_METRICS_PORT, with a separate RUNTIME_LOG_LEVEL and a LOG_LEVEL default of DEBUG.

The Makefile is also where the constants for local networks live. SEPOLIA_WEB3_URL points at the execution layer endpoints for Sepolia, and GNOSIS_WEB3_URLS points at a Gnosis Chain endpoint, both passed to the node as command line arguments.

## A local network of beacon nodes and validators on one machine

The second simulation is heavier and closer to a real network.

The local network simulation creates a full peer to peer network of beacon nodes and validators on a single machine, and runs the beacon chain in real time. Parameters such as shard count, validator counts and data folders are set as environment variables before launching it. The documented invocation is:

```bash
# Clear data files from your last run and start the simulation with a new genesis block:
make VALIDATORS=192 NUM_NODES=6 USER_NODES=1 local-testnet-minimal
```

The variables map onto the Makefile defaults directly, where VALIDATORS is set to 1 and NODE_ID to 0 by default.

The USER_NODES variable deserves attention because it is a testing technique rather than a knob. The README explains that the network is prepared for seven beacon nodes but one of them is not started by default, using USER_NODES, and that this is useful to test catching up to the consensus. The command that starts the missing node is given as:

```bash
./tests/simulation/run_node.sh 0 # (or the index (0-based) of the missing node)
```

and a separate node also lets you test sync and see the action from a single node's perspective.

A third detail changes the process model. By default, validators are split in half between beacon node and validator client processes, fifty fifty, communicating through the common validator API, so 192 validators across 6 nodes roughly means 6 beacon node and 6 validator client processes with 16 validators each. If you would rather have all the validators handled by the beacon nodes, you can pass USE_VC=0 as an additional argument to make local-testnet-minimal. That is a genuinely useful switch, because the split and the merged configurations behave differently under a client change, and the simulation lets you run both on one laptop.

## ncli, ncli_db and the shared testing API

The tooling that ships with the client is aimed at people who need to look inside the data rather than just run it.

ncli is a command line tool with pretty printers, SSZ decoders and state transition helpers, so you can interact with Eth2 data structures and functions without writing a full client. ncli_db performs surgery on the Nimbus sqlite database, which is the sort of tool that saves hours when you are debugging a stuck node. There is also multinet, a set of scripts to build and run several Eth2 clients locally, which is the harness for testing client interoperability rather than just your own client.

The Makefile lists the tools that are built unconditionally by the default target, and the list gives a good picture of the project's internal surface: resttest, ncli, ncli_db, ncli_split_keystore, fakeee, wss_sim and a custom compiled library, libnimbus_lc.a.

For anyone integrating against the client, the README lists five public REST API instances for testing, split across mainnet, Hoodi and Sepolia and marked testing or unstable. It also warns, in bold, that these are very much unstable testing instances, that they may be unresponsive at times, and that you should not rely on them for validating. They may be disabled at any time.

That warning matters more than it first appears. A test suite that quietly depends on a shared endpoint is one that will fail on a day when the endpoint is down and nobody will know whether the client broke or the infrastructure did.

## The container build and the shape of the deployment

The Dockerfile in the repository shows how the client is packaged, and it is a good illustration of a project that cares about image size.

The build stage is debian:testing-slim with build-essential and git-lfs installed, the source is added, and the node is compiled with make -j$(nproc) update followed by a build that passes the const_preset=mainnet and disableMarchNative defines, and a log level of TRACE. A second stage then starts from a clean debian:testing-slim and copies only the built binary across, which is the comment's stated reason for splitting the stages, to reduce size.

The runtime image sets the PATH to the directory holding the binary, sets the entrypoint to nimbus_beacon_node, and sets the stop signal to SIGINT, which matters for a client that needs to shut down cleanly and persist its state.

At the repository root, beyond the client itself, there is a Dockerfile, an installer/ directory, a docker/ directory, a nix/ directory alongside flake.nix and flake.lock for a Nix based environment, an .oss-scanner/ directory for open source scanning, an .envrc for direnv, and separate scripts for running mainnet and Sepolia beacon nodes. There is also a CHANGELOG.md and per-network specification preset documents such as ConsensusSpecPreset-mainnet.md and ConsensusSpecPreset-minimal.md, which is the documentation you would read to know what the client expects from a given network configuration.

## Conclusion

Adopt Nimbus-eth2 if you run beacon nodes and validators on constrained hardware, you want a client written in Nim, or you need the simulation tooling the project provides for research. Do not adopt it if you need a client with a large third party integration surface, and do not point validation tooling at the shared testing REST API instances, because the README says they are unstable and may be disabled at any time. Before you deploy, read the branch guide and pick stable rather than testing or unstable, read the migration guide if you are moving from another client, and confirm your hardware is within the resource envelope the project describes.

## FAQ

### What is Nimbus Eth2 and what is it written in?

It is the Nim implementation of the Ethereum Beacon Chain consensus layer, described as extremely efficient and optimised for embedded and resource restricted devices including Raspberry Pi. The repository is status-im/nimbus-eth2 and the execution client lives in the separate nimbus-eth1 project.

### Which branch of nimbus-eth2 should I run?

The stable branch, which the README recommends for most users. The testing branch is a pre-release branch suitable for testnets, and the unstable branch is the main development branch that pull requests are merged against and that contributors should start from.

### How do I run the Nimbus block simulator?

Build it with `make NIMFLAGS="-d:release" block_sim` and then run `build/block_sim --help`. The simulator runs the Beacon chain state transition in isolation, without networking and without slot time delays, and the release flag makes longer runs practical.

### Can I test a local beacon chain network on one machine with nimbus-eth2?

Yes. The local network simulation creates a peer to peer network of beacon nodes and validators on a single machine and runs the chain in real time, with parameters such as validator and node counts set as environment variables, for example `make VALIDATORS=192 NUM_NODES=6 USER_NODES=1 local-testnet-minimal`.

## Sources

- [Issues](https://github.com/status-im/nimbus-eth2/issues)
- [Project website](https://nimbus.guide)
- [README](https://github.com/status-im/nimbus-eth2/blob/stable/README.md)
- [Releases](https://github.com/status-im/nimbus-eth2/releases)
- [status-im/nimbus-eth2 on GitHub](https://github.com/status-im/nimbus-eth2)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/status-im-nimbus-eth2