Run a Local Explorer Instance

Run a full OpenScan.AI explorer on your laptop in a few minutes — perfect for development and demos.

A local instance gives you a private explorer UI and API for a devnet (Anvil, Hardhat) or any testnet, so you can inspect transactions, test contract verification, and prototype integrations without touching public infrastructure.

Prerequisites

  • Docker 24+ with Docker Compose
  • 8 GB RAM available to Docker
  • A chain to index: a local devnet or any reachable RPC endpoint

Step 1: Start a local devnet (optional)

If you don’t have a chain handy, start Anvil (from Foundry):

Terminal window
anvil --chain-id 31337

Anvil exposes JSON-RPC on http://127.0.0.1:8545 with trace support — everything the indexer needs.

Step 2: Start the explorer stack

Terminal window
git clone https://github.com/OpenScanAI/blockscout.git
cd blockscout/docker-compose
cp envs/common-blockscout.env.example envs/common-blockscout.env

Point the stack at your chain in envs/common-blockscout.env:

Terminal window
ETHEREUM_JSONRPC_HTTP_URL=http://host.docker.internal:8545
ETHEREUM_JSONRPC_TRACE_URL=http://host.docker.internal:8545
CHAIN_ID=31337
COIN=ETH
NETWORK="Local Devnet"
SUBNETWORK="Anvil"

host.docker.internal lets containers reach services on your host machine (it works on Docker Desktop for macOS and Windows; on Linux, add extra_hosts: ["host.docker.internal:host-gateway"] or use the host’s LAN IP).

Launch:

Terminal window
docker compose up -d
docker compose logs -f backend

Step 3: Watch it index

Within seconds, the backend starts importing blocks. Verify:

Terminal window
curl http://localhost:4000/api/v2/main-page/indexing-status
curl http://localhost:4000/api/v2/stats

Open the UI at http://localhost — blocks, transactions, and addresses appear as they’re indexed.

Step 4: Exercise it

Deploy a contract to your devnet and watch it show up:

Terminal window
# With Foundry, against the local devnet
forge create src/MyToken.sol:MyToken \
  --rpc-url http://127.0.0.1:8545 \
  --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80

Then try the full local workflow:

  1. Find the contract address on http://localhost.
  2. Verify it via the Verify & publish form (or forge verify-contract --verifier blockscout --verifier-url http://localhost:4000/api ...).
  3. Read and write the contract from the Contract tab.
  4. Query it via the local API: curl http://localhost:4000/api/v2/smart-contracts/<address>.

This is the fastest loop for testing verification settings before verifying on a public network.

Step 5: Reset when the chain resets

Devnets restart from empty state. Reset the explorer’s database to match:

Terminal window
docker compose down -v
docker compose up -d

Pointing at a testnet instead

Swap the env values for a public testnet RPC (e.g. XDC Apothem: https://rpc.apothem.network, CHAIN_ID=51, COIN=TXDC) and recreate the stack. Historical sync takes longer; bound the range with FIRST_BLOCK if you only need recent activity.

Troubleshooting

  • No blocks indexing — the container can’t reach your RPC. Confirm curl http://host.docker.internal:8545 works from inside a container, or use the host LAN IP.
  • UI loads but shows nothing — indexing still in progress; check the indexing-status endpoint.
  • Reset didn’t clear data — you skipped -v; the named volume persists without it.

Next steps

Edit page on github
Alerts & Webhooks API Integration