Optimism Documentation

op-geth has reached end-of-support (2026-05-31) and does not support the now-active Karst hardfork, so op-geth nodes can no longer follow the canonical chain. This tutorial runs op-reth (the primary supported execution client) via Docker. See the op-geth deprecation notice for the full migration plan.

This tutorial runs an OP Stack node using the official op-reth and op-node Docker images in a single docker-compose.yml. No source build required.

OP Mainnet requires a one-time pre-Bedrock state import. OP Sepolia does not. If you point this tutorial at OP Mainnet on a fresh datadir, op-reth will fail at startup with Op-mainnet has been launched without importing the pre-Bedrock state. Before running OP Mainnet, follow the op-reth sync-op-mainnet guide to either restore from a pre-synced snapshot or run the minimal-bootstrap import. OP Sepolia bootstraps via snap sync with no extra steps — start there if you’re just testing the setup.

Dependencies

Docker
Docker Compose (v2)
An L1 execution RPC endpoint (Ethereum mainnet for OP Mainnet, or Ethereum Sepolia for OP Sepolia).
An L1 Beacon API endpoint for the same L1 chain. Needed by op-node to fetch blob data post-Ecotone.

Quick start

Create a working directory

mkdir op-stack-node && cd op-stack-node

Generate the JWT secret

Both containers share a JWT secret over a bind mount:

openssl rand -hex 32 > jwt.txt

Create the .env file

Configure your network and L1 endpoints. Pick one network block (Sepolia or Mainnet) and fill in your L1 RPC + Beacon URLs:

cat > .env <<'EOF'
# --- Network: OP Sepolia (default) ---
OP_RETH_CHAIN=optimism_sepolia
OP_NODE_NETWORK=op-sepolia
OP_RETH_SEQUENCER=https://sepolia-sequencer.optimism.io

# --- Network: OP Mainnet (uncomment to use instead) ---
# OP_RETH_CHAIN=optimism
# OP_NODE_NETWORK=op-mainnet
# OP_RETH_SEQUENCER=https://mainnet-sequencer.optimism.io

# --- L1 endpoints (required) ---
L1_RPC_URL=https://your-l1-rpc-endpoint
L1_RPC_KIND=basic
L1_BEACON_URL=https://your-l1-beacon-endpoint
EOF

L1_RPC_KIND valid values: alchemy, quicknode, infura, parity, nethermind, debug_geth, erigon, basic, any. Use basic if unsure.

OP_RETH_CHAIN and OP_NODE_NETWORK accept any superchain-registry chain (e.g. unichain / unichain-mainnet, soneium / soneium-mainnet). For each chain, point L1_RPC_URL / L1_BEACON_URL at the corresponding L1 (Ethereum Mainnet or Sepolia) and update OP_RETH_SEQUENCER to that chain’s sequencer endpoint.

Create docker-compose.yml

services:
  op-reth:
    image: us-docker.pkg.dev/oplabs-tools-artifacts/images/op-reth:v2.2.5
    container_name: op-reth
    ports:
      - "8545:8545"          # JSON-RPC HTTP
      - "8546:8546"          # JSON-RPC WebSocket
      - "9001:9001"          # Prometheus metrics
      - "30303:30303"        # P2P TCP
      - "30303:30303/udp"    # P2P UDP
    volumes:
      - ./reth-data:/data
      - ./jwt.txt:/jwt.txt:ro
    command:
      - node
      - --chain=${OP_RETH_CHAIN}
      - --datadir=/data
      - --http
      - --http.addr=0.0.0.0
      - --http.port=8545
      - --ws
      - --ws.addr=0.0.0.0
      - --ws.port=8546
      - --authrpc.addr=0.0.0.0
      - --authrpc.port=8551
      - --authrpc.jwtsecret=/jwt.txt
      - --rollup.sequencer=${OP_RETH_SEQUENCER}
      - --metrics=0.0.0.0:9001
    restart: unless-stopped

  op-node:
    image: us-docker.pkg.dev/oplabs-tools-artifacts/images/op-node:v1.18.2
    container_name: op-node
    depends_on:
      - op-reth
    ports:
      - "9545:7000"          # JSON-RPC HTTP (host 9545 → container 7000; macOS uses 7000 for AirPlay)
      - "7300:7300"          # Prometheus metrics
      - "9222:9222"          # P2P TCP
      - "9222:9222/udp"      # P2P UDP
    volumes:
      - ./jwt.txt:/jwt.txt:ro
    command:
      - op-node
      - --l1=${L1_RPC_URL}
      - --l1.rpckind=${L1_RPC_KIND}
      - --l1.beacon=${L1_BEACON_URL}
      - --l2=ws://op-reth:8551
      - --l2.jwt-secret=/jwt.txt
      - --network=${OP_NODE_NETWORK}
      - --syncmode=execution-layer
      - --l2.enginekind=reth
      - --rpc.addr=0.0.0.0
      - --rpc.port=7000
      - --metrics.enabled
      - --metrics.addr=0.0.0.0
      - --metrics.port=7300
    restart: unless-stopped

The op-reth datadir is bind-mounted from ./reth-data on the host so you can inspect / restore from a snapshot directly (see Bootstrap from a snapshot below).Image tags shown are the latest as of writing. For the current tags, see the op-reth releases and op-node releases.

Start the node

docker compose up -d

Follow logs with:

docker compose logs -f

Verification

Check the node is alive and advancing:

curl -s -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
  http://localhost:8545

Expected: {"jsonrpc":"2.0","id":1,"result":"0x..."} with the current block in hex. Run again after a minute — the number should increase as sync progresses. For op-node sync status (unsafe, safe, and finalized heads in one call):

curl -s -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"optimism_syncStatus","params":[],"id":1}' \
  http://localhost:9545 | jq .

During the initial EL-driven sync (--syncmode=execution-layer), unsafe_l2 tracks the tip via libp2p gossip while safe_l2 and finalized_l2 stay at 0. This is expected — op-node defers L1 derivation until op-reth finishes its staged sync. Once the EL catches up, derivation begins and the safe/finalized heads start advancing.

You can also tail op-node logs directly:

docker compose logs op-node | grep -E "Sync progress|Finished EL sync"

Bootstrap from a snapshot

Syncing from scratch is fine for OP Sepolia (~30–50 GB, hours) but slow for OP Mainnet (~700 GB, days). For Mainnet — or anytime you’d rather skip the initial sync — bootstrap op-reth from a pre-synced snapshot.

For OP Mainnet, a snapshot also handles the pre-Bedrock state requirement (see the warning at the top of this page) in one step.

Stop the containers

docker compose down
rm -rf reth-data       # only if you previously synced and want to start clean

Download a snapshot

Browse datadirs.optimism.io for the snapshot matching your network and pick a recent file. Then download and verify the SHA256:

curl -fLO https://datadirs.optimism.io/<snapshot-file>.tar.zst

# Verify checksum against the value on the index page
sha256sum <snapshot-file>.tar.zst   # Linux
shasum -a 256 <snapshot-file>.tar.zst   # macOS

Extract into the datadir

The bind-mounted directory is ./reth-data (relative to your docker-compose.yml):

mkdir -p reth-data
tar -I zstd -xvf <snapshot-file>.tar.zst -C reth-data --strip-components=1

--strip-components=1 removes the top-level wrapping directory inside the tarball. Run tar -tf <snapshot-file>.tar.zst | head -3 first to confirm — if files are already at the archive root, omit --strip-components.

Start the node

docker compose up -d
docker compose logs -f op-reth

op-reth will recognize the existing datadir on startup and pick up from the snapshot’s tip — latest_block should be the snapshot’s height, not 0. It will then catch up from that tip to current (minutes for Sepolia, hours for Mainnet, depending on snapshot age).

Next steps

Node Metrics and Monitoring Guide — wire up Prometheus/Grafana against the metrics port.
Node Troubleshooting Guide — if you run into problems.
Building and running an OP Stack node from source — if you need a custom build or want to inspect the source.

Getting Started

Guides

Tutorials

Reference

Archive

Running a Node With Docker

Dependencies

Quick start

Verification

Bootstrap from a snapshot

Next steps

​Dependencies

​Quick start

​Verification

​Bootstrap from a snapshot

​Next steps

Dependencies

Quick start

Verification

Bootstrap from a snapshot

Next steps