Quick Start (Docker)

Get the Optimum Gateway running with Docker.

Running on Kubernetes? See Kubernetes (Helm) for the official Helm chart.

Prerequisites: Requirements and Network Requirements. You also need a credential: an API key (see Generate your API key below), or for a fleet, one org join key (see Gateway Self-Enrollment).

Hardware Requirements

Minimum: 2+ vCPUs, 512MB RAM, 500MB+ disk
Recommended: 4+ vCPUs

Generate your API key

Every gateway authenticates with a credential. This section covers the API key path; fleets can use a join key instead, via Gateway Self-Enrollment. The key binds your gateway's identity, chain, operator, and validator scope — everything the gateway needs comes from this key, so there is no per-network YAML to edit.

Access is invite-only. You cannot self-register. The Optimum team must onboard you first. Anyone not invited cannot create an account or generate a key.

Get invited. The Optimum team adds you as an operator. You receive a "Welcome to Optimum" email invite to the Partner Console.
Sign in. Open the console and sign in with the same email the invite was sent to, using your Google or Microsoft account — no password.
Select your network. Use the Network picker in the header (Ethereum, Hoodi, or Mock Chain). It defaults to Ethereum, and the key takes its chain from whatever is selected here — the generate dialog is titled for that network, with no chain field of its own.
Open Manage Gateways. In the sidebar go to Manage Gateways, then select the Gateway tab.

Generate one key

Generate a key. Click GENERATE KEY and fill in:
- Clusters — tick every cluster this key may join. At least one is required on any network that has clusters, and generation is refused without it.
- Gateway details (optional) — pick from the dropdowns where available: Region, Consensus client, Hosting provider, DVT. These label the gateway in monitoring.
The modal confirms the new key is provisioned as a partner gateway, and names it automatically. There is no name field, and the name cannot be changed afterwards.
Copy the key. The key (format ogw_live_...) is shown only once. Copy and store it securely. If you lose it, generate a new one and revoke the old.

Bulk generate many keys

Running a fleet? You do not need one key per host at all. Mint a single org join key and let each gateway enroll itself on first boot — see Gateway Self-Enrollment. Bulk generation below remains supported for operators who prefer one key per gateway.

Use BULK GENERATE when you need many gateway keys at once (for example a large fleet rollout). Each key is still one per gateway — bulk create saves clicking GENERATE KEY repeatedly.

Select your network and open Manage Gateways. Same as above: header Network picker, then sidebar Manage Gateways -> Gateway tab.
Start bulk generate. Click BULK GENERATE.
Choose how many. Enter a count in How many keys, which is prefilled with 10. Your operator quota is shown above it (for example 0 of 1000 used · 1000 remaining).
Clusters and gateway details. Clusters is required on any network that has them. Region, Consensus client, Hosting provider, and DVT are optional. All of them apply to every key in the batch — the same fields as single-key generation. Keys are auto-named; you do not enter a label per key.
Download your keys. When creation finishes, download the batch as CSV or JSON. Raw keys (ogw_live_...) are shown only once — store the file securely before closing the dialog. Keep the browser tab open until creation finishes; that is when the secrets are at risk, and the dialog warns you if you try to close it without downloading.
Deploy one key per host. Map each key to a gateway instance and set OPT_API_KEY on that host. Do not reuse a key across gateways.

All-or-nothing. If any key in a batch fails to create, the whole batch is rolled back — none of the keys are kept. Fix the issue (for example quota) and try again.

One API key per gateway. Each gateway instance needs its own key. Do not share a key across gateways — the gateway registers a single identity per key, and reuse causes registration conflicts. If you run multiple gateways (e.g. Hoodi + Mainnet, or several hosts), generate a separate key for each — use BULK GENERATE for large rollouts, or switch to Gateway Self-Enrollment.

The gateway exchanges this key on startup at auth.getoptimum.io/api/v1/auth/token for a short-lived JWT that carries your gateway_id, chain, and validator scope.

Installation

docker pull getoptimum/gateway:v1.3.2

Configuration

Create config/app_conf.yml:

yaml

log_level: info
gateway_cluster_id: optimum_ethereum_hoodi_v0_1   # assigned by Optimum during onboarding

agent_lib_p2p_port: 33212
agent_mump2p_port: 33213
telemetry_enable: true
telemetry_port: 48123
identity_libp2p_dir: /tmp/libp2p
identity_mump2p_dir: /tmp/mump2p

Set your API key via the environment, not YAML. Pass it as OPT_API_KEY so it never lives in a config file or image layer. Your gateway_id, chain, and validator scope are all derived from this key — do not set them in YAML.

export OPT_API_KEY=ogw_live_xxx

Run

mkdir -p config data/libp2p data/mump2p

docker run --name optimum-gateway --rm \
  -p 33212:33212/tcp \
  -p 33213:33213/tcp \
  -p 127.0.0.1:48123:48123/tcp \
  -e OPT_API_KEY=$OPT_API_KEY \
  -v $(pwd)/config:/app/config \
  -v $(pwd)/data/libp2p:/tmp/libp2p \
  -v $(pwd)/data/mump2p:/tmp/mump2p \
  getoptimum/gateway:v1.3.2 \
  -config=/app/config/app_conf.yml

Persist the identity volumes (/tmp/libp2p, /tmp/mump2p) across restarts — otherwise the gateway's peer ID changes on every run and your CL client config breaks.

Verify

Health check:

curl http://localhost:48123/health

json

{
  "status": "healthy",
  "gateway_id": "optimum-dev-hoodi-kubernetes-validator-lighthouse",
  "version": "v1.3.2",
  "commit_hash": "a0b2bc1",
  "uptime_seconds": 1639,
  "checks": {
    "cl_peers": {"status": "ok", "value": 1},
    "mump2p_peers": {"status": "ok", "value": 13},
    "subscribed_topics": {"status": "ok", "value": 65},
    "last_block_age_sec": {"status": "ok", "value": 1},
    "cl_health": {"status": "ok"},
    "mump2p_health": {"status": "ok"}
  }
}

For a lightweight liveness probe (process + HTTP up), use the root endpoint:

curl http://localhost:48123/

json

{"status":"ok"}

Metrics with your gateway_id:

curl http://localhost:48123/metrics | grep gateway_id

text

mump2p_gateway_app_build_info{commit="a0b2bc1",gateway_id="your-gateway-id",paired_with="partner",...} 1
mump2p_gateway_mump2p_peers{gateway_id="your-gateway-id"} 13
...

Startup logs (fork digest, topics):

docker logs optimum-gateway

text

{"msg":"initialized fork digest from chain default","fork_digest":"c6ecb76c","chain":"hoodi"}
{"msg":"fork digest updated from bootstrap","fork_digest":"c6ecb76c"}
{"msg":"subscribed to topic","topic":"/eth2/c6ecb76c/beacon_block/ssz_snappy"}
{"msg":"subscribed to topic","topic":"/eth2/c6ecb76c/beacon_attestation_0/ssz_snappy"}
...

Note: "Failed to connect to bootstrap" during startup is normal. See Troubleshooting.

Connect CL Client

Get gateway peer info:

curl -s http://localhost:48123/api/v1/self_info

Use libp2p.multiaddrs[0] (or another reachable multiaddr) for IP and peer_id for peer ID.

Recommended CL versions: Use Prysm v7.1.8 or later. For Teku use v26.6.0+ (minimum v26.4.0). See Troubleshooting for client-specific PeerDAS flags.

Prysm

./beacon-chain \
  --peer=/ip4/YOUR_GATEWAY_IP/tcp/33212/p2p/YOUR_GATEWAY_PEER_ID \
  ...

Teku

teku \
  --p2p-direct-peers=/ip4/YOUR_GATEWAY_IP/tcp/33212/p2p/YOUR_GATEWAY_PEER_ID \
  --p2p-static-peers=/ip4/YOUR_GATEWAY_IP/tcp/33212/p2p/YOUR_GATEWAY_PEER_ID \
  ...

Use --p2p-direct-peers (not just --p2p-static-peers) — static peers can be pruned. See Troubleshooting - Teku PeerDAS for details.

Lighthouse

Add your Lighthouse node as a direct peer in the gateway config so the gateway auto-reconnects after restarts:

yaml

direct_cl_peers:
  - /ip4/YOUR_LIGHTHOUSE_IP/tcp/9000/p2p/YOUR_LIGHTHOUSE_PEER_ID

See Troubleshooting - Lighthouse v8.x for additional required flags.

Nimbus

Point Nimbus at the gateway (multiaddr or ENR; multiaddr is typical):

nimbus_beacon_node \
  --direct-peer=/ip4/YOUR_GATEWAY_IP/tcp/33212/p2p/YOUR_GATEWAY_PEER_ID \
  --netkey-file=/data/netkey \
  ...

Add your Nimbus node in the gateway config so the gateway reconnects after restarts:

yaml

direct_cl_peers:
  - /ip4/YOUR_NIMBUS_IP/tcp/YOUR_NIMBUS_P2P_PORT/p2p/YOUR_NIMBUS_PEER_ID

Use a stable --netkey-file (not random) — Nimbus requires it for privileged direct peers. Nimbus drop/reconnect cycles during warmup are normal; see Troubleshooting - Nimbus for verification and expected behavior.

Lodestar

Lodestar is supported. Point it at the gateway as a trusted/direct peer and add the Lodestar node to the gateway's direct_cl_peers so the gateway re-dials after restarts.

Fleet rollout?

If you run many gateways, you do not need one API key per host. Mint a single org join key (ojk_) and let each gateway self-enroll on first boot. See Gateway Self-Enrollment.

Next Steps

Configuration - Ports, direct peers, advanced settings
Gateway Self-Enrollment - Fleet rollout with a join key
Consumer Block Stream - Opt-in WebSocket / gRPC feed of decoded blocks
Troubleshooting - Gateway diagnosis and common issues
Metrics - Gateway and mesh metrics

Quick Start (Docker) ​

Hardware Requirements ​

Generate your API key ​

Generate one key ​

Bulk generate many keys ​

Installation ​

Configuration ​

Run ​

Verify ​

Connect CL Client ​

Prysm ​

Teku ​

Lighthouse ​

Nimbus ​

Lodestar ​

Fleet rollout? ​

Next Steps ​

Quick Start (Docker)

Hardware Requirements

Generate your API key

Generate one key

Bulk generate many keys

Installation

Configuration

Run

Verify

Connect CL Client

Prysm

Teku

Lighthouse

Nimbus

Lodestar

Fleet rollout?

Next Steps