Run a Celestia light node

Written by Furi9 min read

On this page

This guide sets up a Celestia light node with celestia-node v0.34.3 on Mainnet Beta, running under systemd and sampling block data. It is for node operators and web3 developers, and it notes the Mocha testnet differences at each step.

Prerequisites#

A light node performs data availability sampling (DAS). It checks that block data is available without downloading whole blocks, so its hardware needs are small. The official minimums for a non-archival light node are:

ResourceMinimum
Memory500 MB RAM
CPUSingle core
Disk20 GB SSD
Bandwidth56 Kbps

celestia-node officially supports four platforms: linux/amd64, linux/arm64, darwin/amd64 and darwin/arm64. This guide uses an Ubuntu or Debian server with systemd.

Install the tools that the commands below need:

bash
sudo apt update && sudo apt install -y curl tar jq

Pick your network. Versions change at network upgrades, so confirm them on the Mainnet Beta (opens in a new tab) and Mocha (opens in a new tab) pages before you install.

NetworkChain IDcelestia-nodeNetwork flagNode store
Mainnet Betacelestiav0.34.3--p2p.network celestia (default)~/.celestia-light
Mocha testnetmocha-5v0.34.3-mocha--p2p.network mocha~/.celestia-light-mocha-5

GitHub lists Mocha releases as pre-releases. Install the tag listed for your network, not whatever GitHub shows as the latest release.

1. Install celestia-node#

Download the release binary and verify it#

Set the version and your CPU architecture. Use x86_64 on Intel or AMD servers and arm64 on ARM servers.

bash
VERSION="v0.34.3"   # Mocha: v0.34.3-mocha
ARCH="x86_64"       # or arm64
cd "$HOME"
curl -LO "https://github.com/celestiaorg/celestia-node/releases/download/${VERSION}/celestia-node_Linux_${ARCH}.tar.gz"
curl -LO "https://github.com/celestiaorg/celestia-node/releases/download/${VERSION}/checksums.txt"

Check the archive against the published checksum:

bash
sha256sum --ignore-missing -c checksums.txt

The line for your file must end with OK. If it does not, delete the download and try again. Do not run an archive that fails this check.

Extract the celestia binary and install it:

bash
tar -xzf "celestia-node_Linux_${ARCH}.tar.gz" celestia
sudo install -m 0755 celestia /usr/local/bin/celestia
celestia version

The official docs also offer an install script that downloads the same release and verifies its checksum. Read the script (opens in a new tab) before you run it, and always pass -v with your network's tag. Without -v, the script installs the latest stable release, which skips Mocha pre-releases.

bash
# Mainnet Beta
bash -c "$(curl -sL https://docs.celestia.org/celestia-node.sh)" -- -v v0.34.3
# Mocha
bash -c "$(curl -sL https://docs.celestia.org/celestia-node.sh)" -- -v v0.34.3-mocha

Build from source to get cel-key#

Build from source if you also want the cel-key utility, which the release archive does not include. v0.34.3 requires Go 1.26.8 or later. Install Go, git and make with the official environment setup guide (opens in a new tab) first.

bash
cd "$HOME"
git clone https://github.com/celestiaorg/celestia-node.git
cd celestia-node
git checkout tags/v0.34.3   # Mocha: tags/v0.34.3-mocha
make build
sudo make install
make install-key

On Linux, make install copies the binary into /usr/local/bin, which is why that command needs sudo. make install-key places cel-key in your Go bin directory.

2. Initialize the light node#

Initialization creates the node store and a new account key.

bash
celestia light init

For Mocha:

bash
celestia light init --p2p.network mocha

The output prints the key name (my_celes_key), its celestia1... address, and a mnemonic. Anyone with the mnemonic controls the key, so handle it with care:

  • Write it down offline, on paper or in an offline password manager.
  • Never paste it into a website, chat, support ticket or AI tool.
  • Clear any terminal scrollback or session logs that captured it.

The default keyring backend is test, and init logs a warning that it is plaintext. It stores the key unencrypted under ~/.celestia-light/keys/keyring-test/ on Mainnet Beta, or ~/.celestia-light-mocha-5/keys/keyring-test/ on Mocha. Make sure only the node's user can read that directory. Keep only the TIA you need for fees on this key. The encrypted file backend asks for a passphrase at startup, so it does not suit an unattended service.

To use an existing key instead, recover it with cel-key in your own terminal. Replace <key-name> with a label of your choice:

bash
cel-key add <key-name> --recover --keyring-backend test --node.type light

Add --p2p.network mocha for Mocha. Then pass --keyring.keyname <key-name> when you start the node.

3. Fund the key if you will submit blobs#

Sampling costs nothing. The account needs tokens only to pay for transactions, such as PayForBlobs when you post data.

  • On Mainnet Beta, send TIA to the node address from a wallet you control.
  • On Mocha, request testnet tokens from the web faucet (opens in a new tab). You can also post $request <celestia-address> in #mocha-faucet on the Celestia Discord, using your node address. The limit is 10 tokens per week per address or Discord ID. Testnet tokens have no value.

Once the node runs with a core endpoint, celestia state account-address prints the address.

4. Choose a core endpoint#

The light node gets block headers and samples from the DA network over P2P. For state access, it connects to a consensus node over gRPC, on port 9090 by default. State access covers balances, account queries and transaction submission.

Sampling does not need a core endpoint. If you leave out --core.ip, the node still syncs and samples, but state calls fail.

The official docs list these public endpoints:

NetworkgRPC hostPortTLS
Mainnet Betapublic-endpoint.celestia-mainnet.quiknode.pro9090yes
Mochapublic-endpoint.celestia-mocha.quiknode.pro9090yes

These shared endpoints have no production SLA. For production, use a provider with an SLA or your own consensus node. The network pages also list community gRPC endpoints, and the docs advise against relying on them for production.

If your provider requires an x-token, put it in a file named xtoken.json in a private directory:

json
{
  "x-token": "<your-x-token>"
}

Run chmod 600 on that file. Then add --core.xtoken.path <directory> to the start command, where <directory> is the folder that holds the file. The node reads this path only when you also set --core.tls.

5. Start the node#

Replace <core-grpc-host> with your chosen gRPC host. Keep --core.tls for TLS endpoints like the public ones above. Drop it for a plaintext endpoint, such as your own consensus node on a private network.

bash
celestia light start \
  --p2p.network celestia \
  --core.ip <core-grpc-host> \
  --core.port 9090 \
  --core.tls

For Mocha, use --p2p.network mocha and a Mocha endpoint.

The node uses port 2121 over TCP and UDP for P2P. On a cloud server, allow it through the firewall:

bash
sudo ufw allow 2121/tcp
sudo ufw allow 2121/udp

The JSON-RPC API listens on localhost:26658. Keep it bound to localhost and do not open it to the internet.

Watch the logs for a minute, then stop the node with Ctrl+C before you set up the service.

6. Run the node with systemd#

Create the service file. $USER and $(which celestia) expand when you run the command, so run it as the user that ran init. Replace <core-grpc-host> first.

bash
1sudo tee /etc/systemd/system/celestia-lightd.service > /dev/null <<EOF
2[Unit]
3Description=celestia light node
4After=network-online.target
5Wants=network-online.target
6
7[Service]
8User=$USER
9ExecStart=$(which celestia) light start --p2p.network celestia --core.ip <core-grpc-host> --core.port 9090 --core.tls
10Restart=on-failure
11RestartSec=3
12
13[Install]
14WantedBy=multi-user.target
15EOF

For Mocha, change the network flag and endpoint in ExecStart. Check the result with cat /etc/systemd/system/celestia-lightd.service, then enable and start the service:

bash
sudo systemctl daemon-reload
sudo systemctl enable --now celestia-lightd
sudo journalctl -u celestia-lightd -f

Verify it works#

The CLI finds the running node store on its own and signs a local admin token from it. Run these commands as the service user.

Check header sync. Sync is complete when height reaches to_height:

bash
celestia header sync-state

Check sampling:

bash
celestia das sampling-stats

Look for these fields in the result:

  • head_of_sampled_chain moves toward network_head_height.
  • catch_up_done turns true once the node has caught up.
  • is_running stays true.

Confirm the node type, version and peer identity:

bash
celestia node info
celestia p2p info

node info returns "type": "Light" and the api_version. If you set a core endpoint, check the balance too:

bash
celestia state balance

To query the node from scripts or another tool, call the JSON-RPC API with an auth token. You cannot revoke a token after you issue it, so request the lowest permission level you need and set a time limit:

bash
AUTH_TOKEN=$(celestia light auth read --ttl 1h)
curl -s -X POST http://localhost:26658 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -d '{"id":1,"jsonrpc":"2.0","method":"das.SamplingStats","params":[]}' | jq

On Mocha, add --p2p.network mocha to the auth command. das.SamplingStats works with a read token. node.Info needs an admin token.

Troubleshooting#

State calls return "node is running without state access"#

The node started without a core endpoint. Add --core.ip, --core.port and, for TLS endpoints, --core.tls. Add the same flags to the systemd unit, then run sudo systemctl daemon-reload and restart the service.

"Error: node: store is in use"#

Only one process can open a node store at a time. You probably started the node by hand while the service was running. Stop one of them:

bash
sudo systemctl stop celestia-lightd

Config errors after an upgrade#

Errors such as nodebuilder/share: interval must be positive point to an old config. Back up config.toml, then merge in the new fields:

bash
celestia light config-update --p2p.network celestia

On Mocha, use mocha as the network. Review your custom values before you start the node again. The docs require this step when you upgrade from a version before v0.31.3.

"node: store is not initialized" on Mocha#

Without --p2p.network, celestia-node defaults to Mainnet Beta. A Mocha node started without the flag looks in ~/.celestia-light instead of ~/.celestia-light-mocha-5 and finds no initialized store. Use the same network flag in init, start, auth and the systemd unit.

Next steps#

Keep reading

All guides
  • 13 min read

    Relay IBC packets with Hermes

    This guide is for node operators who want to relay IBC packets between Cosmos Hub and Osmosis. At the end, Hermes relays on the existing transfer channel with…