> ## Documentation Index
> Fetch the complete documentation index at: https://docs.optimism.io/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` |

`kona-node` does not run a supervisor RPC server: the binary has no `--supervisor.*`
flag group. Its only interop flag, `--interop.dependency-set`
(`KONA_NODE_INTEROP_DEPENDENCY_SET`), takes a path to a dependency-set JSON file
rather than a port.

`--conductor.rpc` (`KONA_NODE_CONDUCTOR_RPC`) is not a listening port either. It is
the RPC endpoint URL of an external conductor service that the node dials out to,
and it has no default value. Supplying it enables the conductor integration when the
node runs in sequencer mode (`--mode sequencer`); in validator mode it has no effect.

## Core Node Arguments

| Flag                                            | Env                                           | Description                                                                 | Required | Default     |
| ----------------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------- | -------- | ----------- |
| `--mode <validator/sequencer>`                  | `KONA_NODE_MODE`                              | Mode of operation for the node                                              | No       | `validator` |
| `--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.rpc <URL>`             | `KONA_NODE_CONDUCTOR_RPC`          | RPC endpoint URL of an external conductor service. Supplying it enables the conductor integration in sequencer mode; it has no effect in validator mode. | -       |
| `--conductor.rpc.timeout <SECONDS>` | `KONA_NODE_CONDUCTOR_RPC_TIMEOUT`  | Conductor service RPC timeout                                                                                                                            | `1`     |

## Interop Arguments

| Flag                              | Env                                | Description                                                                                                                                | Default |
| --------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| `--interop.dependency-set <PATH>` | `KONA_NODE_INTEROP_DEPENDENCY_SET` | Path to the JSON file describing the interop dependency set for this chain. Required when the rollup config schedules the Lagoon hardfork. | -       |

`kona-node` does not run a supervisor RPC server, so there is no `--supervisor.*`
flag group. `--interop.dependency-set` is the node's only interop flag.

## 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](/node-operators/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