filecoin-project/lotus: running a Filecoin node in Go

What Lotus is, and who actually needs it

Lotus is described in its README as an implementation of the Filecoin Distributed Storage Network, written in Go, with the protocol itself specified separately at spec.filecoin.io. That distinction matters: Lotus is one implementation of a network other people specify, not the definition of the network. The repository is organised around that role. The top level carries chain/, miner/, node/, storage/, gateway/, cli/, api/ and itests/, which maps onto the three binaries the build produces: lotus, lotus-miner and lotus-worker.

The audience is narrow and technical. If you want to hold FIL or move it around, you do not need this repository. You need Lotus when you want to run a full node that validates and stores chain data, when you are operating storage capacity on the network, or when you are building against the node API. The README frames the build around joining mainnet, joining a testnet such as Calibration, or running a devnet, which is the mental model the project expects you to have before you start.

How the pieces fit: daemon, miner, worker, gateway

The architecture visible in the repository is a set of long-running processes that share a data directory and talk over an API. The lotus daemon is the full node: it syncs the chain, holds wallets and chain state, and by default stores everything under $HOME/.lotus. lotus-miner is the storage provider process, with its own repository. lotus-worker is the piece that carries out sealing work, and the README describes building and installing all three together so that they land in /usr/local/bin.

The dependency graph explains a lot of the build pain. The Makefile builds an FFI layer from extern/filecoin-ffi before the Go binaries, and the Dockerfile installs a pinned Rust toolchain (RUST_VERSION=1.86.0) alongside Go, because the proof code is not pure Go. The Dockerfile also shows the intended container topology: a lotus service exposing port 1234, and a lotus-gateway service that depends on it and maps 1235 on the host to 1234 in the container, with FULLNODE_API_INFO pointing at the internal service name. The gateway is a read-oriented proxy in front of a full node, which is the pattern you use when you do not want every client to talk to the daemon directly.

Installing Lotus and syncing for the first time

The README gives distribution-specific dependency lists. On Ubuntu or Debian the one-liner installs the OpenCL, build and hwloc packages the proofs need. Run this first, because the Go build will fail without the OpenCL and hwloc headers.

Installing Lotus and syncing for the first time (continued)

sudo apt install mesa-opencl-icd ocl-icd-opencl-dev gcc git bzr jq pkg-config curl clang build-essential hwloc libhwloc-dev wget -y && sudo apt upgrade -y

Lotus requires Go 1.25.14 or higher according to the README badge and go.mod. The README's own install command fetches that toolchain and unpacks it into /usr/local, then reminds you to put /usr/local/go/bin on your PATH.

wget -c https://golang.org/dl/go1.25.14.linux-amd64.tar.gz -O - | sudo tar -xz -C /usr/local
echo "export PATH=$PATH:/usr/local/go/bin" >> ~/.bashrc && source ~/.bashrc

Clone the repository, then check out a release tag rather than staying on master. The README states plainly that master is the dev branch and that a production mainnet node should use the latest release; the release flow document explains why the releases branch was deprecated in favour of tags.

git clone https://github.com/filecoin-project/lotus.git
cd lotus/
git checkout <vX.X.X>   # tag for a release

The build target selects the network. make clean all builds for mainnet; make clean calibnet builds for Calibration, which the README notes uses a 32GiB minimum sector size. The default build uses prebuilt proofs binaries; building those from source is a separate documented path that also needs rustup.

make clean all      # mainnet
# or
make clean calibnet # Calibration with min 32GiB sectors
sudo make install

After install you have lotus, lotus-miner and lotus-worker in /usr/local/bin, and lotus will use $HOME/.lotus for configuration, chain data and wallets unless you override it. The README then sends you to the docs site to start the daemon and sync the chain, so treat the first sync as a separate, long-running step rather than something the build finishes for you. If you would rather not build at all, docker-compose.yaml starts a full node with docker-compose up, mounting named volumes for the proof parameters and the Lotus repository, and publishing port 1234.

Where Lotus is the wrong tool, and what to weigh first

The README is candid about one failure mode and silent about others. The candid part is the branch warning: master is the dev branch, and the project says to use it with caution. If you clone the default branch and run it against mainnet, you are running unreleased code, and the release flow document exists precisely because the project changed how releases are cut. The silent part is rollback. The README does not document a downgrade path, and the go.mod file carries three retract directives (v1.14.0, v1.20.2, v1.28.0) that show the project has, in the past, published tags it later told users not to use. Treat version selection as a decision you make before you sync, not after.

Resource shape is the second constraint. A full node is a disk and bandwidth commitment that grows with the chain, and a storage provider adds sealing hardware on top. The Calibration target's 32GiB minimum sector size is a hint about the scale involved. If your actual goal is to query chain data or send transactions, running the gateway in front of someone else's node is a smaller commitment than running the node yourself, and the docker-compose file shows that split directly.

The third case is simpler: if you need a wallet, Lotus is oversized. The repository is a node, a miner and a worker, and nothing in the README positions it as an end-user client.

How Lotus differs from other Filecoin node implementations

Lotus is the reference implementation, which means other implementations are measured against its behaviour rather than the other way round. The conformance/ directory in the repository is the concrete expression of that role: it holds the tests that pin down what a Filecoin implementation must do, and the go.mod file pulls in test vectors through a git submodule (extern/test-vectors). An alternative implementation in another language, such as a Rust or JavaScript node, is aiming at the same specification and the same vectors, but it will not share Lotus's operational surface. The CLI, the config file layout, the $HOME/.lotus repository format and the JSON-RPC API are Lotus's, and tooling written against them assumes Lotus.

The practical difference shows up in what you inherit. Choosing Lotus means inheriting the FFI and Rust build chain, the proof parameter download, and the release-tag discipline the README describes. Choosing a non-reference implementation means a different build story and, typically, a smaller set of operators who have already hit the problems you are about to hit. The repository also lists go-fil-markets and builtin-actors as tightly integrated but independent modules, so even within the Go ecosystem the surface is split across repositories rather than contained in one.

Licence and the cost of staying current

Lotus is dual-licensed under MIT and Apache 2.0, with LICENSE-MIT and LICENSE-APACHE at the repository root. The repository metadata reports the licence as NOASSERTION, which is a statement about automated detection rather than about the terms; the two licence files are the authoritative artefact, and if you are redistributing a modified build, read both rather than assuming a single permissive grant. This is not legal advice.

Upgrade cost is governed by the release process rather than by the code. The README directs mainnet operators to the latest release and explains that the releases branch is deprecated in favour of tags, so the work is: watch for a new tag, check out that tag, rebuild, and restart the daemon. The retract directives in go.mod are the reason to read release notes before moving, since a tag can be withdrawn. The repository was last pushed on 2026-09-23, and the most recent releases listed are v1.37.0-rc1 and miner/v1.37.0-rc1 from 2026-09-23, with v1.36.3 from 2026-09-11 as the preceding stable tag. A release candidate is not the tag to put on a production node.

Editorial conclusion

Lotus is the right choice if you need to run a Filecoin full node, act as a storage provider, or run the gateway in front of one, and you are willing to pin a release tag rather than track master. It is the wrong choice if you want a lightweight wallet or a hosted API and nothing to maintain: the repository ships a daemon, a miner and a worker, and the README points at lotus.filecoin.io for setup rather than offering a shortcut. Before committing hardware, verify the Go toolchain against GO_VERSION_MIN, confirm the proof parameters volume has room, and decide whether you need the prebuilt proofs binaries or the from-source Rust path, since that decision changes what you install.

Frequently asked questions

Official sources

1. filecoin-project/lotus on GitHub
2. Issues
3. Project website
4. README
5. Releases