# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.citrea.xyz/developer-documentation/run-a-node.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.