Skip to content
Get packs

Guide · Open source

How to use Ink Node: run an Ink Sepolia or Mainnet node with Docker

Updated · written with AI from the project's own documentation and checked against our catalogue data

Ink Node is an open-source Docker Compose setup for running your own node on the Ink network, an Optimism-based blockchain. It starts an op-reth execution client, an op-node rollup node, a healthcheck service, and Prometheus and Grafana dashboards. This guide walks through the prerequisites, the environment file, starting the stack, and confirming it is syncing, so you can run an Ink Sepolia testnet node or a Mainnet node.

Ink Nodeinkonchain/node · ★ 36.4k · MIT

Quick start

  1. 1Check prerequisites. Install Docker Engine with Compose v2 or Docker Desktop, and confirm you have working L1 execution RPC and beacon API endpoints for your target Ethereum network.
  2. 2Clone the repository. Run git clone on the inkonchain/node repository and change into the node directory.
  3. 3Create your env file. Copy .env.example to .env and set NETWORK_NAME, NODE_TYPE, your L1 endpoints and the healthcheck reference RPC.
  4. 4Start the stack. Run docker compose up -d --build. The first start restores a large snapshot and can take a long time.
  5. 5Verify services. Run docker compose ps and check the logs for RPC HTTP server started and Rollup node started.
  6. 6Confirm sync. Call optimism_syncStatus on port 9545 and check that current_l1 advances toward head_l1.

What you need before you start

You need Docker Engine and Docker Compose v2 on Linux, or Docker Desktop on macOS and Windows. You also need working L1 execution RPC and L1 beacon API endpoints for the Ethereum network that matches your target Ink network. Free public endpoints are not enough for the L1 connection, according to the README.

Check your disk and memory too. The README recommends 16GB+ RAM and a 500 GB SSD for testnet, or a 2 TB SSD for mainnet, with NVMe recommended and 100 Mbps+ download.

  • Docker Engine and Docker Compose v2 (Linux) or Docker Desktop (macOS, Windows)
  • Working L1 execution RPC and L1 beacon API endpoints
  • Enough free disk space for the node type you choose
  • 16GB+ RAM recommended

Install Docker on Ubuntu

The README includes an Ubuntu install sequence that adds Docker's official apt repository and installs the Docker engine and Compose plugin. If you are not logged in as root, log out and back in after adding yourself to the docker group, then check that Docker works.

sudo usermod -aG docker $(whoami) docker ps

Clone the repo and create your .env file

Clone the repository and copy the environment template. For a first run, the README suggests ink-sepolia with a full node. Then edit .env to set your L1 endpoints and the healthcheck reference RPC.

NETWORK_NAME chooses ink-sepolia or ink-mainnet. NODE_TYPE=full restores the latest op-reth full snapshot and prunes old state, while NODE_TYPE=archive keeps all history. For mainnet, the README says to switch the healthcheck reference RPC to https://rpc-gel.inkonchain.com.

  • OP_NODE__RPC_ENDPOINT: your Sepolia execution RPC
  • OP_NODE__L1_BEACON: your Sepolia beacon API
  • OP_NODE__RPC_TYPE=basic is the right default for generic providers
  • Leave OVERRIDE_HOLOCENE and EXTENDED_ARG empty unless you know the flag is compatible
git clone https://github.com/inkonchain/node cd node cp .env.example .env # then edit .env: # NETWORK_NAME=ink-sepolia # NODE_TYPE=full # OP_NODE__RPC_ENDPOINT=<your Sepolia execution RPC> # OP_NODE__L1_BEACON=<your Sepolia beacon API> # OP_NODE__RPC_TYPE=basic # HEALTHCHECK__REFERENCE_RPC_PROVIDER=https://rpc-gel-sepolia.inkonchain.com

Start the stack with Docker Compose

Run the start command. It pulls service images, builds the local bedrock-init image, downloads and extracts the latest op-reth snapshot, creates a JWT, and starts the services. The snapshot is hundreds of GB, so the first start can take a long time.

If the stack looks stuck, check the bedrock-init logs first, because op-reth and op-node wait for it to create /shared/initialized.txt.

  • bedrock-init (one-time init)
  • op-reth (execution client)
  • op-node
  • healthcheck
  • prometheus
  • grafana
docker compose up -d --build

Check that the node is starting correctly

Run docker compose ps to see running services. bedrock-init exits after setup and usually drops out of the default output. Use docker compose ps -a to confirm it exited with code 0.

Then check the logs. Good signals include op-reth printing RPC HTTP server started and op-node printing Rollup node started. The README also gives curl smoke tests for the execution RPC on port 9993 and the rollup node RPC on port 9545.

  • bedrock-init: Creating JWT... and Creating Bedrock flag...
  • op-reth: RPC HTTP server started
  • op-node: Rollup node started
docker compose ps docker compose logs --tail 50 bedrock-init op-reth op-node curl -fsS -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}' http://127.0.0.1:9993

Confirm the node is syncing

The best early signal that the rollup node is moving forward is optimism_syncStatus. Look for current_l1 advancing toward head_l1. Right after a snapshot restore, unsafe_l2 and eth_blockNumber stay at the snapshot height until derivation produces new blocks, so that is normal.

The healthcheck service exposes metrics on port 7300. Grafana is at http://localhost:3000 with username admin and the preloaded Simple Node Dashboard.

  • Look for current_l1 advancing toward head_l1
  • Check healthcheck_height metrics on port 7300
  • Open Grafana at http://localhost:3000
curl -fsS -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"optimism_syncStatus","params":[],"id":1}' http://127.0.0.1:9545

Stop, restart, upgrade or wipe the node

docker compose down stops the stack without removing data volumes. docker compose restart restarts it. To upgrade, pull the repo and images, then rebuild. docker compose down -v removes all local chain and monitoring data, so only use it when you want a clean start.

docker compose down docker compose restart git pull docker compose pull docker compose up -d --build docker compose down -v

What people use it for

  • Run an Ink Sepolia testnet node to test applications before deploying
  • Expose a local Ink RPC endpoint for development and experiments
  • Operate Ink Mainnet infrastructure with Docker Compose and monitoring dashboards
  • Watch node health and sync progress in the preloaded Grafana dashboard

Frequently asked questions

Is Ink Node free to use?

The repository is licensed under MIT, so you can use it under those terms. Running it still requires your own hardware, disk space, and L1 RPC endpoints, which the README says must be working and not free public endpoints.

What hardware do I need to run an Ink node?

The README recommends 16GB+ RAM, a 500 GB SSD for testnet, and a 2 TB SSD for mainnet, with NVMe recommended and 100 Mbps+ download. Disk needs depend on whether you choose a full or archive node.

Can I use a free public Ethereum RPC endpoint?

The README says free public endpoints are not enough for the L1 connection. The L1 RPC must serve receipts for blocks up to about a week old and have high rate limits.

What is the difference between full and archive node types?

NODE_TYPE=full restores the latest op-reth full snapshot and prunes old state. NODE_TYPE=archive restores the latest archive snapshot and keeps all history.

Why is my node stuck at startup?

The first start can take a long time because the snapshot is hundreds of GB. op-reth and op-node wait for bedrock-init to create /shared/initialized.txt, so check the bedrock-init logs first.

How does Ink Node compare to simple-optimism-node?

Ink Node is forked and customized from smartcontracts/simple-optimism-node and adds Ink-specific setup, including Ink Sepolia and Ink Mainnet support. The source does not give a detailed feature comparison beyond this.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Ink Node suits developers and operators who are comfortable with Docker, terminal commands and L1 RPC endpoints, and who want a testnet or mainnet Ink node. If you have no Docker experience, limited hardware or disk, or only a free public Ethereum RPC, pick a lighter option or a hosted RPC instead.

Install options & downloads