# Environment

> Every NeuroChain environment variable — node (network, consensus, economics, AI, IBC v2, security), gateway, web app, docs site and MCP server — with defaults and what each one changes.

Source: https://docs.nro.world/operate/env

All services read their settings from environment variables; the repository's `.env.example` lists them with comments. Defaults below are what the code uses when a variable is unset.

Several protocol values (gas budget, stake, rewards, slashing, AI thresholds) are **governance parameters** stored on chain. Where an environment variable exists for one, it overrides the on-chain value **on that node at start-up** — meant for test networks; on a shared network every validator must use the same value. See [Governance → Parameters](/learn/governance#parameters).

## Node

### Network and identity

| Variable | Default | Meaning |
|----------|---------|---------|
| `CHAIN_ENV` | `mainnet` | `mainnet`: strict signatures, faucet off, RPC on localhost. `testnet`: warn-only signatures, faucet on |
| `NEUROCHAIN_NETWORK` | `neurochain-mainnet-1` | Network / chain id |
| `NEUROCHAIN_DATA_DIR` | `./data` | Data directory (state, WAL, key) |
| `NEUROCHAIN_MODELS_DIR` | `./models` | AI model weights |
| `NEUROCHAIN_RPC_PORT` | `9933` | HTTP RPC port |
| `NEUROCHAIN_RPC_HOST` | `localhost` (mainnet) / `0.0.0.0` (testnet) | RPC bind address |
| `NEUROCHAIN_P2P_PORT` | `30333` | P2P port (also carries consensus) |
| `NEUROCHAIN_P2P_PORT_MIN` / `_MAX` | `1024` / `65534` | Accepted peer port range |
| `NEUROCHAIN_NODE_ADDR` | `localhost:<p2p port>` | Address peers use to reach this node; must not be `0.0.0.0`. Matches the node to its genesis validator entry |
| `NEUROCHAIN_BOOTSTRAP` | — | Comma-separated peers to join on start |
| `NEUROCHAIN_PEER_DISCOVERY_SECS` | `30` | Peer discovery interval |
| `NEUROCHAIN_P2P_CONN_RATE_LIMIT` | `20` | Inbound P2P connections per second per IP |
| `NEUROCHAIN_TLS_CERT`, `NEUROCHAIN_TLS_KEY` | — | Serve the RPC over HTTPS |

### Genesis

| Variable | Default | Meaning |
|----------|---------|---------|
| `NEUROCHAIN_GENESIS_VALIDATORS` | this node only | `neuro:name.node|p2p_host:port|stake_nro|trust|ml_dsa_pubkey_hex,…` — identical on every validator. See [Run a node](./node#a-multi-validator-network) |
| `NEUROCHAIN_GENESIS_ACCOUNTS` | — | `neuro:addr.human|nro,…` — initial balances |
| `NEUROCHAIN_FAUCET_BALANCE` | 1 000 000 000 NRO | Balance of the faucet vault at genesis |
| `NEUROCHAIN_INITIAL_BALANCE` | `0` | uNRO credited to a never-seen account on first read (test networks only) |
| `NEUROCHAIN_GAS_SPONSOR` | `neuro:faucet.vault` | Onboarding gas sponsor |
| `NEUROCHAIN_GAS_SPONSOR_FUND` | 1 000 000 NRO | Its gas pool at genesis |
| `NEUROCHAIN_CHECKPOINT_URL` | — | Start an empty node from this node's state snapshot |

### Consensus and sharding

| Variable | Default | Meaning |
|----------|---------|---------|
| `NEUROCHAIN_MIN_VALIDATORS` | `7` | Below this, the node warns about reduced fault tolerance |
| `NEUROCHAIN_BLOCK_MS` | `200` | Minimum wait before proposing a block with transactions |
| `NEUROCHAIN_EMPTY_BLOCK_MS` | `2000` | Minimum wait before proposing an empty block |
| `NEUROCHAIN_SYNC_HISTORY_BLOCKS` | `10000` | Decided blocks kept to serve catching-up peers |
| `NEUROCHAIN_JAIL_BLOCKS` | `10000` | Jail length after a slash (governance `jail_blocks`) |
| `NEUROCHAIN_SLASH_FRACTION_DOUBLE_SIGN_BPS` | `500` | Double-sign slash, basis points of `min_stake` |
| `NEUROCHAIN_SLASH_REWARD_FRACTION_BPS` | `100` | Reporter's share of a slash |
| `NEUROCHAIN_SLASH_EVIDENCE_WINDOW` | `10000` | Oldest offence (in blocks) that evidence may prove |
| `NEUROCHAIN_SHARD_ID` | — | Shard this node serves; unset = single shard |
| `NEUROCHAIN_SHARDS` | `4` with a shard id, else `1` | Number of shards |
| `NEUROCHAIN_SHARD_DIR_PREFIX` | `shard` | Sub-directory name per shard |

### Economics and mempool

| Variable | Default | Meaning |
|----------|---------|---------|
| `NEUROCHAIN_UNBONDING_BLOCKS` | governance (1 512 000) | Staking lock |
| `NEUROCHAIN_REWARD_INTERVAL_BLOCKS` | governance (216 000) | Blocks between reward payouts |
| `NEUROCHAIN_FUEL_PER_GAS_UNIT` | `20000` | Contract fuel per gas unit |
| `NEUROCHAIN_MAX_SPONSORED_FEE` | `100000` uNRO | Largest fee a gas pool pays per transaction |
| `NEUROCHAIN_MAX_MEMPOOL` | `10000` | Pending transactions held |
| `NEUROCHAIN_MAX_PENDING_PER_ACCOUNT` | `64` | Pending transactions per sender |
| `NEUROCHAIN_RBF_MIN_BUMP_PCT` | `10` | Gas price increase needed to replace a pending transaction |
| `NEUROCHAIN_MIN_FEE_PER_GAS` | `0` | Extra mempool price floor |
| `NEUROCHAIN_FAUCET_MAX_NRO` | `100` | Largest faucet request (test networks) |
| `NEUROCHAIN_FAUCET_COOLDOWN_SECS` | `86400` | Faucet cooldown per address; `0` = none |

### AI

| Variable | Default | Meaning |
|----------|---------|---------|
| `MONITOR_INTERVAL_SECS` | `20` | Re-audit of deployed contracts |
| `MONITOR_SCORE_THRESHOLD` | `10` | Score change that triggers a certificate update |
| `NEUROCHAIN_SENTINEL_POLICY_ENABLED` | governance (`0`) | Sentinel policy layer on/off |
| `NEUROCHAIN_SENTINEL_HOLD_THRESHOLD` | governance (`60`) | Score × 100 from which transfers are held |
| `NEUROCHAIN_SENTINEL_STEPUP_THRESHOLD` | governance (`70`) | Score × 100 from which the owner must confirm |
| `NEUROCHAIN_SENTINEL_HOLD_BLOCKS` | governance (`50`) | Automatic release delay |
| `NEUROCHAIN_SENTINEL_CONFIRM_EXPIRY_BLOCKS` | governance (`1000`) | Wait for confirmation before refund |
| `NEUROCHAIN_SENTINEL_AGENT_CONFIRM_THRESHOLD` | governance (`60`) | Threshold for session-key transfers |
| `NEUROCHAIN_TRUST_ACTIVATION_BLOCKS` | governance (`300`) | Delay before a trusted recipient counts |
| `AI_EXPORT_MAX_LIMIT` | `5000` | Rows per AI data export request |

### IBC v2

See [IBC v2 & sharding → Configuration](./ibc#configuration): `NEUROCHAIN_IBC_OPERATOR_PUBKEYS`, `NEUROCHAIN_IBC_TRUSTED_PUBKEYS`, `NEUROCHAIN_IBC_REQUIRE_HEADER`, `NEUROCHAIN_IBC_REQUIRE_PACKET_COMMITMENT`, `NEUROCHAIN_IBC_TIMEOUT_BLOCKS`, `NEUROCHAIN_IBC_MAX_PACKET_UNRO`, `NEUROCHAIN_IBC_MAX_CHANNEL_ESCROW_UNRO`, `NEUROCHAIN_IBC_NATIVE_DENOM`.

### Native assets

| Variable | Default | Meaning |
|----------|---------|---------|
| `NEUROCHAIN_ASSET_ISSUERS` | — | Addresses given the `verified` issuer tier at genesis |
| `NEUROCHAIN_RESERVED_SYMBOLS` | — | Tickers reserved at genesis |

Both are read once, at genesis; afterwards the registries change only through governance.

### Access and limits

| Variable | Default | Meaning |
|----------|---------|---------|
| `NEUROCHAIN_RPC_RATE_LIMIT` | `100` | RPC requests per second per IP |
| `CORS_ALLOWED_ORIGINS` | `*` | Allowed browser origins |
| `NEUROCHAIN_INTERNAL_TOKEN` | — | Required `X-Internal-Token` for internal endpoints |
| `NEUROCHAIN_SNAPSHOT_TOKEN` | — | Required bearer token for `/api/v1/state/snapshot` |
| `NEUROCHAIN_ALLOW_SERVER_DERIVE` | `false` | Allow `POST /api/v1/wallet/derive-address` (receives a recovery phrase) on test networks; always off on mainnet |
| `RUST_LOG` | `neurochain=info,warn` | Log level |

## Gateway

Listed with explanations on the [Gateway](./gateway#configuration) page: `PORT`, `NODE_RPC_URL`, `NEUROCHAIN_SHARD_NODES`, `SHARD_NODE_URLS`, `NETWORK_ID`, `CORS_ALLOWED_ORIGINS`, `TLS_CERT`, `TLS_KEY`, rate limits (`GLOBAL_RL_MAX_RPS`, `AI_RL_MAX_RPM`, `WS_*`), chain watching (`POLL_NODE_INTERVAL_MS`, `SENTINEL_*`, `ALERT_COOLDOWN_MS`), faucet (`FAUCET_AMOUNT`, `FAUCET_COOLDOWN_SECS`, `REDIS_URL`) and AI tools (`ANTHROPIC_API_KEY`, `SMARTFORGE_*`, `AI_EXPORT_TOKEN`, `ASSISTANT_*`).

## Web app

| Variable | Default | Meaning |
|----------|---------|---------|
| `WEB_PORT` | `8080` | Dev server port |
| `WEB_HOST` | `localhost` | Dev server bind; `0.0.0.0` to expose on the network |
| `GATEWAY_URL` | `http://localhost:3000` | Gateway the dev server proxies `/api` and `/ws` to |
| `VUE_APP_NEUROCHAIN_RPC` | — (same origin) | Force a fixed API base URL into the build |
| `VUE_APP_SITE_URL`, `VUE_APP_SITE_NAME`, `VUE_APP_SITE_OG_IMAGE` | — | Metadata of the deployed app |
| `VUE_APP_DOCS_URL` | — | Link to this documentation |

## Docs site

| Variable | Default | Meaning |
|----------|---------|---------|
| `DOCS_SITE_URL` | `https://docs.nro.world` | Canonical URLs, sitemap, `hreflang`, `llms.txt` |
| `DOCS_OG_IMAGE` | `/og-image.png` | Social preview image |
| `DOCS_GOOGLE_SITE_VERIFICATION`, `DOCS_BING_SITE_VERIFICATION` | — | Search-console ownership tokens |
| `DOCS_HOST`, `DOCS_PORT` | `localhost`, `5173` | Dev server |
| `DOCS_BASE` | `/` | Base path |

## MCP server

| Variable | Default | Meaning |
|----------|---------|---------|
| `NEUROCHAIN_MCP_CONFIG` | — | Path to the JSON config — see [AI agents (MCP)](/build/mcp) |