Running a Node With Docker

Run an OP Stack node (op-reth + op-node) using the official Docker images and docker-compose.

op-geth reaches end-of-support on 2026-05-31 and will not support the L1 Glamsterdam hardfork. 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

1. Create a working directory

   mkdir op-stack-node && cd op-stack-node
   
2. Generate the JWT secret

   Both containers share a JWT secret over a bind mount:

   openssl rand -hex 32 > jwt.txt
   
3. 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.

4. 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.

5. 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.

1. Stop the containers

   docker compose down
   rm -rf reth-data       # only if you previously synced and want to start clean
   
2. 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
   
3. 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.

4. 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.