---
title: "CLI Reference"
sidebar_position: 7
description: "Complete CLI flag reference for Erigon — all startup options, environment variables, and configuration settings."
---


# CLI Reference

The Erigon CLI has a wide range of flags that can be used to customize its behavior. There are 3 ways to configure Erigon, listed by priority:

* [Command line options](/fundamentals/configuring-erigon/#command-line-options) (flags)
* [Configuration file](/fundamentals/configuring-erigon/#configuration-file)
* [Environment variables](/fundamentals/configuring-erigon/#environment-variables)

:::tip
In order to see all the available options (flags) you must run the command:

```bash
./build/bin/erigon --help
```
:::

## Command line options

Flags are passed directly to the `erigon` binary at startup. Each flag starts with `--`, followed by the flag name and, where applicable, a value separated by a space or `=`. For example, to start Erigon on the Holesky testnet with a custom data directory and the JSON-RPC API enabled on port 8545:

```bash
./build/bin/erigon --chain=holesky --datadir=/data/erigon --http --http.port=8545
```

Flags can be combined freely, providing a high degree of customization. Here's a breakdown of the most important flags:

### General Options

These flags cover the general behavior and configuration of the Erigon client.

* `--datadir value`: Specifies the data directory for the databases.
  * Default: `/home/usr/.local/share/erigon`
* `--ethash.dagdir value`: Sets the directory to store the ethash mining DAGs.
  * Default: `/home/usr/.local/share/erigon-ethash`
* `--config value`: Sets Erigon flags using a YAML/TOML file.
* `--version, -v`: Prints the version information.
* `--help, -h`: Displays help information.
* `--chain value`: Sets the name of the [network](/fundamentals/supported-networks) to join.
  * Default: `mainnet`
* `--networkid value`: Explicitly sets the network ID.
  * Default: `1`
* `--identity value`: Sets a custom node name.
* `--externalcl`: Enables the external consensus layer.
  * Default: `false`, means that Caplin is enabled.
* `--override.osaka value`: Manually specifies the Osaka fork time.
  * Default: `0`
* `--override.amsterdam value`: Manually specifies the Amsterdam fork time.
  * Default: `0`
* `--vmdebug`: Records information for VM and contract debugging.
  * Default: `false`
* `--gdbme`: Restarts Erigon under gdb for debugging.
  * Default: `false`
* `--ethstats value`: The reporting URL for an ethstats service.
* `--trusted-setup-file value`: Absolute path to a `trusted_setup.json` file.
* `--prune.include-receipts, --persist.receipts, --experiment.persist.receipts.v2`: Downloads and caches historical receipts. Without it, receipts and logs are re-derived on demand from state history, so the related RPC calls still work, just with higher latency.
  * Default: `false` (disabled) in every prune mode
* `--keep.stored.chain.config`: Avoids overriding the chain configuration already stored in the database.
  * Default: `false`

### Development, testing, and block-production helpers

These flags are mainly for dev networks, testing, or specialized block-production setups.

* `--allow-insecure-unlock`: Accepted for go-ethereum CLI compatibility but currently has **no effect** — the flag is registered and settable, yet nothing in the codebase reads it and Erigon exposes no account-unlocking RPC.
  * Default: `false`
* `--dev-validator-seed value`: Deterministic BLS key seed for the embedded dev validator. Read only in PoS dev mode, which is selected by `--chain dev`; on any other chain the flag does nothing.
  * Default: `devnet`
* `--dev-validator-count value`: Number of validators for PoS dev mode (`--chain dev`).
  * Default: `64`
* `--dev.slot-time value`: Slot duration in seconds for PoS dev mode (`--chain dev`). Values below `2` are silently raised to `2`.
  * Default: `6`
* `--miner.gaslimit value`: Target gas limit for mined blocks.
  * Default: unset — the target falls back to the chain configuration's default block gas limit, or `60000000` where the chain config does not set one. An explicit `0` is ignored rather than applied as a zero limit, so the flag only takes effect when set to a positive value.
* `--miner.extradata value`: Block extra data set by the miner. Values longer than 32 bytes are silently truncated.
  * Default: the client version string
* `--experimental.bal`: Generates block access lists.
  * Default: `false`
* `--experimental.always-generate-changesets`: Overrides changeset generation logic.
  * Default: `false`, derived as the inverse of the `BATCH_COMMITMENTS` environment variable (itself `true` by default). Running with `BATCH_COMMITMENTS=false` therefore flips this default to `true` unless the flag is passed explicitly.
* `--chaos.monkey`: Testing-only flag that enables spontaneous network, consensus, and other failures.
  * Default: `false`

### Database and Caching

These flags control database performance and memory usage. See [Database](/fundamentals/database) for the on-disk layout.

* `--db.pagesize value`: Sets the fixed page size for the database.
  * Default: `16KB`
* `--db.size.limit value`: Sets a runtime limit on the chaindata database size.
  * Default: `1TB`
* `--db.writemap`: Enables `WRITE_MAP` for fast database writes.
  * Default: `true`
* `--db.read.concurrency value`: Maximum number of concurrent open database read transactions (the MDBX read-transaction semaphore); when it is full, extra readers wait for a slot by default, though some RPC paths (HTTP/WebSocket) fail fast with an overload response instead. Low values are fine for low read-concurrency nodes (for example, validators); raise it for nodes serving heavy parallel RPC.
  * Default: scales with the host as `min(max(10, GOMAXPROCS * 64), 9000)` — kept well above the CPU count because reads are I/O-bound, and capped below Go's roughly 10,000 OS-thread limit.
* `--database.verbosity value`: Enables internal database logs.
  * Default: `2`
* `--batchSize value`: Sets the batch size for the execution stage.
  * Default: `512M`
* `--etl.bufferSize value`: Buffer size for ETL operations. Also settable through the `ETL_OPTIMAL` environment variable.
  * Default: `256MB`
* `--bodies.cache value`: Sets the size limit for the block bodies cache.
  * Default: `268435456`
* `--state.cache value`: Sets the amount of data to store in the StateCache.
  * Default: `0MB`
* `--sync.parallel-state-flushing`: Enables parallel state flushing.
  * Default: `true`
* `--erigondb.domain.steps-in-frozen-file value`: Overrides the `steps_in_frozen_file` setting from `erigondb.toml` for the domain merge cap only (history and inverted-index merges are unaffected). Pass a positive integer to set an explicit cap, or `Inf` to leave the domain merge unbounded.
  * Default: unset (uses the value from `erigondb.toml`)
  * Use with care — an incorrect value may affect database structure.
* `--commitment.plainValues` *(New in v3.6)*: On the first start of a fresh datadir, write commitment values in plain form (no shortened key references). This is a one-time, per-datadir choice — it is ignored once `erigondb.toml` exists.
  * Default: `false`

### Pruning and Snapshots

Flags for managing how old chain data is handled and stored. See [Snapshots Management](/fundamentals/snapshots-management) for snapshot tooling and disk usage.

* `--prune.mode value`: Selects a pruning preset (`full`, `archive`, `minimal`, `blocks`). See also [Pruning Modes](/fundamentals/pruning-modes)
  * Default: `"full"`
* `--prune.distance value`: Keeps state history for the latest `N` blocks, or `keep-all` to keep everything.
  * Default: unset (retention follows `--prune.mode`)
* `--prune.distance.blocks value`: Keeps block history for the latest `N` blocks, or a named policy: `keep-post-merge` (prune pre-merge blocks only) or `keep-all` (keep every block).
  * Default: unset (retention follows `--prune.mode`)
* `--prune.include-commitment-history, --prune.experimental.include-commitment-history, --experimental.commitment-history`: Enables fast `eth_getProof` for executed blocks by storing commitment history. Requires +32 GB RAM. See [`eth_getProof`](/interacting-with-erigon/eth#eth_getproof).
  * Default: `false`
* `--prune.commitment-history.distance value`: Keeps commitment history for the latest `N` blocks, or `keep-all`. Empty or `0` (default) keeps everything. Requires `--prune.include-commitment-history`.
  * Default: unset (empty / `0`, keeps everything)
* `--prune.receipts.distance, --persist.receipts.distance value`: Keeps the receipt cache for the latest `N` blocks, or `keep-all`. Empty or `0` (default) follows the state-history window. Requires `--prune.include-receipts`.
  * Default: unset (empty / `0`, follows the state-history window)
* `--snap.skip-state-snapshot-download`: Skips state download and starts from genesis.
  * Default: `false`
* `--snap.keepblocks`: Workaround/debug — keeps ancient blocks in the DB instead of moving them into snapshots (useful for debugging).
  * Default: `false`
* `--snap.stop`: Workaround for snapshot-related bugs — stops producing new snapshot files (DB will grow as a result).
  * Default: `false`
* `--snap.state.stop`: Workaround for state-related bugs — stops producing new state files (DB will grow as a result).
  * Default: `false`
* `--snap.p2p-manifest` *(New in v3.5)* (experimental): Decentralized snapshot discovery — peers advertise their `chain.toml` manifest via ENR instead of the centralized `preverified.toml`. Opt-in; requires a compatible peer network.
  * Default: `false`
* `--snap.chaintoml-url value` *(New in v3.5)*: Fetch the preverified `chain.toml` directly from this URL instead of the default R2/GitHub CDN. Precedence: the `ERIGON_REMOTE_PREVERIFIED` environment variable (path to a local override file) wins over this URL and the default CDN; a local `preverified.toml` in the datadir also takes precedence — delete it to re-fetch from the URL.
  * Default: `""` (uses the built-in CDN)
* `--snap.download.to.block, --shadow.fork.block value`: Downloads snapshots only up to the given block number (exclusive). Intended for testing and shadow forks.
  * Default: `0` (disabled — downloads all available snapshots)

### Transaction Pool (TxPool)

Options for configuring the [transaction pool](/fundamentals/modules/txpool).

* `--txpool.api.addr value`: The TxPool API network address.
  * Default: Uses the value of `--private.api.addr`
* `--txpool.disable`: Disables the internal transaction pool.
  * Default: `false`
* `--txpool.pricelimit value`: Sets the minimum gas price for acceptance into the pool.
  * Default: `1`
* `--txpool.pricebump value`: Sets the price bump percentage to replace a transaction.
  * Default: `10`
* `--txpool.blobpricebump value`: Sets the price bump percentage for replacing a type-3 blob transaction.
  * Default: `100`
* `--txpool.accountslots value`: Sets the number of executable transaction slots per account.
  * Default: `16`
* `--txpool.blobslots value`: Sets the maximum number of blobs per account.
  * Default: `540`
* `--txpool.totalblobpoollimit value`: Sets the total limit on the number of all blobs in the pool.
  * Default: `5400`
* `--txpool.globalslots value`: Sets the maximum number of executable transaction slots for all accounts.
  * Default: `10000`
* `--txpool.globalbasefeeslots value`: Sets the maximum number of non-executable transactions with insufficient base fees.
  * Default: `30000`
* `--txpool.globalqueue value`: Sets the maximum number of non-executable transaction slots for all accounts.
  * Default: `30000`
* `--txpool.trace.senders value`: A comma-separated list of addresses whose transactions will be traced.
* `--txpool.commit.every value`: Sets how often transactions are committed to storage.
  * Default: `15s`
* `--txpool.gossip.disable`: Disables P2P gossip of transactions.
  * Default: `false`
* `--txpool.queued.dormancy value`: Evicts queued transactions from senders with no on-chain state changes for at least this duration (e.g. `3h`, `2h30m`).
  * Default: `3h0m0s`
  * Set to `0` to disable dormancy-based eviction.

### Network and Peers

These flags manage network connectivity, peer discovery, and traffic control. See [Default Ports](/fundamentals/default-ports) for the full port map.

* `--port value`: The main network listening port.
  * Default: `30303`
* `--p2p.protocol value`: The version of the `eth` P2P protocol.
  * Default: `69`, `70`, `71`
* `--nat value`: The NAT port mapping mechanism (See [here](/fundamentals/nat) for more details).
* `--nodiscover`: Disables peer discovery.
  * Default: `false`
* `--discovery.v4`, `--discv4`: Enables the Node Discovery Protocol v4 (Discv4) for managed ENRs and topic discovery.
  * Default: `false` (disabled by default since v3.4; discv5 is now the default discovery protocol)
* `--discovery.v5`, `--discv5`, `--v5disc`: Enables the Node Discovery Protocol v5 (Discv5) for managed ENRs and topic discovery.
  * Default: `true` (enabled by default since v3.4)
* `--netrestrict value`: Restricts network communication to specific IP networks.
* `--nodekey value`: The P2P node key file.
* `--nodekeyhex value`: The P2P node key as a hexadecimal string.
* `--discovery.dns value`: Sets DNS discovery entry points.
* `--bootnodes value`: Comma-separated enode URLs for P2P discovery bootstrap.
* `--staticpeers value`: Comma-separated enode URLs to connect to.
* `--trustedpeers value`: Comma-separated enode URLs for trusted peers.
* `--maxpeers value`: The maximum number of network peers.
  * Default: `32`

### RPC & API

Flags for configuring various RPC servers and their behavior. See [Interacting with Erigon](/interacting-with-erigon) for the JSON-RPC API reference.

* `--private.api.addr value`: The internal gRPC API address for Erigon's components.
  * Default: `127.0.0.1:9090`
* `--private.api.ratelimit value`: Limits the number of simultaneous internal API requests.
  * Default: `31872`
* `--http`: Enables the JSON-RPC HTTP server.
  * Default: `true`
* `--http.enabled`: An alternative flag to enable the HTTP server.
  * Default: `true`
* `--graphql`: Enables the GraphQL endpoint.
  * Default: `false`
* `--http.addr value`: The HTTP-RPC server listening interface.
  * Default: `localhost`
* `--http.port value`: The HTTP-RPC server listening port.
  * Default: `8545`
* `--authrpc.addr value`: The HTTP-RPC server listening interface for the Engine API.
  * Default: `localhost`
* `--authrpc.port value`: The HTTP-RPC server listening port for the Engine API.
  * Default: `8551`
* `--authrpc.jwtsecret value`: The path to the [JWT secret](/fundamentals/jwt) file for the consensus layer.
* `--http.compression`: Enables compression over HTTP-RPC.
  * Default: `true`
* `--http.corsdomain value`: A comma-separated list of domains for cross-origin requests.
* `--http.vhosts value`: A comma-separated list of virtual hostnames.
  * Default: `localhost`
* `--authrpc.vhosts value`: A comma-separated list of virtual hostnames for the Engine API.
  * Default: `localhost`
* `--http.api value`: The APIs offered over the HTTP-RPC interface.
  * Default: `eth,erigon,engine`
* `--ws`: Enables the WS-RPC server.
  * Default: `false`
* `--ws.port value`: The WS-RPC server listening port.
  * Default: `8546`
* `--ws.compression`: Enables compression over WebSocket.
  * Default: `true`
* `--ws.max.connections value`: Maximum number of concurrent WebSocket connections.
  * Default: `0` (unlimited)
* `--rpc.batch.concurrency value`: Limits the number of goroutines for batch requests.
  * Default: `2`
* `--rpc.max.concurrency value`: Maximum number of concurrent HTTP RPC requests (HTTP admission control).
  * Default: `0` (inherits value from `--db.read.concurrency`)
  * Set to `-1` to disable admission control (unlimited)
* `--rpc.streaming.disable`: Disables JSON streaming for heavy endpoints.
  * Default: `false`
* `--state.stream.disable`: Disables streaming of state changes from the core to the RPC daemon.
  * Default: `false`
* `--rpc.accessList value`: Specifies a granular API allowlist.
* `--rpc.gascap value`: Sets a cap on gas usage for `eth_call`/`estimateGas`.
  * Default: `50000000`
* `--rpc.batch.limit value`: Sets the maximum number of requests in a batch.
  * Default: `100`
* `--rpc.blockrange.limit value`: Sets the maximum block range for `eth_getLogs` and similar range queries.
  * Default: `1000`
  * Applies to: `eth_getLogs`, `erigon_getLogs`
* `--rpc.logs.maxresults value`: Sets the maximum number of log results returned per query.
  * Default: `20000`
  * Applies to: `eth_getLogs`, `erigon_getLogs`, `erigon_getLatestLogs`
  * Set to `0` to remove the limit entirely (use with caution on large ranges).
  * Works in tandem with `--rpc.blockrange.limit`: both constraints apply independently — a query can be blocked by either limit.
* `--rpc.logs.querylimit value`: Maximum number of alternative addresses or topics allowed per search position in the `eth_getLogs` filter criteria.
  * Default: `1000`
  * Applies to: `eth_getLogs`
  * Set to `0` or a negative value for no limit.
* `--rpc.returndata.limit value`: Sets the maximum return data size for `eth_call`.
  * Default: `100000`
* `--rpc.allow-unprotected-txs`: Allows unprotected transactions via RPC.
  * Default: `false`
* `--rpc.gethcompat`: Enables Geth-compatible storage iteration order for `debug_storageRangeAt` (results sorted by keccak256 hash). Disabled by default for performance.
  * Default: `false`
* `--rpc.txfeecap value`: Sets a cap on transaction fees in ether.
  * Default: `1`
* `--rpc.slow value`: Logs RPC requests slower than the specified threshold.
  * Default: `0s`
* `--rpc.evmtimeout value`: The maximum time to wait for an EVM call.
  * Default: `5m0s`
* `--rpc.overlay.getlogstimeout value`: The maximum time to wait for `overlay_getLogs`.
  * Default: `5m0s`
* `--rpc.overlay.replayblocktimeout value`: The maximum time to wait to replay a single block.
  * Default: `10s`
* `--rpc.txsync.defaulttimeout value`: The default timeout for `eth_sendRawTransactionSync` when the caller does not specify one.
  * Default: `25s`
* `--rpc.txsync.maxtimeout value`: The maximum timeout for `eth_sendRawTransactionSync`; larger requested timeouts are clamped to this value.
  * Default: `1m0s`
* `--rpc.subscription.filters.maxlogs value`: Maximum logs to store per subscription.
  * Default: `10000`
* `--rpc.subscription.filters.maxheaders value`: Maximum block headers to store per subscription.
  * Default: `10000`
* `--rpc.subscription.filters.maxtxs value`: Maximum transactions to store per subscription.
  * Default: `10000`
* `--rpc.subscription.filters.maxaddresses value`: Maximum addresses per subscription to filter logs by.
  * Default: `0`
* `--rpc.subscription.filters.maxtopics value`: Maximum topics per subscription to filter logs by.
  * Default: `0`
* `--rpc.subscription.filters.timeout value`: Timeout before idle subscription filters are evicted.
  * Default: `5m0s`
  * Set to `0` to disable eviction.
* `--http.timeouts.read value`: Maximum duration for reading a request.
  * Default: `30s`
* `--http.timeouts.write value`: Maximum duration before timing out a response write.
  * Default: `30m0s`
* `--http.timeouts.idle value`: Maximum idle time for a connection with keep-alives enabled.
  * Default: `2m0s`
* `--authrpc.timeouts.read value`: Maximum read duration for an Engine API request.
  * Default: `30s`
* `--authrpc.timeouts.write value`: Maximum write duration for an Engine API response.
  * Default: `30m0s`
* `--authrpc.timeouts.idle value`: Maximum idle time for an Engine API connection.
  * Default: `2m0s`
* `--healthcheck`: Enables gRPC health checks.
  * Default: `false`

### MCP Server

Flags for configuring the Model Context Protocol (MCP) server. The embedded [MCP server](/fundamentals/mcp) is **enabled by default** on
`127.0.0.1:8553`. Pass `--mcp.disable` to turn it off.

* `--mcp.disable`: Disables the embedded MCP server.
    * Default: `false`
* `--mcp.addr value`: The MCP server listening address.
  * Default: `127.0.0.1`
* `--mcp.port value`: The MCP server listening port.
  * Default: `8553`

### Logging and Profiling

Flags for controlling logging and performance profiling. See [Logs](/fundamentals/logs) for log files, levels, and rotation.

* `--log.json`: Formats console logs with JSON.
  * Default: `false`
* `--log.console.json`: Formats console logs with JSON.
  * Default: `false`
* `--log.dir.json`: Formats file logs with JSON.
  * Default: `false`
* `--verbosity value`: Sets the log level for console logs.
  * Default: `info`
* `--log.console.verbosity value`: Sets the log level for console logs.
  * Default: `info`
* `--log.dir.disable`: Disables disk logging.
  * Default: `false`
* `--log.dir.path value`: The path to store user and error logs.
* `--log.dir.prefix value`: The file name prefix for logs stored on disk.
* `--log.dir.verbosity value`: Sets the log verbosity for disk logs.
  * Default: `dbug`
* `--log.delays`: Enables block delay logging.
  * Default: `false`
* `--pprof`: Enables the pprof HTTP server.
  * Default: `false`
* `--pprof.addr value`: The pprof HTTP server listening interface.
  * Default: `127.0.0.1`
* `--pprof.port value`: The pprof HTTP server listening port.
  * Default: `6060`
* `--pprof.cpuprofile value`: Writes a CPU profile to a file.
* `--trace value`: Writes an execution trace to a file.
* `--vmtrace value`: Sets the provider tracer.
* `--vmtrace.jsonconfig value`: Sets the tracer's configuration.
* `--metrics`: Enables metrics collection and reporting. See [Creating a dashboard](/fundamentals/creating-a-dashboard).
  * Default: `false`
* `--metrics.addr value`: The stand-alone metrics HTTP server listening interface.
  * Default: `127.0.0.1`
* `--metrics.port value`: The metrics HTTP server listening port.
  * Default: `6061`

### Consensus and Forks

Flags related to consensus mechanisms and network forks.

* `--fakepow`: Disables proof-of-work verification.
  * Default: `false`
* `--gpo.blocks value`: The number of recent blocks to check for gas prices.
  * Default: `20`
* `--gpo.percentile value`: The percentile of recent transaction gas prices to use for a suggested gas price.
  * Default: `60`
* `--proposer.disable`: Disables the PoS proposer.
  * Default: `false`
* `--builder.maxblobs value`: Caps the number of blobs included in a locally built block.
  * Default: unset — the protocol maximum applies. Setting it to `0` excludes blob transactions from built blocks entirely.
* `--bor.heimdall value`: The URL of the Heimdall service.
  * Default: `http://localhost:1317`
* `--bor.withoutheimdall`: Runs without the Heimdall service.
  * Default: `false`
* `--bor.period`: Overrides the bor block period.
  * Default: `false`
* `--bor.minblocksize`: Ignores the bor block period and waits for `blocksize` transactions.
  * Default: `false`
* `--polygon.pos.ssf`: Enables Polygon PoS Single Slot Finality.
  * Default: `false`
* `--polygon.pos.ssf.block value`: Enables Polygon PoS Single Slot Finality from a specific block.
  * Default: `0`
* `--polygon.wit-protocol`: Enables the WIT protocol (`wit/0`) for stateless witness data exchange. Primarily useful on Bor (Polygon) chains — the witness buffer is only populated there — and must be set explicitly.
  * Default: `false`

### Sentry

Flags for configuring the [Sentry](/fundamentals/modules/sentry) component.

* `--sentry.api.addr value`: A comma-separated list of Sentry addresses.
* `--sentry.log-peer-info`: Logs detailed peer info when a peer connects or disconnects.
  * Default: `false`
* `--sentinel.addr value`: The address for the sentinel component.
  * Default: `localhost`
* `--sentinel.port value`: The port for the sentinel component.
  * Default: `7777`
* `--sentinel.bootnodes value`: Comma-separated enode URLs for P2P discovery bootstrap for the sentinel.
* `--sentinel.staticpeers value`: Connects to comma-separated consensus static peers.

### Downloader and Synchronization

These flags control the block synchronization and data downloading process, including the BitTorrent protocol settings. See [Downloader](/fundamentals/modules/downloader) for how snapshot downloading works.

* `--downloader.api.addr value`: The Downloader address.
* `--downloader.disable.ipv4`: Disables IPv4 for the Downloader.
  * Default: `false`
* `--downloader.disable.ipv6`: Disables IPv6 for the Downloader.
  * Default: `false`
* `--no-downloader`: Disables the Downloader component.
  * Default: `false`
* `--downloader.verify`: Verifies snapshots on startup.
  * Default: `false`
* `--sync.loop.throttle value`: Sets the minimum time between sync loop starts.
* `--sync.loop.block.limit value`: Sets the maximum number of blocks to process per loop iteration.
  * Default: `5000`
* `--sync.loop.break.after value`: Sets the last stage of the sync loop to run.
* `--bad.block value`: Marks a block as bad and forces a reorg.
* `--webseed value`: Comma-separated URLs for network support infrastructure.

#### BitTorrent Options

* `--torrent.port value`: The port to listen for the BitTorrent protocol.
  * Default: `42069`
* `--torrent.maxpeers value`: An unused parameter.
  * Default: `100`
* `--torrent.conns.perfile value`: The number of connections per file.
  * Default: `10`
* `--torrent.trackers.disable`: Disables conventional BitTorrent trackers.
  * Default: `false`
* `--torrent.upload.rate value`: The upload rate in bytes per second.
  * Default: `16mb`
* `--torrent.download.rate value`: Sets the torrent download rate cap. Default: `512mb`. Use a lower value on shared machines to avoid saturating the connection; use `Inf` to remove the limit.
* `--torrent.webseed.download.rate value`: The download rate for webseeds. If not set, rate limit is shared with torrent.
* `--torrent.verbosity value`: Sets the verbosity level for BitTorrent logs. 0=silent, 1=error, 2=warn, 3=info, 4=debug, 5=detail (must set `--verbosity` to equal or higher level)
  * Default: `1`

### Fork Choice Update (FCU)

Flags for configuring Fork Choice Update behavior.

* `--fcu.timeout value`: FCU timeout before switching to async processing (use `0` to disable).
  * Default: `1s`
* `--fcu.background.prune`: Enables background pruning after FCU.
  * Default: `true`
* `--fcu.background.commit`: Enables background flush and commit after FCU.
  * Default: `false`

### Execution

Flags for configuring the parallel block execution engine.

**All `--exec.*` flags are new in v3.5** — they expose, as CLI flags, execution toggles that on earlier releases were settable only via the `EXEC3_*` / `NO_*` environment variables (which still work).

* `--exec.workers value`: Number of parallel block-execution workers (equivalent to the `EXEC3_WORKERS` env var). Overridden by `--exec.serial`.
  * Default: the number of CPU cores (inherited from the `EXEC3_WORKERS` default when the flag is not set).
  * Note: `erigon --help` describes this flag's default as "half the number of CPU cores". That value is not actually applied — when `--exec.workers` is omitted, Erigon uses `EXEC3_WORKERS`, which defaults to the full CPU-core count. The flag-help text is a known inconsistency in the binary.
* `--exec.serial`: Force serial execution by clamping the parallel executor to a single worker. Wins over `--exec.workers` and `EXEC3_WORKERS` — use to disable parallelism for diagnostics or like-for-like baseline comparisons.
  * Default: `false`
* `--exec.no-prune`: Disable all DB pruning: state-aggregator (Domain/InvertedIndex) plus stage-level pruning (Execution: ChangeSets3/BlockAccessList; TxLookup; WitnessProcessing; Snapshots: PruneAncientBlocks/canonical markers/retirement). Equivalent to `NO_PRUNE=true`. Diagnostic / perf-comparison use only.
  * Default: `false`
* `--exec.no-merge`: Disable state-aggregator file merges for Domain / History / Inverted-Index. Equivalent to `NO_MERGE=true`. Diagnostic / perf-comparison use only.
  * Default: `false`
* `--exec.no-background-maintenance`: Suppress background state-aggregator and E2 block-snapshot retirement goroutines so execution is not perturbed by housekeeping work. Equivalent to `NO_BACKGROUND_E3_BUILD=true`. Diagnostic / focused-performance-testing use only — NOT an operational setting.
  * Default: `false`
* `--exec.batched-io`: Enable BAL-driven I/O optimisations — read-ahead pre-warming of the DB page cache (`READ_AHEAD=true`) and version-map pre-population from BAL hints (`IGNORE_BAL=false`). Disable for cold-read or non-BAL scheduling performance measurements.
  * Default: `true`
* `--exec.state-cache`: Enable the executor's domain-shared read cache. Equivalent to `USE_STATE_CACHE=true`. Disable for cold-read performance measurements.
  * Default: `true`

**Commitment-trie construction.** The following flags change how the commitment (state-root) trie is computed during execution. Both default off and are intended for comparing root hashes against a sequential sync before enabling broadly.

* `--experimental.parallel-commitment` *(New in v3.6)* (experimental): Compute the commitment trie with the fully parallel `ParallelPatriciaHashed` implementation. Equivalent to the `COMMITMENT_PARALLEL=true` environment variable.
  * Default: `false`
* `--experimental.streaming-commitment` *(New in v3.6)* (experimental): Compute the commitment trie with the `StreamingCommitter`, which overlaps trie folding with block execution. If set, takes precedence over `--experimental.parallel-commitment`. No environment-variable equivalent.
  * Default: `false`

### Caplin (Consensus Layer)

Flags for configuring the [Caplin](/fundamentals/caplin) consensus layer.

* `--caplin.discovery.addr value`: The address for the Caplin DISCV5 protocol.
  * Default: `0.0.0.0`
* `--caplin.discovery.port value`: The port for the Caplin DISCV5 protocol.
  * Default: `4000`
* `--caplin.discovery.tcpport value`: The TCP port for the Caplin DISCV5 protocol.
  * Default: `4001`
* `--caplin.checkpoint-sync-url value`: The checkpoint sync endpoint.
* `--caplin.subscribe-all-topics`: Subscribes to all gossip topics.
  * Default: `false`
* `--caplin.max-peer-count value`: The maximum number of peers to connect to.
  * Default: `128`
* `--caplin.enable-upnp`: Enables NAT porting for Caplin.
  * Default: `false`
* `--caplin.local-discovery`: Also attempts to find peers over private IPs. May cause issues with some hosts (for example, Hetzner).
  * Default: `false`
* `--caplin.nat value`: NAT port mapping for Caplin P2P. Sets the external IP advertised in the discv5 ENR and libp2p multiaddrs while the socket binds to `--caplin.discovery.addr`. Required when running inside Docker or behind NAT. Accepted values: `""` (none), `"extip:1.2.3.4"`, `"stun"`, `"stun:<host>"`, `"upnp"`, `"pmp"`, `"pmp:192.168.0.1"`.
  * Default: `""` (no NAT mapping)
* `--caplin.max-inbound-traffic-per-peer value`: The maximum inbound traffic per second per peer.
  * Default: `1MB`
* `--caplin.max-outbound-traffic-per-peer value`: The maximum outbound traffic per second per peer.
  * Default: `1MB`
* `--caplin.adaptable-maximum-traffic-requirements`: Makes the node adaptable to traffic based on the number of validators.
  * Default: `true`
* `--caplin.blocks-archive`: Enables backfilling for blocks.
  * Default: `false`
* `--caplin.blobs-archive`: Enables backfilling for blobs.
  * Default: `false`
* `--caplin.states-archive`: Enables the archival node for historical states.
  * Default: `false`
* `--caplin.blobs-immediate-backfill`: Tells Caplin to immediately backfill blobs.
  * Default: `false`
* `--caplin.blobs-no-pruning`: Disables blob pruning.
  * Default: `false`
* `--caplin.columns-keep-slots value`: Number of slots to retain PeerDAS data column sidecars. Increase for DA oracle or rollup nodes that need longer column history.
  * Default: `131072` (~18 days)
* `--caplin.checkpoint-sync.disable`: Disables checkpoint sync.
  * Default: `false`
* `--caplin.snapgen`: Enables snapshot generation.
  * Default: `false`
* `--caplin.mev-relay-url value`: The MEV relay endpoint.
* `--caplin.validator-monitor`: Enables Caplin validator monitoring metrics.
  * Default: `false`
* `--caplin.custom-config value`: Sets a custom config for Caplin.
* `--caplin.custom-genesis value`: Sets a custom genesis for Caplin.
* `--caplin.use-engine-api`: Uses the Engine API for internal Caplin.
  * Default: `false`
* `--beacon.api.read.timeout value`: HTTP read timeout for the Beacon API server, in seconds.
  * Default: `5`
* `--beacon.api.write.timeout value`: HTTP write timeout for the Beacon API server, in seconds.
  * Default: `31536000` (~1 year)
* `--beacon.api.idle.timeout value`: HTTP idle (keep-alive) timeout for the Beacon API server, in seconds.
  * Default: `25`

### Shutter Network Encrypted Transactions

Flags for configuring the [Shutter Network](/staking/shutter-network) encrypted transactions mempool.

* `--shutter`: Enables the Shutter encrypted transactions mempool.
  * Default: `false`
* `--shutter.p2p.bootstrap.nodes value`: Overrides the default P2P bootstrap nodes.
* `--shutter.p2p.listen.port value`: Overrides the default P2P listen port.
  * Default: `0`

## Configuration file

You can configure Erigon using a YAML or TOML configuration file by specifying its path with the `--config` flag.

:::tip
**Note**: flags specified in the configuration file can be overridden by directly setting them in the Erigon command line.
:::

Both in YAML and TOML files boolean operators (`false`, `true`) and strings without spaces can be specified without quotes, while strings with spaces must be included in `""` or `''` quotes.

### YAML

Use the `--config` flag to point at the YAML configuration file.

```bash
./build/bin/erigon --config ./config.yaml --chain=holesky
```

Example of a YAML config file:

```yaml
datadir : 'your datadir'
chain : "mainnet"
http : true
http.api : ["eth","debug","net"]
```

In this case the `--chain` flag in the command line will override the value in the YAML file and Erigon will run on the Holesky testnet.

### TOML

Use the `--config` flag to point at the TOML configuration file.

```bash
./build/bin/erigon --config ./config.toml
```

Example of a TOML config file:

```toml
datadir = 'your datadir'
chain = "mainnet"
http = true
"http.api" = ["eth","debug","net"]
```

## Environment variables

Erigon supports configuration through environment variables, primarily for experimental features and advanced settings.

### Core Environment Variables

**Database and Performance:**

* `MDBX_LOCK_IN_RAM` - Locks MDBX database in RAM for better performance
* `MDBX_DIRTY_SPACE_MB` - Sets dirty space limit for MDBX database
* `SNAPSHOT_MADV_RND` - Controls snapshot memory advice randomization (default: `true`)

**Synchronization and Pruning:**

* `NO_PRUNE` - Disables pruning when set to true (flag equivalent: `--exec.no-prune`)
* `NO_MERGE` - Disables merging operations (flag equivalent: `--exec.no-merge`)
* `PRUNE_TOTAL_DIFFICULTY` - Controls total difficulty pruning (default: `true`)
* `MAX_REORG_DEPTH` - Sets maximum reorganization depth (default: `96`)
* `CAPLIN_STATE_PRUNE_DISABLE` - Disables pruning of Caplin's state indexing DB after ranges are frozen into snapshots (default: `false`)
* `CAPLIN_STATE_PRUNE_TIMEOUT` - Overrides the per-pass time budget for Caplin state pruning (a duration, e.g. `500ms`; default derived from the chain's slot time)

**Execution and Processing:**

* `EXEC3_PARALLEL` - Enables parallel block execution (Block-STM). **Default changed to `true` in v3.5** — parallel execution is now on by default. Set to `false` or use `--exec.serial` to revert to single-threaded execution.
* `EXEC3_WORKERS` - Sets number of parallel execution workers (default: number of CPU cores)
* `STAGES_ONLY_BLOCKS` - Limits stages to blocks only

**State Cache:**

* `USE_STATE_CACHE` - Enables the executor's domain-shared read cache (default: `true`; flag equivalent: `--exec.state-cache`). When `false` no cache is built, and neither the budgets nor the pin controller below have any effect.
* `STATE_CACHE_ACCOUNTS` - Byte budget for the account cache (default: `150MB`). **New in v3.6**; the built-in budget it overrides was `1GB` in v3.5.
* `STATE_CACHE_STORAGE` - Byte budget for the storage cache (default: `1GB`)
* `STATE_CACHE_CODE` - Byte budget for the code cache, applied separately to each of its two byte-bearing layers; a third, size-only layer is sized independently (default: `512MB`)
* `STATE_CACHE_CODE_INDEX` - Byte budget for the address-to-code index, shared by its two address-keyed LRUs (default: `32MB`, floor 1024 entries each). **New in v3.6**; the built-in budget was `16MB` in v3.5.
* `DISABLE_ADAPTIVE_PIN` - Disables the adaptive trunk-pin controller, which watches per-contract miss pressure on the commitment branch cache and pins the hottest contracts' trunk branches in RAM to cut per-block I/O (default: `true`, so pinning is off; new in v3.6). Set to `false` to enable it — it targets workloads where a single contract dominates storage reads, and costs RAM on the commit path.

The four `STATE_CACHE_*` budgets are new in v3.6. Values parse as human-readable sizes (`150MB`, `1GB`); an unparseable value aborts startup, though only when the state cache is enabled — with `USE_STATE_CACHE=false` nothing reads them.

None of the four is an exact byte bound. Each is divided by a typical per-domain entry size to produce an entry-count cap, and it is that cap, not a running byte total, that evicts — so residency follows the entries actually stored. The code layers assume roughly 12 KiB per contract, and a working set of larger contracts will exceed the configured figure. `STATE_CACHE_CODE` applies to each of the two byte-bearing code layers, so their combined nominal ceiling is twice the value; a third, size-only layer answers `EXTCODESIZE`/`EXTCODEHASH` — `STATE_CACHE_CODE` does not size it, but it grows on demand from the same envelope, up to a ceiling of about 61 MiB. A contract inserted into both at once is stored once and referenced twice, but the layers are independent LRUs: once their eviction orders diverge, a refill into one while the other still holds a live entry leaves two backing arrays for the same contract, so heap use can approach the two-layer total. The account and storage caps are additionally clamped to between 1024 and 2^24 entries, which for their entry sizes means roughly 96 KiB–1.5 GiB for accounts and 88 KiB–1.375 GiB for storage; a value outside its own range makes no difference.

The budgets are not reserved up front. The account, storage and code caches start small and grow in steps, funding each step from one process-wide envelope sized at 1/32 of the memory available to Erigon (system RAM, cgroup limit or `GOMEMLIMIT`, whichever is lowest) and shared with other in-process caches such as the commitment branch cache. A growth step that would overflow the envelope is refused, and that cache evicts within its current size until envelope space frees up. The small construction-time reservation is taken unconditionally, so a full envelope can be modestly overdrawn.

What that means for sizing: each of these state caches starts at 1024 entries, or at its own ceiling if that is smaller — a `STATE_CACHE_CODE` below about 12 MiB starts and stays under 1024 entries. That initial capacity is reserved from the envelope at construction, not on first use: the two byte-bearing code layers take 24 MiB between them before a single block executes. Only growth beyond it is demand-driven, so twice `STATE_CACHE_CODE` is the largest reservation those layers can reach, not one they hold from the start. `STATE_CACHE_CODE_INDEX` differs again — it fixes its entry count at construction but never reserves envelope bytes at all.

Budgets summing past the envelope therefore mean it *can* saturate, not that it will — that depends on the working set. With 32 GiB available to Erigon after limits the whole envelope is 1 GiB — below the roughly 2.2 GiB the envelope-backed caches can reserve under the defaults (accounts, storage, twice the code budget, and the size-only layer) — so a large enough working set saturates it; past that point raising the envelope-backed budgets together adds no aggregate capacity and only changes which cache wins the space left. Where more is available the envelope may never saturate, and there raising them does help. Mind that the figure follows the *lowest* of physical RAM, the cgroup limit and `GOMEMLIMIT`: a 32 GiB host running Erigon in an 8 GiB container gets a 256 MiB envelope, not 1 GiB. `STATE_CACHE_CODE_INDEX` sits outside the envelope altogether — its entry cap is fixed up front from the budget, so above the 1024-entry floor noted above, raising it adds index capacity independently of how saturated the envelope is.

### Memory and Debugging Variables

**Memory Management:**

* `NO_MEMSTAT` - Disables memory statistics collection
* `SAVE_HEAP_PROFILE` - Enables automatic heap profiling
* `HEAP_PROFILE_THRESHOLD` - Memory usage percentage threshold for heap profiling (default: 35%)

**Tracing and Debugging:**

* `TRACE_ACCOUNTS` - Comma-separated list of accounts to trace
* `TRACE_BLOCKS` - Comma-separated list of block numbers to trace
* `TRACE_INSTRUCTIONS` - Enables instruction-level tracing

### Docker Environment Variables

When running Erigon in [Docker](/fundamentals/docker-compose), you can configure user permissions and data directories:

* `DOCKER_UID` - The UID of the Docker user
* `DOCKER_GID` - The GID of the Docker user
* `XDG_DATA_HOME` - The data directory mounted to containers

### Usage Examples

**Basic Performance Tuning:**

```bash
export MDBX_LOCK_IN_RAM=true
export SNAPSHOT_MADV_RND=false
./build/bin/erigon --datadir=/path/to/data
```

**Memory Debugging:**

```bash
export SAVE_HEAP_PROFILE=true
export HEAP_PROFILE_THRESHOLD=45
./build/bin/erigon --datadir=/path/to/data
```

**Docker Deployment:**

```bash
export DOCKER_UID=$(id -u)
export DOCKER_GID=$(id -g)
export XDG_DATA_HOME=/preferred/data/folder
make docker-compose
```
