celestia-app

celestia-app is the software used by validators and consensus nodes on the Celestia consensus network. celestia-app is a blockchain application built using parts of the Cosmos stack:

• celestiaorg/cosmos-sdk a fork of cosmos/cosmos-sdk
• celestiaorg/celestia-core a fork of cometbft/cometbft

Diagram

                ^  +-------------------------------+  ^
                |  |                               |  |
                |  |  State-machine = Application  |  |
                |  |                               |  |   celestia-app (built with Cosmos SDK)
                |  |            ^      +           |  |
                |  +----------- | ABCI | ----------+  v
Celestia        |  |            +      v           |  ^
validator or    |  |                               |  |
full consensus  |  |           Consensus           |  |
node            |  |                               |  |
                |  +-------------------------------+  |   celestia-core (fork of CometBFT)
                |  |                               |  |
                |  |           Networking          |  |
                |  |                               |  |
                v  +-------------------------------+  v

Install

From source

1. Install Go 1.26.9

2. Clone this repo

3. Install the celestia-appd binary. This installs a "multiplexer" binary that will also download embedded binaries for celestia-app v3 through v9.

   make install
   

Prebuilt binary

If you'd rather not install from source, you can download a prebuilt binary from the releases page.

1. Navigate to the latest release on https://github.com/celestiaorg/celestia-app/releases.

2. Download the binary for your platform (e.g. celestia-app_Linux_x86_64.tar.gz) from the Assets section. Tip: if you're not sure what platform you're on, you can run uname -a and look for the operating system (e.g. Linux, Darwin) and architecture (e.g. x86_64, arm64).

3. Extract the archive

   tar -xvf celestia-app_Linux_x86_64.tar.gz
   

4. Verify the extracted binary works

   ./celestia-appd --help
   

5. (Optional) verify the prebuilt binary checksum. Download checksums.txt and then verify the checksum:

   sha256sum --ignore-missing --check checksums.txt
   

   You should see output like this:

   celestia-app_Linux_x86_64.tar.gz: OK
   

See https://docs.celestia.org/operate/consensus-validators/install-celestia-app/ for more information.

Supported operating systems

This is the canonical matrix of operating systems that celestia-app is built for and tested against. For the OS versions a specific release was tested on, see the per-release entries in docs/release-notes/release-notes.md.

Tested in CI

celestia-app's GitHub Actions workflows run all unit, integration, and lint jobs on:

GitHub may advance ubuntu-latest to a newer LTS over time; see actions/runner-images for the current alias mapping.

Other OS / version combinations may work but are not exercised by CI and are not officially supported.

Note that arm64 binaries are cross-compiled via goreleaser but are not executed in CI; only the x86_64 build is exercised end-to-end.

Prebuilt binaries

The GitHub Releases page provides prebuilt binaries for:

Linux binaries built with the multiplexer require glibc >= 2.38 (Ubuntu 24.04 or equivalent). See Prerequisites for details.

Each release also ships the Fibre server as its own archive (fibre_Linux_x86_64.tar.gz, fibre_Darwin_arm64.tar.gz, etc.) for the same four platforms, built the same way and versioned in lockstep with celestia-appd. See fibre/cmd/README.md for usage.

Known incompatibilities

• Windows: the celestia-appd binary does not support signing with Ledger hardware wallets.
• OpenBSD: the celestia-appd binary does not support signing with Ledger hardware wallets.
• Ubuntu 22.04 and older: incompatible with multiplexer builds (glibc < 2.38).

Usage

Prerequisites

[!CAUTION] If you are using the multiplexer binary (default make build), the embedded binaries require glibc >= 2.38. This means Ubuntu 24.04 or later (or an equivalent distribution) is required. Nodes running older OS versions (e.g., Ubuntu 22.04) will fail to start with a glibc version mismatch error.

If you are on Linux, enable the BBR ("Bottleneck Bandwidth and Round-trip propagation time") congestion control algorithm.

# Check if BBR is enabled (Linux only).
make bbr-check

# If BBR is not enabled then enable it (Linux only).
make bbr-enable

Environment variables

Most flags can also be set with environment variables prefixed by the binary name, e.g. CELESTIA_APPD_PRUNING=nothing for --pruning. Some command-specific flags, such as config sync --dry-run, ignore environment variables. Client flags such as --node also accept the CELESTIA_APP_ prefix, e.g. CELESTIA_APP_NODE. start flags only accept the CELESTIA_APPD_ prefix.

Using celestia-appd

# Print help.
celestia-appd --help

# Create config files for a new chain named "test".
celestia-appd init test

# Start the consensus node.
celestia-appd start

Updating config files

celestia-appd config sync adds missing settings and their documentation using the binary's defaults. It syncs these files:

A file is skipped if it does not exist, so the command works on hosts that run only the node or only Fibre. Synchronization runs only when this command is called, not on node startup. Existing values, comments, ordering, and unknown settings are preserved; whitespace may be normalized when settings are added. Flags and environment overrides are not saved. Before replacing a file, it creates a <file>.backup-* file in the same directory. Earlier backups are never overwritten. If nothing is missing, it leaves the file untouched.

To inspect additions or update the files before restarting:

celestia-appd config sync --home ~/.celestia-app --fibre-home ~/.celestia-fibre --dry-run
celestia-appd config sync --home ~/.celestia-app --fibre-home ~/.celestia-fibre

Then edit the fields under your node's and Fibre's home directories to set the values you want before restarting.

Read-only files, linked files, and TOML layouts that cannot be safely extended are left untouched. For deployment-managed configurations, add the reported settings to the source configuration. The command returns an error on failure.

Synchronization does not update app.toml, remove deprecated settings, or replace existing values with newer defaults. Once a default is written, it remains an explicit value on later upgrades. Existing binary overrides for consensus, mempool, and P2P settings still apply.

Create a single node local testnet

# Start a single node local testnet.
./scripts/single-node.sh

# Publish blob data to the local testnet.
celestia-appd tx blob pay-for-blob 0x00010203040506070809 0x48656c6c6f2c20576f726c6421 \
	--chain-id test \
	--from validator \
	--keyring-backend test \
	--fees 21000utia \
	--yes

# Query the tx
celestia-appd query tx <txhash from previous command>

Join a public Celestia network

For instructions on running a node on Celestia's public networks, refer to the consensus node guide in the docs.

[!NOTE] When connecting to a public network, you must download the correct genesis file. Please use the celestia-appd download-genesis command.

Usage as a library

If you import celestia-app as a Go module, you may need to add some Go module replace directives to avoid type incompatibilities. Please see the replace directive in go.mod for inspiration.

Usage in tests

If you are running celestia-app in tests, you may want to override the delayed_precommit_timeout to produce blocks faster. By default, a celestia-app chain with app version >= 3 will produce blocks every ~6 seconds. To produce blocks faster, you can override the delayed_precommit_timeout with the --delayed-precommit-timeout flag.

# Start celestia-appd with a one-second block time.
celestia-appd start --delayed-precommit-timeout 1s

Fibre

Fibre (available from app v10) is Celestia's data availability protocol served by validator-operated fibre servers: blobs are erasure-coded and disseminated across the validator set instead of riding the data square. Depending on your role:

• Run a fibre server (validators): fibre/cmd/README.md — setup, on-chain host registration, and troubleshooting.
• Publish and retrieve blobs (Go): fibre/README.md — client quickstart.
• Payment module reference: x/fibre/README.md — escrow, payment promises, CLI.
• Protocol specification: specs/src/fibre.md.

Server Architecture

celestia-appd runs celestia-core and the Cosmos SDK application in one process when the native application version is active. Core handles consensus and networking; the application executes transactions and maintains module state. They communicate through ABCI. The servers below expose different services from that process.

flowchart TB
    subgraph Appd["celestia-appd process — native application"]
        Core["Core: consensus and networking<br/>RPC :26657 · gRPC :9098 · P2P :26656"]
        App["Application: transaction execution and state<br/>gRPC :9090 · REST / gRPC-Web :1317"]
        Signer["PrivValidator: local key or remote signer<br/>PrivVal gRPC :26669"]
        Core <-->|"ABCI via multiplexer"| App
        App -->|"Block API calls"| Core
        Core -->|"Sign proposals and votes"| Signer
    end
    Peers["Other consensus nodes"] <-->|"P2P"| Core
    Client["Fibre client"] <-->|"gRPC over TLS"| Fibre["Separate fibre process :7980<br/>Stores and serves blob shards"]
    Fibre -->|"Query state via app gRPC"| App
    Fibre -->|"Sign via PrivVal gRPC"| Signer
    Signer -.->|"Optional remote-signing connection"| KMS["Separate KMS process"]

When replaying older application versions, the multiplexer runs an embedded application binary in a child process and forwards ABCI calls over gRPC. Core remains in the parent process.

The addresses below are configurable defaults. Application gRPC also exposes Core's Block API on the same listener, so clients can query both application state and block data through one connection. Core gRPC does not expose application module queries.

Celestia-Core (CometBFT) Servers

Celestia-App (Cosmos SDK) Servers

Validator Signing and Fibre

PrivValidator is Core's signing interface. It uses a local consensus key or an external signer configured through priv_validator_laddr. That remote-signing connection is separate from the PrivVal gRPC endpoint exposed to Fibre.

Fibre connects to application gRPC for chain state and to PrivVal gRPC for signatures. It always requests signatures through the node, even when the key is held by an external KMS. See the Fibre server guide for connection and deployment details.

Contributing

If you are a new contributor, please read contributing to Celestia.

This repo attempts to conform to conventional commits so PR titles should ideally start with fix:, feat:, build:, chore:, ci:, docs:, style:, refactor:, perf:, or test: because this helps with semantic versioning and changelog generation. It is especially important to include an ! (e.g. feat!:) if the PR includes a breaking change.

PR titles must start the subject with [high], [medium], or [low] to indicate the review thoroughness needed. For example: fix!: [high] correct gas accounting or docs: [low] clarify setup instructions. Include the same tag in the PR description and explain why you chose it. Contributors should write their own PR titles; Dependabot generates its titles from the configured prefix.

• [high]: Deep review for consensus, state transitions, security, or other changes with significant risk.
• [medium]: Standard review for code changes with limited impact and well-understood behavior.
• [low]: Focused review for straightforward docs, tests, or tooling changes with low risk.

Choose the higher level when unsure. A small diff can still need deep review. CI checks the title format; reviewers should confirm the chosen level.

Dependabot defaults to [high] for the app's Go dependencies and [medium] for Docker, GitHub Actions, and test dependencies. Maintainers should confirm the level and add it to the PR description with a brief explanation.

External contributions must reference a meaningful issue. Open an issue explaining the value of your change before submitting unsolicited work. Trivial PRs limited to comment wording, typos, formatting, or irrelevant test updates may be closed. Low-effort AI-generated PRs will be closed; contributors using AI must understand, review, and revise its output before submission.

This repo contains multiple go modules. When using it, rename go.work.example to go.work and run go work sync.

Tools

1. Install markdownlint 0.39.0
2. Install hadolint
3. Install yamllint
4. Install markdown-link-check
5. Install goreleaser

Helpful Commands

# Get more info on make commands.
make help

# Build the celestia-appd binary into the ./build directory.
make build

# Build and install the celestia-appd binary into the $GOPATH/bin directory.
make install

# Run tests.
make test

# Format code with linters (this assumes golangci-lint and markdownlint are installed).
make lint-fix

# Regenerate Protobuf files (this assumes Docker is running).
make proto-gen

Docs

Package-specific READMEs aim to explain implementation details for developers that are contributing to these packages. The specs aim to explain the protocol as a whole for developers building on top of Celestia.

Dependency branches

The source of truth for dependencies is the go.mod file but the table below describes the compatible branches for celestiaorg repos.

Audits