> ## Documentation Index > Fetch the complete documentation index at: https://docs.cowboy.inc/llms.txt > Use this file to discover all available pages before exploring further. # Configuration Reference > Validator config file, genesis, environment variables, and CLI project config ## Overview Cowboy configuration lives in three layers: 1. **Validator** — a per-validator YAML file plus `genesis.json`, generated by the `setup` binary (`./scripts/run_build.sh` for a local devnet) 2. **Node environment variables** — runtime knobs for the RPC server 3. **CLI project config** — `.cowboy/config.json` in your project, created by `cowboy init` ## Validator config file (YAML) Generated as `test/.yaml` on a local devnet. Key fields: ### Identity and keys | Field | Meaning | | --------------------- | ---------------------------------------------------------- | | `private_key` | Validator's Ed25519 consensus signing key (hex) | | `share`, `polynomial` | BLS12-381 threshold-signature share and network polynomial | ### Network | Field | Default (local devnet) | Meaning | | --------------------------------- | ------------------------------- | ---------------------------------------------------- | | `port` | from `--start-port` (e.g. 3000) | P2P consensus port | | `metrics_port` | `port + 1` | Prometheus metrics endpoint | | `rpc_port` | `4000` | HTTP RPC port; omit to disable RPC on this validator | | `local` | `true` | Local vs authenticated P2P mode | | `allowed_peers` / `bootstrappers` | generated | Peer public keys / initial bootstrap subset | ### Storage, runtime, logging | Field | Meaning | | ----------------------------------------------- | --------------------------------------------------------------------------- | | `directory` | State/block storage directory for this validator | | `worker_threads` | Tokio runtime threads | | `message_backlog`, `mailbox_size`, `deque_size` | Engine queue depths (devnet default 16384 / 16384 / 10) | | `signature_threads` | Dedicated BLS verification threads (default 2) | | `log_level` | `trace` / `debug` / `info` / `warn` / `error` | | `log_block_metrics_table` | Emit the per-block gas-lane/timer metrics table to the log (default `true`) | ### Chain and services | Field | Meaning | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `genesis_config_path` | Path to `genesis.json` (relative to the config file) | | `chain_id`, `network` | Usually inherited from genesis; used for replay protection in storage delegation | | `enable_faucet` | Serve `/faucet` (also requires a dev chain id — 1 or 100) | | `indexer` | Optional indexer URL the validator **uploads** chain data to (seeds, notarizations, finalizations). For historical-query fallback on the RPC side, use the `INDEXER_URL` env var instead | ## Genesis (`genesis.json`) | Field | Meaning | | ---------------------------------- | ---------------------------------------------------------------------------------- | | `total_supply` | Total CBY supply in base units | | `accounts` | Initial balances (`public_key_hex` or deterministic `seed`, `balance`, `nonce`) | | `chain_id` | Chain identifier — `1` local, `100` dev; gates the faucet | | `network` | Network name (e.g. `canyon`, `mesa`) used in delegation-cert domain separation | | `system_deployers` | Addresses allowed to deploy actors with the `sys.upgrade` entitlement | | `relay_nodes`, `auto_drain_policy` | Pre-registered CIP-9 relays and drain-settlement policy | | `reputation_config` | CIP-2 runner-reputation EMA parameters (half-life, floor/ceiling, jail-exit floor) | ## Node environment variables | Variable | Default | Effect | | ----------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------- | | `RPC_BIND_ADDRESS` | `127.0.0.1` | RPC bind **host** (e.g. `0.0.0.0` to expose; the port comes from `rpc_port` and must not be included here) | | `RPC_GLOBAL_RATE_LIMIT_PER_SEC` | `100` | Global RPC rate limit (cap 10,000) | | `RPC_SUBMIT_ADMISSION_CONCURRENCY` | `32` | Concurrent `/submit` admission permits | | `FAUCET_RATE_PER_MIN` | `5` | Faucet rate limit | | `RAS_EXPLORER_RATE_PER_SEC` | `5` | Per-IP limit for explorer-facing `/ras/*` reads | | `STATE_SYNC_RATE_PER_SEC` | `5` | Per-IP limit for `/state/snapshot` & `/state/operations` | | `CORS_ALLOWED_ORIGINS` | `http://localhost:3000` | CORS allowlist (comma-separated, or `*`) | | `COWBOY_DEV_MODE` | unset | Serve Swagger UI (`/swagger-ui`) + OpenAPI spec — dev only | | `INDEXER_URL` | unset | Fallback indexer for historical data | | `RAS_ALLOW_PRIVATE_RELAY_ENDPOINTS` | unset | Permit private-IP relay endpoints (devnet only; SSRF guard otherwise) | Consensus timing (leader timeout, certification timeout, fetch limits) is compiled into the validator binary and is not file-configurable. ## CLI project config (`.cowboy/config.json`) Created by `cowboy init `; supports multiple named environments: ```json theme={null} { "active": "local", "environments": { "local": { "rpc_url": "http://localhost:4000", "key_file": "keys/local", "watchtower_registry": null, "identity": "0x..." } } } ``` | Field | Meaning | | --------------------- | ------------------------------------------------------------- | | `active` | Currently selected environment | | `rpc_url` | RPC endpoint for that environment | | `key_file` | Path to the secp256k1 key, relative to `.cowboy/` | | `watchtower_registry` | Watchtower registry actor address (optional) | | `identity` | Network identity (BLS polynomial) for verification (optional) | **Resolution order** (first match wins): * Private key: `--private-key` flag → `COWBOY_PRIVATE_KEY` env → `key_file` of the active environment → legacy `.cowboy/key` * RPC URL: `--rpc-url` flag → `COWBOY_RPC_URL` env → active environment's `rpc_url` → `http://localhost:4000` `cowboy init local` targets a local validator; `cowboy init dev` targets the hosted devnet. See [cowboy init](/cli-specs/cowboy-init). ## Runner daemon The off-chain runner reads its executor credentials from the environment — `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, and `LLM_MODEL` for the LLM executor — generates its key material on first run, and registers on-chain with a stake (`cowboy runner register --stake 50000`, denominated in CBY). Stake gates eligibility twice: registration requires stake ≥ 1.5× the runner's declared maximum job value, and at dispatch a runner is only a candidate for jobs whose price its effective stake covers at 1.5×. See [cowboy runner](/cli-specs/cowboy-runner-job) and [CIP-2](/cips/cip-2-offchain-compute). ## Further reading * [RPC API Reference](/references/rpc-api) — endpoints these knobs gate * [Troubleshooting](/getting-started/troubleshooting) — symptoms caused by misconfiguration * [Quickstart](/getting-started/quickstart) — the happy-path local setup