celestia-node: running a Celestia light or bridge node

What the node does in the Celestia stack

Celestia separates consensus from data availability, and celestia-node is the part that deals with the second. The data availability network wraps the celestia-core consensus network by listening for blocks from it and making those blocks digestible for data availability sampling. The project points at its own write-up of data availability sampling for the detail, and the short version is that light clients can confirm that a block's data is available across the network without downloading the whole thing. The node software itself is the Go implementation of the two node types, light and bridge, and it sits on top of a fairly conventional Cosmos stack. The dependency list shows celestia-app and the Cosmos SDK, CometBFT for consensus, the go-square and namespace merkle tree libraries that Celestia uses for its data structures, and the libp2p stack for peer to peer traffic, alongside the IPFS libraries for content addressing.

Light or bridge, and what each one costs you

The two node types do different jobs and have different operational shapes. A bridge node relays blocks from the consensus network to the data availability network, which means it needs to follow the chain and stay connected, and it is the node whose job is to make data available to samplers. A light node verifies the availability of block data by sampling the data availability network for shares, which is a cheaper role that depends on other nodes to be serving. The hardware guidance for each type is not in this repository, it is in the Celestia documentation under the nodes overview, which is where an operator should start. What the repository does show is the dependency direction between them, since the light node path in the quick start is built around a funded wallet, while the bridge node is a relay.

Building and installing the binaries

The installation path is the familiar Go one, a clone, a build and an install, and the README gives it in three commands:

git clone https://github.com/celestiaorg/celestia-node.git
cd celestia-node
make build
sudo make install

The build produces the celestia binary along with cel-key and cel-shed, which the container image copies in as well. The minimum requirement for building is Go 1.26.8 or higher, and that is a floor rather than a suggestion, since the module file declares the same version. The supported architectures are a short list, linux on amd64 and arm64, and macOS on Intel and Apple Silicon, and the README is explicit that only those four are officially tested and supported. Anything else is a build from source that nobody has validated, which for a node that is expected to run for weeks is a decision to make deliberately.

Initialising and starting a node

Once the binary is installed, the node has an init step and a start step, and the type is an argument to both commands:

celestia <node_type> init
celestia <node_type> start

The node type is either bridge or light, so the same binary covers both roles. There is one environment variable documented, CELESTIA_BOOTSTRAPPER, which starts the node in bootstrapper mode and defaults to false, which tells you the default is a normal node rather than a seeding one. The public API of the node is documented separately, on the node RPC documentation site, so the binary is not a black box for anything an application needs to query. The Makefile also provides a help target for the node commands, so a reader can list what is available without guessing at flags, and the Celestia documentation has a guide for running a node that covers the cases the README leaves out.

The mocha quick start and its options

For a first run, the repository provides a target that does the tedious parts. The sequence is a help target to list the commands, an install target that puts the celestia and cel-key binaries in place, and then the setup command itself:

make light-mocha-up

The README lists what that command does, and the list is worth reading because it shows what a light node needs. It checks the wallet balance, it requests funds from the faucet if they are needed, it sets the node height to one below the latest so the startup is quick, and it initialises the node if this is the first time it has run. The first item is the real constraint, because a light node on mocha needs a wallet with funds, and that is a step the tooling automates but does not remove. Two options are documented as well, a COMMAND of again resets the node state to the latest height, and a CORE_IP value points the node at a specific core node instead of the default.

The code layout and the libraries doing the work

The directory names describe the architecture more precisely than a paragraph could. The share and das directories hold the share handling and the data availability sampling, header holds the block header types, core holds the consensus network client, store and state hold the persistence, pruner the logic that discards old data, and nodebuilder the code that assembles a node from its parts, including the test harness it uses. The libraries are where the hard parts live. The Reed Solomon library and the rsmt2d implementation provide the erasure coding that makes sampling possible, which light nodes then sample to check that the data is available. The namespace merkle tree library is what proves a blob belongs to a block, and the libp2p stack with the Kad DHT is how nodes find each other, with the badger based store and the go-datastore interface handling persistence and the IPFS content addressing libraries identifying the blobs.

The container image and its defaults

The Dockerfile is a conventional multi-stage build and its defaults tell you how the project expects a node to be deployed. The builder stage uses the Go 1.26.8 alpine image with CGO disabled, and it produces the celestia, cel-key and cel-shed binaries. The runtime stage is a plain alpine 3.24.2 image that runs as a dedicated unprivileged user with the identifier 10001, with the home directory set through CELESTIA_HOME, and the comment links to Dockerfile guidance that advises against a UID below 10000. Two environment variables carry the deployment intent, NODE_TYPE which defaults to bridge and P2P_NETWORK which defaults to mocha, both of which are meant to be overridden by a deployment manifest. The port exposed is 2121, and the entrypoint is a shell script shipped from the docker directory.

Licence, releases and the network suffix

The licence is Apache 2.0, with the LICENSE and NOTICE files in the repository root. The release naming is the part that needs a second look, because the tags carry a network suffix. The recent releases are v0.34.4-corto from 2026-10-14, v0.34.3 from 2026-10-07 and v0.34.3-mocha from 2026-10-06, and the Makefile has an explicit comment about it, saying the network suffix is intentionally kept in the version so that the semantic version and the default node tag are no longer stripped. The practical meaning is that a version string tells you both the release and the network it was cut for, and a binary built for one network is not interchangeable with another. The last push was on 2026-10-19, so the project moves quickly, and the tree also carries a goreleaser configuration for the release artefacts, a golangci configuration for the linter, and a docs directory with the architecture decision records that explain the design.

Editorial conclusion

celestia-node fits an operator who wants to contribute availability to the Celestia network, either by relaying blocks as a bridge node or by sampling for shares as a light node, and it fits a developer who wants a running node against the mocha test network in a few minutes. It does not fit a machine outside the four officially supported architectures, and it does not fit a beginner, because the light node path starts with a wallet that has to be funded from a faucet. Before deploying, read the hardware guidance for your node type in the Celestia documentation, decide which of the two node types you actually need, and note that the release names carry a network suffix, so a version string tells you which network a build was cut for.

Frequently asked questions

Official sources

1. celestiaorg/celestia-node on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases