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:
| Resource | Minimum |
|---|---|
| Memory | 500 MB RAM |
| CPU | Single core |
| Disk | 20 GB SSD |
| Bandwidth | 56 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:
sudo apt update && sudo apt install -y curl tar jqPick 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.
| Network | Chain ID | celestia-node | Network flag | Node store |
|---|---|---|---|---|
| Mainnet Beta | celestia | v0.34.3 | --p2p.network celestia (default) | ~/.celestia-light |
| Mocha testnet | mocha-5 | v0.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.
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:
sha256sum --ignore-missing -c checksums.txtThe 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:
tar -xzf "celestia-node_Linux_${ARCH}.tar.gz" celestia
sudo install -m 0755 celestia /usr/local/bin/celestia
celestia versionThe 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.
# 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-mochaBuild 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.
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-keyOn 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.
celestia light initFor Mocha:
celestia light init --p2p.network mochaThe 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:
cel-key add <key-name> --recover --keyring-backend test --node.type lightAdd --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-fauceton 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:
| Network | gRPC host | Port | TLS |
|---|---|---|---|
| Mainnet Beta | public-endpoint.celestia-mainnet.quiknode.pro | 9090 | yes |
| Mocha | public-endpoint.celestia-mocha.quiknode.pro | 9090 | yes |
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:
{
"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.
celestia light start \
--p2p.network celestia \
--core.ip <core-grpc-host> \
--core.port 9090 \
--core.tlsFor 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:
sudo ufw allow 2121/tcp
sudo ufw allow 2121/udpThe 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.
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
15EOFFor 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:
sudo systemctl daemon-reload
sudo systemctl enable --now celestia-lightd
sudo journalctl -u celestia-lightd -fVerify 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:
celestia header sync-stateCheck sampling:
celestia das sampling-statsLook for these fields in the result:
head_of_sampled_chainmoves towardnetwork_head_height.catch_up_doneturnstrueonce the node has caught up.is_runningstaystrue.
Confirm the node type, version and peer identity:
celestia node info
celestia p2p infonode info returns "type": "Light" and the api_version. If you set a core endpoint, check the balance too:
celestia state balanceTo 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:
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":[]}' | jqOn 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:
sudo systemctl stop celestia-lightdConfig 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:
celestia light config-update --p2p.network celestiaOn 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#
- By default, a light node syncs headers and samples only within its pruning window, about the last 7 days, not from genesis. To start from a different trusted point, set
SyncFromHeightandSyncFromHashunder[Header.Syncer]inconfig.toml, and leave the0xprefix off the hash. This means you trust whoever supplied the hash. The advanced light node guide (opens in a new tab) covers the details. - Post and read a blob with
celestia blob submitandcelestia blob get. In v0.34.3, the node submits data without a0xprefix as plain text, so keep the prefix for hex data. See the quickstart (opens in a new tab). - Track upgrades on the network upgrades (opens in a new tab) page and the celestia-node releases (opens in a new tab). Read the release notes before each upgrade for config or CLI changes.
- Export node metrics with the DA node metrics guide (opens in a new tab).