Running Nodes

Run your own node to connect to Immutable Chain.

Immutable Geth

View the node software source code

Immutable Chain supports two types of nodes for connecting to the network:

Type	Description	Access
Public	For partners wanting to run a node in the network	Permissionless
Private	For critical infrastructure partners with direct Immutable relationship	Requires allowlisting

Public Nodes

Public nodes do not participate in txpool gossiping—they forward all transactions directly to the Immutable RPC endpoint. This manages gossiping load while processing all transactions normally.

Requirements

Hardware: 2 AWS vCPU, 4GB RAM, 100GB free storage
OS: Ubuntu 22.04.1 (tested)
Software: Docker

Setup Instructions

1. Create data directory

mkdir /opt/immutable-zkevm

2. Pull the Docker image

docker pull ghcr.io/immutable/immutable-geth/immutable-geth:latest
docker tag ghcr.io/immutable/immutable-geth/immutable-geth:latest geth

3. Initialize the node

Testnet
Mainnet

docker run \
  --rm \
  -v /opt/immutable-zkevm:/mnt/geth \
  --name geth \
  geth immutable bootstrap rpc \
  --zkevm testnet \
  --datadir /mnt/geth

docker run \
  --rm \
  -v /opt/immutable-zkevm:/mnt/geth \
  --name geth \
  geth immutable bootstrap rpc \
  --zkevm mainnet \
  --datadir /mnt/geth

4. Start the node as a service

Testnet
Mainnet

docker run \
  -d \
  --restart=always \
  -v /opt/immutable-zkevm:/mnt/geth \
  --name geth \
  -p 8545:8545 \
  geth \
  --zkevm testnet \
  --config /etc/geth/testnet-public.toml \
  --datadir /mnt/geth \
  --http \
  --http.port "8545" \
  --http.addr "0.0.0.0" \
  --gossipdefault \
  --disabletxpoolgossip \
  --rpcproxy

docker run \
  -d \
  --restart=always \
  -v /opt/immutable-zkevm:/mnt/geth \
  --name geth \
  -p 8545:8545 \
  geth \
  --zkevm mainnet \
  --config /etc/geth/mainnet-public.toml \
  --datadir /mnt/geth \
  --http \
  --http.port "8545" \
  --http.addr "0.0.0.0" \
  --gossipdefault \
  --disabletxpoolgossip \
  --rpcproxy

Verify Deployment

Check logs

docker logs geth

You should see output indicating the node is syncing:

INFO [12-04|04:54:26.754] Chain ID:  13473 (unknown)
INFO [12-04|04:54:26.754] Consensus: Clique (proof-of-authority)
INFO [12-04|04:54:36.978] Block synchronisation started
INFO [12-04|04:54:37.205] Imported new chain segment number=1,343,079

Verify chain ID

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

Expected responses:

Testnet: {"jsonrpc":"2.0","id":1,"result":"0x34a1"} (13473)
Mainnet: {"jsonrpc":"2.0","id":1,"result":"0x343b"} (13371)

Private Nodes

Private nodes are for partners providing critical infrastructure with a direct relationship with Immutable. They require allowlisting via WireGuard or static IP.

Most node operators should use the permissionless public node setup. Contact your Immutable representative if you need private node access.

Access Methods

WireGuard: Generate keys and provide your public key to Immutable:

sudo apt-get install wireguard
umask 077
wg genkey > wg-privatekey
wg pubkey < wg-privatekey > wg-publickey

After receiving your WireGuard config, update PrivateKey and start:

# Save config to /etc/wireguard/wg0.conf
wg-quick up wg0

Static IP: Provide your static IP to your Immutable contact for allowlisting.

Private Node Startup

Running private nodes is the same as the process for public nodes described above, with the exception of step 4, “Start the node as a service”:

Testnet
Mainnet

docker run \
  -d \
  --restart=always \
  -v /opt/immutable-zkevm:/mnt/geth \
  --name geth \
  -p 8545:8545 \
  geth \
  --zkevm testnet \
  --config /etc/geth/testnet.toml \
  --datadir /mnt/geth \
  --http \
  --http.port "8545" \
  --http.addr "0.0.0.0"

docker run \
  -d \
  --restart=always \
  -v /opt/immutable-zkevm:/mnt/geth \
  --name geth \
  -p 8545:8545 \
  geth \
  --zkevm mainnet \
  --config /etc/geth/mainnet.toml \
  --datadir /mnt/geth \
  --http \
  --http.port "8545" \
  --http.addr "0.0.0.0"

Next Steps

Chain Overview

Learn about Immutable Chain

Ecosystem Partners

Explore RPC provider partners

Differences from Ethereum

Review chain differences

Faucet

Get testnet tokens

PRODUCTS

GUIDES

Immutable Geth

Public Nodes

Requirements

Setup Instructions

Verify Deployment

Private Nodes

Access Methods

Private Node Startup

Next Steps

Chain Overview

Ecosystem Partners

Differences from Ethereum

Faucet

Immutable Geth

​Public Nodes

​Requirements

​Setup Instructions

​Verify Deployment

​Private Nodes

​Access Methods

​Private Node Startup

​Next Steps

Chain Overview

Ecosystem Partners

Differences from Ethereum

Faucet

Public Nodes

Requirements

Setup Instructions

Verify Deployment

Private Nodes

Access Methods

Private Node Startup

Next Steps