nimbus-eth1: an Ethereum execution client written to run on a Raspberry Pi

The client is one half of a pair, with the consensus side elsewhere

nimbus-eth1 is an execution-layer client, and the README is careful about what that means in this repository. It contains development work on an execution-layer client to pair with the Status consensus-layer client, and the client focuses on efficiency and security while striving to be as light-weight as possible in terms of resources used. The word light-weight here is the project's defining constraint rather than a marketing adjective, and it is visible in the target list: the repository topics include android, ios, mobile and raspberry-pi, and the primary language is Nim. All consensus-layer client development is happening in parallel in the separate nimbus-eth2 repository, so this repository is deliberately scoped. Two other projects also live here. The Nimbus Portal client is a Portal Network light client, and the Nimbus Verified Proxy has its own directory and README. The consequence for an adopter is that you are adopting the execution layer, and the consensus layer is a separate codebase you will need as well. For development progress, the README points to the Nimbus blog rather than trying to summarise it in the repository.

Building on POSIX means make, submodules and a vendored build system

The prerequisites are modest: GNU Make, Bash and the usual POSIX utilities, with Git 2.9.4 or newer. The build sequence is documented as one block, and the comments inside it explain the parts that trip people up:

# The first `make` invocation will update all Git submodules.
# You'll run `make update` after each `git pull`, in the future, to keep those submodules up to date.
# Assuming you have 4 CPU cores available, you can ask Make to run 4 parallel jobs, with "-j4".

make -j4 nimbus_execution_client

# See available command line options
build/nimbus_execution_client --help

# Start syncing with mainnet
build/nimbus_execution_client

# Update to latest version
git pull && make update
# Build the newly downloaded version
make -j4 nimbus_execution_client

# Run tests
make test

The submodule step is the part to internalise. The first make invocation updates all Git submodules, and you run make update after each git pull in future, so the vendored dependencies stay in step with the source. The build system itself is vendored: the Makefile sets BUILD_SYSTEM_DIR to vendor/nimbus-build-system and includes its makefiles/variables.mk from there, and the README says the interesting Make variables and targets are documented in the separate nimbus-build-system repository. That design keeps the build reproducible from a single clone, but it also means the Makefile you are reading is a thin wrapper and the real documentation lives elsewhere.

Nim comes from a Status fork, and env.sh wires it into your shell

The build depends on a fork of the Nim compiler, and the repository gives you a script to make sure you invoke the right one. To run a command that might use binaries from the Status Nim fork, the README says to use env.sh:

./env.sh bash # start a new interactive shell with the right env vars set
which nim
nim --version

# or without starting a new interactive shell:
./env.sh which nim
./env.sh nim --version

The two forms matter. Running ./env.sh bash gives you an interactive shell with the environment variables already set, so everything you type afterwards uses the fork. Running ./env.sh with a single command wraps just that command, which is the form you want in a script or a CI step where you do not want to change your whole session. The repository root carries the env.sh script, a .envrc file for direnv users, a flake.nix and flake.lock, and a nix/ directory. The Nim side of the project is organised through nimbus.nims, nimbus.nimble and config.nims, with the source packages under execution_api/, execution_chain/, nrpc/ and tools/. The Makefile also defines a set of TOOLS targets, among them nrpc, nimbus_history_exporter and test_tools_build, which are separate binaries from the client itself.

A Raspberry Pi build is documented, with a 64GB card as the baseline

The Raspberry Pi path is labelled experimental, and the hardware requirements are stated before anything else. You need a Raspberry Pi 4 or later, and the README is blunt about storage: 64GB SD Card, with a note that less might work too but the default recommended 4-8GB will probably be too small. The operating system is Rasbian Buster Lite, with the Lite version enough to get going and saving disk space. The setup steps are concrete. You increase the swap size to 2gb by editing the swapfile with vi, setting CONF_SWAPSIZE=2048, then reboot. Then you install the prerequisites and clone:

# Install prerequisites
sudo apt-get install git libgflags-dev libsnappy-dev

mkdir status
cd status

# Raspberry pi doesn't include /usr/local/lib in library search path - need to add
export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH

git clone https://github.com/status-im/nimbus-eth1.git

cd nimbus-eth1

# Follow instructions above!

The swap increase is the interesting requirement. A full execution client sync is disk and memory intensive, and the swap file is what stops a 4GB device from running out of memory during the sync. The library path export exists because the Raspberry Pi does not include /usr/local/lib in its search path, which matters for a project that installs native dependencies into that prefix.

Android builds run inside a Termux PRoot with an Ubuntu image

The Android instructions are also marked experimental, and they describe a different model of running a Linux binary on a phone. You install the Termux app from F-Droid or the Google Play store, then install a PRoot of your choice following the instructions for your preferred distribution. The README notes that the Ubuntu PRoot is known to contain all Nimbus prerequisites compiled on the Arm64 architecture, which is the common architecture for Android devices, and adds that depending on the distribution it may require effort beyond the scope of the guide to get all prerequisites in place. Assuming Ubuntu PRoot is used, the sequence is short:

# Install prerequisites
apt install git make gcc

# Clone repo and build Nimbus just like above
git clone https://github.com/status-im/nimbus-eth1.git

cd nimbus-eth1

make update

make nimbus_execution_client

build/nimbus_execution_client

The PRoot approach means the phone runs a full Linux userland through proot rather than a native ARM build of the client. That buys you the same toolchain as the server build at the cost of performance overhead from the emulation layer. The same approach appears on the Raspberry Pi guide, which is why both are described as experimental rather than as supported platforms.

The Dockerfile splits build and deploy so the runtime image stays small

The repository ships a Dockerfile and a Dockerfile.debug, and the structure of the main one is worth reading because it explains the project's size goals. It uses a multi-stage build with debian:trixie-slim as the base for both stages. The build stage installs curl, build-essential and git-lfs, copies the source into /root/nimbus-eth1, and runs make init followed by a build with DISABLE_MARCH_NATIVE=1 and V=1. The DISABLE_MARCH_NATIVE flag is the interesting one: it prevents the compiler from targeting the build machine's native CPU instructions, which is what lets one image run on hardware other than the builder. The second stage is a fresh debian:trixie-slim that installs build-essential and copies in only the compiled binary from the build stage. The deploy stage then sets PATH to include /home/user/nimbus-eth1/build, sets the working directory to the same place, and declares the entrypoint as nimbus with STOPSIGNAL SIGINT so that a container stop sends an interrupt the client can handle cleanly.

Experimental make variables change the garbage collector and the logger

Beyond the standard Make flags, a small set of variables control the build in ways that matter when something goes wrong. The README lists them with decreasing priority, meaning that if in doubt the lower-priority variable is ignored when a higher-priority one is available. Setting BOEHM_GC=1 changes the garbage collector to boehm, and the stated reason is that it might help debugging in certain cases when the gc is involved in a memory corruption or corruption camouflage. That is an unusual and specific reason to switch collectors, and it tells you the project has seen memory corruption problems worth chasing. Setting ENABLE_LINE_NUMBERS=1 enables the logger to print out the source code location with the log message. For these variables, using the value 0 is ignored and the value 2 has the same effect as 1, ditto for other numbers. The Windows instructions have a similar shape, requiring a link from make to mingw32-make, which the README spells out because the tool ships under a different name. The README also links to documentation for the V variable that controls the Makefile's verbosity, with the rest of the build system documentation living in the nimbus-build-system repository.

Editorial conclusion

nimbus-eth1 suits operators who need an Ethereum execution client on constrained hardware, who already run a Status consensus client, or who want to read a production blockchain client written in Nim rather than Go or Rust. It is the wrong choice if you want a mainstream execution client with the largest ecosystem of tooling and operator experience, and it is the wrong choice if your machine cannot spare the memory a full sync needs. Verify first that your hardware matches the stated Raspberry Pi 4 and 64GB SD card baseline, that you understand the vendored build system and the make update step after every git pull, and that the experimental Android and Windows paths are acceptable for your setup.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. status-im/nimbus-eth1 on GitHub