Configuration Reference

Overview

Cowboy configuration lives in three layers:

Validator — a per-validator YAML file plus genesis.json, generated by the setup binary (./scripts/run_build.sh for a local devnet)
Node environment variables — runtime knobs for the RPC server
CLI project config — .cowboy/config.json in your project, created by cowboy init

Validator config file (YAML)

Generated as test/<validator-pubkey>.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 <network>; supports multiple named environments:

{
  "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.

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 and CIP-2.

Start Here

Build

How Cowboy Works

Reference

Overview

Validator config file (YAML)

Identity and keys

Network

Storage, runtime, logging

Chain and services

Genesis (`genesis.json`)

Node environment variables

CLI project config (`.cowboy/config.json`)

Runner daemon

Further reading

​Overview

​Validator config file (YAML)

​Identity and keys

​Network

​Storage, runtime, logging

​Chain and services

​Genesis (genesis.json)

​Node environment variables

​CLI project config (.cowboy/config.json)

​Runner daemon

​Further reading

Overview

Validator config file (YAML)

Identity and keys

Network

Storage, runtime, logging

Chain and services

Genesis (`genesis.json`)

Node environment variables

CLI project config (`.cowboy/config.json`)

Runner daemon

Further reading