> For the complete documentation index, see [llms.txt](https://service.block-pro.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://service.block-pro.net/testnet/starknet/pathfinder-node.md).

# Pathfinder Node

Install and synchronize Pathfinder on Starknet Sepolia Testnet.

**Sepolia Testnet · `SN_SEPOLIA` · Pathfinder v0.24.2**

Run each command separately in the same shell. The configuration below uses a persistent data directory and a private local RPC endpoint.

## Install Docker

On a fresh Ubuntu 24.04 server, use the following package installation. For a server with an existing container runtime, check [Docker’s compatibility instructions](https://docs.docker.com/engine/install/ubuntu/) first.

### Refresh packages

Refresh APT metadata.

```bash
sudo apt update
```

### Install basic tools

Install download and JSON tools.

```bash
sudo apt install -y ca-certificates curl jq
```

### Create the key directory

Prepare Docker’s signing-key location.

```bash
sudo install -m 0755 -d /etc/apt/keyrings
```

### Download the signing key

Get the Docker repository key.

```bash
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
```

### Set key permissions

Allow APT to read the public key.

```bash
sudo chmod a+r /etc/apt/keyrings/docker.asc
```

### Add the package repository

Configure the official stable Ubuntu repository.

```bash
sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
```

### Refresh the new repository

Load Docker’s package list.

```bash
sudo apt update
```

### Install Docker

Install Engine and Compose from the configured repository.

```bash
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
```

### Enable Docker

Start the runtime and enable it on boot.

```bash
sudo systemctl enable --now docker
```

## Configure Pathfinder

### Create the project directory

Keep configuration and persistent data together.

```bash
mkdir -p "$HOME/pathfinder-sepolia/data"
```

### Open the directory

Run Compose commands from this directory.

```bash
cd "$HOME/pathfinder-sepolia"
```

### Store your Ethereum WebSocket URL

Enter your private Sepolia wss\:// endpoint at the prompt; it will not be echoed.

```bash
read -rsp "Ethereum WebSocket URL: " ETHEREUM_URL; printf "\n"
```

### Write the private environment file

Store the endpoint with permissions restricted to your Linux account.

```bash
(umask 077; printf 'PATHFINDER_ETHEREUM_API_URL=%s\n' "$ETHEREUM_URL" > pathfinder.env)
```

### Clear the shell variable

Remove the temporary copy from the shell.

```bash
unset ETHEREUM_URL
```

### Write the Compose configuration

Pin the image and keep the database outside the container.

```bash
cat > compose.yaml <<EOF
services:
  pathfinder:
    image: swmansion/pathfinder:v0.24.2
    container_name: pathfinder-sepolia
    user: "$(id -u):$(id -g)"
    restart: unless-stopped
    stop_grace_period: 2m
    env_file:
      - pathfinder.env
    environment:
      RUST_LOG: info
    ports:
      - "127.0.0.1:9546:9545"
    volumes:
      - ./data:/usr/share/pathfinder/data
    command:
      - --network=sepolia-testnet
      - --http-rpc=0.0.0.0:9545
      - --storage.state-tries=100
    logging:
      driver: json-file
      options:
        max-size: "20m"
        max-file: "5"
EOF
```

This configuration retains recent state tries while keeping block history. For historical storage proofs, choose `--storage.state-tries=archive` before creating the database and provision extra storage. Use a snapshot with a matching mode.

### Download the image

Fetch the pinned release.

```bash
sudo docker compose pull pathfinder
```

### Optional: start from a snapshot

Follow [Snapshots](/testnet/starknet/snapshots.md) before first startup. Otherwise Pathfinder synchronizes from the network.

### Start the node

Create the container and begin synchronization.

```bash
sudo docker compose up -d pathfinder
```

### Follow logs

Check network selection and progressing blocks.

```bash
sudo docker compose logs --tail 100 -f pathfinder
```

### Verify chain ID

Expected result: `0x534e5f5345504f4c4941` (SN\_SEPOLIA).

```bash
curl -fsS http://127.0.0.1:9546/rpc/v0_10 -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","method":"starknet_chainId","params":[],"id":1}' | jq
```

### Check sync

An object reports progress; false means the node has caught up. Confirm block height also advances.

```bash
curl -fsS http://127.0.0.1:9546/rpc/v0_10 -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","method":"starknet_syncing","params":[],"id":1}' | jq
```

### Check block height

Repeat after a short interval to confirm new blocks arrive.

```bash
curl -fsS http://127.0.0.1:9546/rpc/v0_10 -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","method":"starknet_blockNumber","params":[],"id":1}' | jq
```

[Setup reference](https://docs.swmansion.com/pathfinder/getting-started/running-pathfinder/) · [Configuration reference](https://docs.swmansion.com/pathfinder/getting-started/configuration/).