> ## Documentation Index
> Fetch the complete documentation index at: https://optimism-373f39ad-soyboy-docs-op-supernode-guide.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Kona Node CLI Reference

> Reference for all kona-node CLI flags and environment variables, grouped by category, plus default ports and default runtime behavior.

This document lists all CLI flags for the `kona-node node` subcommand, grouped by category. All flags can be provided as command-line arguments or via environment variables.

<Note>
  For more details on each flag, see the inline help (`kona-node node --help`) or the source code.
</Note>

## Default Ports

| Service        | Default Port | Flag/Env                                             |
| -------------- | ------------ | ---------------------------------------------------- |
| RPC HTTP       | 9545         | `--port` / `KONA_NODE_RPC_PORT`                      |
| RPC WebSocket  | 9545         | (same as HTTP, enabled with `--rpc.ws-enabled`)      |
| P2P TCP        | 9222         | `--p2p.listen.tcp` / `KONA_NODE_P2P_LISTEN_TCP_PORT` |
| P2P UDP        | 9223         | `--p2p.listen.udp` / `KONA_NODE_P2P_LISTEN_UDP_PORT` |
| Supervisor RPC | 9333         | `--supervisor.port` / `KONA_NODE_SEQUENCER_PORT`     |
| Conductor RPC  | 8547         | `--conductor.rpc` / `KONA_NODE_CONDUCTOR_RPC`        |

## Core Node Arguments

| Flag                                            | Env                                           | Description                                                                 | Required | Default    |
| ----------------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------- | -------- | ---------- |
| `--mode <verifier/sequencer>`                   | `KONA_NODE_MODE`                              | Mode of operation for the node                                              | Yes      | `verifier` |
| `--l1-eth-rpc <URL>`                            | `KONA_NODE_L1_ETH_RPC`                        | URL of the L1 execution client RPC API                                      | Yes      | -          |
| `--l1-trust-rpc <true/false>`                   | `KONA_NODE_L1_TRUST_RPC`                      | Whether to trust the L1 RPC without verification                            | No       | `true`     |
| `--l1-beacon <URL>`                             | `KONA_NODE_L1_BEACON`                         | URL of the L1 beacon API                                                    | Yes      | -          |
| `--l2-engine-rpc <URL>`                         | `KONA_NODE_L2_ENGINE_RPC`                     | URL of the engine API endpoint of an L2 execution client                    | Yes      | -          |
| `--l2-trust-rpc <true/false>`                   | `KONA_NODE_L2_TRUST_RPC`                      | Whether to trust the L2 RPC without verification                            | No       | `true`     |
| `--l2-engine-jwt-secret <PATH>`                 | `KONA_NODE_L2_ENGINE_AUTH`                    | Path to file containing the hex-encoded JWT secret for the execution client | No       | -          |
| `--l2-config-file <PATH>`                       | `KONA_NODE_ROLLUP_CONFIG`                     | Path to a custom L2 rollup configuration file                               | No       | -          |
| `--l1-runtime-config-reload-interval <SECONDS>` | `KONA_NODE_L1_RUNTIME_CONFIG_RELOAD_INTERVAL` | Poll interval for reloading runtime config                                  | No       | `600`      |

## Global Arguments

| Flag                                        | Env                     | Description                                  | Required | Default         |
| ------------------------------------------- | ----------------------- | -------------------------------------------- | -------- | --------------- |
| `--l2-chain-id <ID/NAME>` or `-c <ID/NAME>` | `KONA_NODE_L2_CHAIN_ID` | L2 chain ID (numeric) or chain name (string) | No       | `10` (Optimism) |

### Chain ID Support

The `--l2-chain-id` flag supports flexible chain identification using the `alloy_chains` crate:

**Numeric Chain IDs:**

```bash theme={null}
kona-node --l2-chain-id 10 node [args...]      # Optimism mainnet
kona-node --l2-chain-id 8453 node [args...]    # Base mainnet
kona-node --l2-chain-id 1 node [args...]       # Ethereum mainnet
```

**String Chain Names:**

```bash theme={null}
kona-node --l2-chain-id optimism node [args...]
kona-node --l2-chain-id base node [args...]
kona-node --l2-chain-id mainnet node [args...]
```

**Short Flag and Environment Variable:**

```bash theme={null}
kona-node -c optimism node [args...]
export KONA_NODE_L2_CHAIN_ID=optimism && kona-node node [args...]
```

Supported chain names include all those recognized by `alloy_chains` (e.g., `optimism`, `base`, `mainnet`). Unknown numeric chain IDs are accepted for custom networks.

## P2P Arguments

| Flag                                  | Env                                  | Description                                         | Default   |
| ------------------------------------- | ------------------------------------ | --------------------------------------------------- | --------- |
| `--p2p.no-discovery`                  | `KONA_NODE_P2P_NO_DISCOVERY`         | Disable Discv5 (node discovery)                     | `false`   |
| `--p2p.priv.path <PATH>`              | `KONA_NODE_P2P_PRIV_PATH`            | Path to hex-encoded 32-byte private key for peer ID | -         |
| `--p2p.priv.raw <HEX>`                | `KONA_NODE_P2P_PRIV_RAW`             | Hex-encoded 32-byte private key for peer ID         | -         |
| `--p2p.advertise.ip <IP>`             | `KONA_NODE_P2P_ADVERTISE_IP`         | IP to advertise to external peers                   | -         |
| `--p2p.advertise.tcp <PORT>`          | `KONA_NODE_P2P_ADVERTISE_TCP_PORT`   | TCP port to advertise                               | `0`       |
| `--p2p.advertise.udp <PORT>`          | `KONA_NODE_P2P_ADVERTISE_UDP_PORT`   | UDP port to advertise                               | `0`       |
| `--p2p.listen.ip <IP>`                | `KONA_NODE_P2P_LISTEN_IP`            | IP to bind LibP2P/Discv5 to                         | `0.0.0.0` |
| `--p2p.listen.tcp <PORT>`             | `KONA_NODE_P2P_LISTEN_TCP_PORT`      | TCP port to bind LibP2P to                          | `9222`    |
| `--p2p.listen.udp <PORT>`             | `KONA_NODE_P2P_LISTEN_UDP_PORT`      | UDP port to bind Discv5 to                          | `9223`    |
| `--p2p.peers.lo <N>`                  | `KONA_NODE_P2P_PEERS_LO`             | Low-tide peer count                                 | `20`      |
| `--p2p.peers.hi <N>`                  | `KONA_NODE_P2P_PEERS_HI`             | High-tide peer count                                | `30`      |
| `--p2p.peers.grace <SECONDS>`         | `KONA_NODE_P2P_PEERS_GRACE`          | Grace period for new peers                          | `30`      |
| `--p2p.gossip.mesh.d <N>`             | `KONA_NODE_P2P_GOSSIP_MESH_D`        | GossipSub mesh target count                         | `8`       |
| `--p2p.gossip.mesh.lo <N>`            | `KONA_NODE_P2P_GOSSIP_MESH_DLO`      | GossipSub mesh low watermark                        | `6`       |
| `--p2p.gossip.mesh.dhi <N>`           | `KONA_NODE_P2P_GOSSIP_MESH_DHI`      | GossipSub mesh high watermark                       | `12`      |
| `--p2p.gossip.mesh.dlazy <N>`         | `KONA_NODE_P2P_GOSSIP_MESH_DLAZY`    | GossipSub gossip target                             | `6`       |
| `--p2p.gossip.mesh.floodpublish`      | `KONA_NODE_P2P_GOSSIP_FLOOD_PUBLISH` | Publish to all known peers                          | `false`   |
| `--p2p.scoring <none or light>`       | `KONA_NODE_P2P_SCORING`              | Peer scoring strategy                               | `light`   |
| `--p2p.ban.peers`                     | `KONA_NODE_P2P_BAN_PEERS`            | Enable peer banning                                 | `false`   |
| `--p2p.ban.threshold <N>`             | `KONA_NODE_P2P_BAN_THRESHOLD`        | Ban threshold                                       | `-100`    |
| `--p2p.ban.duration <MINUTES>`        | `KONA_NODE_P2P_BAN_DURATION`         | Ban duration                                        | `60`      |
| `--p2p.discovery.interval <SECONDS>`  | `KONA_NODE_P2P_DISCOVERY_INTERVAL`   | Peer discovery interval                             | `5`       |
| `--p2p.bootstore <PATH>`              | `KONA_NODE_P2P_BOOTSTORE`            | Directory to store the bootstore                    | -         |
| `--p2p.redial <N>`                    | `KONA_NODE_P2P_REDIAL`               | Peer redialing threshold                            | `500`     |
| `--p2p.redial.period <MINUTES>`       | `KONA_NODE_P2P_REDIAL_PERIOD`        | Peer dial period                                    | `60`      |
| `--p2p.bootnodes <ENR,...>`           | `KONA_NODE_P2P_BOOTNODES`            | List of bootnode ENRs                               | -         |
| `--p2p.topic-scoring`                 | `KONA_NODE_P2P_TOPIC_SCORING`        | Enable topic scoring                                | `false`   |
| `--p2p.discovery.randomize <SECONDS>` | `KONA_NODE_P2P_DISCOVERY_RANDOMIZE`  | Remove random peers from discovery                  | -         |

## RPC Arguments

| Flag                       | Env                          | Description                           | Default   |
| -------------------------- | ---------------------------- | ------------------------------------- | --------- |
| `--rpc.disabled`           | `KONA_NODE_RPC_DISABLED`     | Disable the RPC server                | `false`   |
| `--rpc.no-restart`         | `KONA_NODE_RPC_NO_RESTART`   | Prevent RPC server from restarting    | `false`   |
| `--rpc.addr <IP>`          | `KONA_NODE_RPC_ADDR`         | RPC listening address                 | `0.0.0.0` |
| `--port <PORT>`            | `KONA_NODE_RPC_PORT`         | RPC listening port                    | `9545`    |
| `--rpc.enable-admin`       | `KONA_NODE_RPC_ENABLE_ADMIN` | Enable the admin API                  | `false`   |
| `--rpc.admin-state <PATH>` | `KONA_NODE_RPC_ADMIN_STATE`  | File path for admin state persistence | -         |
| `--rpc.ws-enabled`         | `KONA_NODE_RPC_WS_ENABLED`   | Enable websocket RPC server           | `false`   |

## Sequencer Arguments

| Flag                                | Env                                | Description                                                | Default          |
| ----------------------------------- | ---------------------------------- | ---------------------------------------------------------- | ---------------- |
| `--sequencer.stopped`               | `KONA_NODE_SEQUENCER_STOPPED`      | Start sequencer in stopped state                           | `false`          |
| `--sequencer.max-safe-lag <N>`      | `KONA_NODE_SEQUENCER_MAX_SAFE_LAG` | Max L2 safe/unsafe lag                                     | `0`              |
| `--sequencer.l1-confs <N>`          | `KONA_NODE_SEQUENCER_L1_CONFS`     | L1 block confirmations for sequencer                       | `4`              |
| `--sequencer.recover`               | `KONA_NODE_SEQUENCER_RECOVER`      | Strictly prepare next L1 origin and create empty L2 blocks | `false`          |
| `--conductor.enabled`               | `KONA_NODE_CONDUCTOR_ENABLED`      | Enable the conductor service                               | `false`          |
| `--conductor.rpc <ADDR>`            | `KONA_NODE_CONDUCTOR_RPC`          | Conductor service RPC endpoint                             | `127.0.0.1:8547` |
| `--conductor.rpc.timeout <SECONDS>` | `KONA_NODE_CONDUCTOR_RPC_TIMEOUT`  | Conductor service RPC timeout                              | `1`              |

## Supervisor Arguments

| Flag                                  | Env                                    | Description                                        | Default   |
| ------------------------------------- | -------------------------------------- | -------------------------------------------------- | --------- |
| `--supervisor.rpc-enabled`            | `KONA_NODE_SUPERVISOR_RPC_ENABLED`     | Enable Supervisor Websocket                        | `false`   |
| `--supervisor.ip.address <IP>`        | `KONA_NODE_SUPERVISOR_IP`              | IP to bind Supervisor Websocket RPC server         | `0.0.0.0` |
| `--supervisor.port <PORT>`            | `KONA_NODE_SUPERVISOR_PORT`            | TCP port for supervisor RPC                        | `9333`    |
| `--supervisor.jwt.secret <HEX>`       | `KONA_NODE_SUPERVISOR_JWT_SECRET`      | JWT secret for supervisor websocket authentication | -         |
| `--supervisor.jwt.secret.file <PATH>` | `KONA_NODE_SUPERVISOR_JWT_SECRET_FILE` | Path to file containing JWT secret                 | -         |

## RPC Trust Flags

The `--l1-trust-rpc` and `--l2-trust-rpc` flags control whether Kona verifies the block hashes of RPC responses. For guidance on when to disable trust and worked examples for trusted, untrusted, and mixed provider setups, see [configure RPC trust](/rust/kona/node/run/rpc-trust).

## Default Behavior

Unless overridden by the flags above, a `kona-node node` run has the following defaults:

* The P2P stack is spun up. The libp2p swarm listens on TCP `9222`
  to receive block gossip. The `discv5` discovery service runs on
  UDP port `9223`. Peer scoring is enabled.
* An RPC server is exposed at `0.0.0.0:9545`. Websocket connections
  are disabled by default.
* Prometheus metrics are disabled. Enable them with the
  `--metrics.enabled` flag; metrics are then served on `0.0.0.0:9090`,
  configurable via the `--metrics.port` and `--metrics.addr` flags.

## Rollup Configuration Loading

If a file path to a rollup config is *not* specified via the
`--l2-config-file` cli flag, the Rollup Config will be loaded
via the [superchain registry][scr].

A custom rollup config can either be specified through the
`--l2-config-file` flag, or specific values may be overridden
using a set of override flags provided by the `kona-node`.

Override flags (for example `--canyon-override`) can be viewed
in the help menu by running `kona-node node --help`. The only
overrides currently supported are hardfork timestamps in seconds.

[scr]: https://github.com/ethereum-optimism/superchain-registry/tree/main