> For the complete documentation index, see [llms.txt](https://docs.citrea.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.citrea.xyz/developer-documentation/run-a-node.md).

# Run Citrea Full Node

Running a Citrea node is permissionless - anyone can run a full node for development & security purposes.

{% hint style="warning" %}
**A Citrea Full Node requires a Bitcoin node.** Citrea uses Bitcoin as its DA layer, so before running a Citrea node you need a fully synced Bitcoin Mainnet node running with `-txindex=1`. Set one up first by following [Bitcoin Mainnet](https://docs.citrea.xyz/developer-documentation/run-a-node/bitcoin-mainnet), then use its RPC URL, username, and password in the steps below.
{% endhint %}

The easiest way to get started is to use the Citrea full node Docker image.

### Step 1: Install Docker

Follow instructions to install Docker [here](https://docs.docker.com/engine/install/).

### Step 2: Run Citrea Full Node (mainnet)

```sh
docker run -d \
  -e NETWORK=mainnet \
  -e NODE_URL=<your_bitcoin_node_rpc_url> \
  -e NODE_USERNAME=<your_bitcoin_rpc_username> \
  -e NODE_PASSWORD=<your_bitcoin_rpc_password> \
  -v citrea-data:/mnt/task/citrea-db \
  -p 8080:8080 \
  chainwayxyz/citrea-full-node:latest
```

This starts a Citrea mainnet full node. You must provide a fully synced Bitcoin mainnet node running with `-txindex=1` for `NODE_URL`

{% hint style="info" %}
**Running on Testnet?** Set `NETWORK=testnet` and point `NODE_URL` at a Bitcoin **Testnet4** node (see [Bitcoin Mainnet](https://docs.citrea.xyz/developer-documentation/run-a-node/bitcoin-mainnet) — each guide has a Testnet4 info box). Everything else stays the same:

```sh
docker run -d \
  -e NETWORK=testnet \
  -e NODE_URL=<your_bitcoin_testnet4_node_rpc_url> \
  -e NODE_USERNAME=<your_bitcoin_rpc_username> \
  -e NODE_PASSWORD=<your_bitcoin_rpc_password> \
  -v citrea-data:/mnt/task/citrea-db \
  -p 8080:8080 \
  chainwayxyz/citrea-full-node:latest
```

{% endhint %}

{% hint style="info" %}
Please note that **there are no financial incentives** to run a Citrea Full Node. It's for your own development setup and security practices.
{% endhint %}

***

## Mainnet manual setup (binary or source)

If you prefer to avoid Docker or need to customize your setup, use one of the options below.

### Option 1: Pre-built binary

1. Download the latest binary for your OS from the Citrea releases page.
2. Download mainnet config and genesis files:

```sh
curl https://raw.githubusercontent.com/chainwayxyz/citrea/nightly/resources/configs/mainnet/rollup_config.toml --output rollup_config.toml
mkdir -p genesis
curl https://raw.githubusercontent.com/chainwayxyz/citrea/nightly/resources/genesis/mainnet/evm.json --output genesis/evm.json
curl https://raw.githubusercontent.com/chainwayxyz/citrea/nightly/resources/genesis/mainnet/accounts.json --output genesis/accounts.json
curl https://raw.githubusercontent.com/chainwayxyz/citrea/nightly/resources/genesis/mainnet/l2_block_rule_enforcer.json --output genesis/l2_block_rule_enforcer.json
```

3. Run the node (example for macOS):

```sh
./citrea-v2.4.0-osx-arm64 --network mainnet --da-layer bitcoin --rollup-config-path ./rollup_config.toml --genesis-paths ./genesis
```

{% hint style="info" %}
**Testnet config & genesis:** To run on testnet, download the `testnet` config and genesis instead and run with `--network testnet`:

```sh
curl https://raw.githubusercontent.com/chainwayxyz/citrea/nightly/resources/configs/testnet/rollup_config.toml --output rollup_config.toml
mkdir -p genesis
curl https://raw.githubusercontent.com/chainwayxyz/citrea/nightly/resources/genesis/testnet/evm.json --output genesis/evm.json
curl https://raw.githubusercontent.com/chainwayxyz/citrea/nightly/resources/genesis/testnet/accounts.json --output genesis/accounts.json
curl https://raw.githubusercontent.com/chainwayxyz/citrea/nightly/resources/genesis/testnet/l2_block_rule_enforcer.json --output genesis/l2_block_rule_enforcer.json

./citrea-v2.4.0-osx-arm64 --network testnet --da-layer bitcoin --rollup-config-path ./rollup_config.toml --genesis-paths ./genesis
```

{% endhint %}

### Option 2: Build from source

1. Clone the repository and checkout the latest tag:

```sh
git clone https://github.com/chainwayxyz/citrea
cd citrea
git fetch --tags
git checkout $(git describe --tags `git rev-list --tags --max-count=1`)
```

2. Build and run:

```sh
SKIP_GUEST_BUILD=1 cargo build --release
./target/release/citrea --network mainnet --da-layer bitcoin --rollup-config-path ./resources/configs/mainnet/rollup_config.toml --genesis-paths ./resources/genesis/mainnet
```

{% hint style="info" %}
**Testnet:** the repo also ships testnet config and genesis. Build the same way and run with `--network testnet`:

```sh
./target/release/citrea --network testnet --da-layer bitcoin --rollup-config-path ./resources/configs/testnet/rollup_config.toml --genesis-paths ./resources/genesis/testnet
```

{% endhint %}

{% hint style="info" %}
**Want to sync faster?** Syncing from genesis can take a while. You can start from a recent snapshot instead — see [Full Node Snapshots](https://docs.citrea.xyz/developer-documentation/run-a-node/snapshots).
{% endhint %}

### Step 3: Check the sync status

You can check the status with the following command (you may need to arrange the URL at the end based on your setup):

```sh
curl -X POST --header "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"citrea_syncStatus","params":[], "id":31}' http://0.0.0.0:8080
```

A sample response (fields may vary based on the sync status):

```json
{
  "jsonrpc": "2.0",
  "id": 31,
  "result": {
    "l1Status": {
      "Synced": 46916
    },
    "l2Status": {
      "Syncing": {
        "headBlockNumber": 252441,
        "syncedBlockNumber": 123425
      }
    }
  }
}
```

## Hardware Requirements for running a node

A Linux/Mac/Windows system with a configuration of

* 8 GB RAM
* 2 TB SSD (NVMe recommended)
* 4 core CPU (if you're using cloud)
* 25+ Mbps network connection

should satisfy the minimum requirements to run a Citrea node. Allocating more resources improves the syncing speed.

***

If you encounter any problems during the node running even though you have a system that fits the requirements, please visit our [Discord](https://discord.gg/citrea) and let us know by opening a ticket.

{% hint style="info" %}
**Looking for Testnet?** There's no separate testnet guide — each step above has a Testnet info box showing the changes (set `NETWORK=testnet` / `--network testnet`, use the `testnet` config & genesis, and point at a Bitcoin Testnet4 node).
{% endhint %}