Reference

Config

Every environment variable and config key, with defaults. Where the example file and the code disagree, we say so.

~/.config/irin/gateway.env

The private env file of the source-run canonical Gateway, mode 0600. It is generated by make setup from config/gateway.env.example, and the __GENERATED_*__ markers in the example are replaced with real values on first install. Every key below appears in that file.

make setup

SourceGenerates ~/.config/irin/gateway.env from the example, filling the __GENERATED_*__ markers on first install, and preserves operator-owned values you already set.

On the installed app, the Keychain holds the keys

IRIN.app's own Gateway pack does not ask you to edit this file: the Council client key (GW_API_KEY) and the arm principal (GW_ARM_PRINCIPALS) live in the macOS Keychain, held per spawn and scrubbed from the ambient environment. This page documents the source-run canonical stack, where the file is the operator's job.

Credentials and auth

Key

Meaning

AUTH_PEPPER

Server-side pepper for hashing API keys. Required non-empty.

BOOTSTRAP_TOKEN

One-time admin key for provisioning the first real admin key. Also serves as the fallback for WATCH_ADMIN_TOKEN.

WATCH_ADMIN_TOKEN

Watch and Outbox admin token. Empty means all admin routes return 401.

COUNCIL_GATEWAY_TOKEN

Token the council endpoint presents to the gateway.

COUNCIL_GATEWAY_KEY_ID

Key id paired with COUNCIL_GATEWAY_TOKEN.

CLAUDE_PROXY_TOKEN

Bearer token for the local-CLI proxy provider claude-cli.

CODEX_PROXY_TOKEN

Bearer token for the local-CLI proxy provider gpt-cli.

Sidecar core

Key

Meaning

GATEWAY_DURABLEexample: 1

Durable state DB. Only the exact value 1 counts.

GATEWAY_AUTH_FAIL_CLOSEDdefault: true

Fail closed on auth errors. The example sets true, which is also the code default.

SIDECAR_SOCKET_MODEexample: 0660

Permissions on the sidecar socket. A malformed value is a hard error.

SIDECAR_SOCKET_GIDexample: 9999

Group id on the sidecar socket. A malformed value is a hard error.

Council endpoint

Key

Meaning

GW_ENABLE_COUNCIL_ENDPOINTexample: 1

Enables the council endpoint. Must be exactly 1.

COUNCIL_BASE_URLexample: http://host.docker.internal:8765

Where the gateway reaches the council server.

Watch runtime

Key

Meaning

WATCH_DISPATCHER_ENABLEDexample: false

Enables the dispatcher. Needs WATCH_DISPATCHER_GATEWAY_KEY.

WATCH_PRODUCER_ENABLEDexample: false

Boot gate only. Effective with the dispatcher key and EXECUTION_MODE=LIVE.

WATCH_CANARY_TENANTexample: canary

Canary tenant. The example says canary; the code default when unset is sovereign. Empty or invalid is fatal.

DAILY_SPEND_CAP_USDexample: 25

Daily spend cap. The example says 25; the code default is 50, and the cap may only be lowered.

WATCH_MAX_FANOUT_COST_USDexample: 2.50

Max fanout cost. The example says 2.50; the code default is 5.0.

Reconciliation

Key

Meaning

RECON_CADENCE_SECS

Reconciliation cadence. Unset means recon never spawns.

RECON_DIVERGENCE_THRESHOLD_USDdefault: 1.0

Divergence threshold in USD.

RECON_IMPORT_PATH

Import path used by reconciliation.

RECON_AUTO_DISARMdefault: off

Page-only knob. on auto-disarms on divergence.

ROOT_PUBKEY_HEX

Root public key for ceremony envelopes. Unset means ceremony-envelope verification is disabled, with a warning.

Arming

Key

Meaning

GW_ARM_PRINCIPALS

Comma-separated principals allowed to arm. At least 1 is required for the arm path.

GW_ARM_DEVIATION_FLAG

Deviation flag for the arm path.

GW_ARM_PRINCIPAL_DOMAINS

Allowed principal domains for arming.

ARM_NOTIFY_URL

Notification URL for arming events.

ARM_STAGE_TTL_MSdefault: 120000

Time-to-live for a staged arm, in milliseconds.

Dispatcher auth

Key

Meaning

WATCH_DISPATCHER_GATEWAY_KEY

Key the dispatcher uses to authenticate to the gateway.

COUNCIL_AUTH_TOKEN

Auth token for the dispatcher's council calls.

The wider dial board

Beyond the generated env file, the stack reads these dials from the environment. One line each: name, meaning, and default where the code has one.

Gateway core

Key

Meaning

GATEWAY_STATE_DB_PATHdefault: /var/lib/sidecar/gateway.db

Durable state database path.

SIDECAR_SOCKET_PATHdefault: /tmp/gateway-sidecar.sock

Unix socket the sidecar listens on.

SIDECAR_GLOBAL_RPMdefault: 6000

Global requests-per-minute cap.

RATE_LIMIT_EXEMPT_CIDRS

CIDR ranges exempt from rate limiting.

IP_POLICY_PATH

IP policy file path.

AUTH_CONFIG_PATHdefault: conf/auth_keys.json

API key configuration file.

MAX_READ_SIZE_MBdefault: 5

Maximum request body read size in megabytes.

MAX_ALLOWED_SKEW_MSdefault: 5000, clamp 1000-10000

Allowed clock skew in milliseconds.

REDIS_URL

Redis connection URL.

OTEL_EXPORTER_OTLP_ENDPOINT

OpenTelemetry OTLP export endpoint.

DECON_CONFIG_PATH

Decon config file path.

GUARD_DRY_RUN

Guard dry-run mode.

MODELS_JSON_PATH

Model catalog JSON path.

LEDGER_DB_PATHdefault: ledger.db

Metering ledger database.

LEDGER_SIGNING_KEY_PATH

Ledger signing key path.

LEDGER_OLD_SIGNING_KEY_PATH

Previous ledger signing key, kept for rotation.

LEDGER_NEW_KEY_STAGING_PATH

Staging path for a new ledger key.

DIRECTIVE_IDENTITY_PATH

Directive signing identity path.

COUNCIL_IDEM_DB_PATH

Council idempotency database path.

COUNCIL_CONCURRENCY_CAPdefault: 2

Concurrency cap for council calls.

LIBRARIAN_BASE_URLdefault: http://127.0.0.1:11435

Librarian service base URL.

Watch and dispatcher

Key

Meaning

WATCH_DB_PATHdefault: watch.db

Watch database path.

WATCH_WORKER_ENABLEDdefault: false

Enables the watch worker.

WATCH_WORKER_TICK_INTERVAL_MSdefault: 1000

Worker tick interval in milliseconds.

WATCH_WORKER_MAX_CLAIMS_PER_TICKdefault: 10

Maximum claims per worker tick.

WATCH_WORKER_LEASE_DURATION_MSdefault: 30000

Worker claim lease duration in milliseconds.

WATCH_WORKER_TENANT_SCOPEdefault: default

Tenant scope the worker claims for.

WATCH_DISPATCHER_STRICT_BOOTdefault: false

Strict dispatcher boot checks.

EXECUTION_MODE

Must be exactly LIVE for armed execution.

WATCH_REPLAY_EPOCH

Replay epoch. 0 means legacy/open.

WATCH_DELIBERATION_DEADLINE_MSdefault: 300000

Deliberation deadline in milliseconds.

DIRECTIVE_STAGE_TTL_MSdefault: 90000, range 30k-300k

Directive staging TTL in milliseconds.

DIRECTIVE_MAX_DELIVERY_ATTEMPTSdefault: 5, range 2-50

Maximum directive delivery attempts.

WATCH_LEASE_DURATION_MSdefault: 150000

Watch lease duration in milliseconds.

WATCH_LEASE_RENEW_MSdefault: lease/3

Watch lease renewal interval.

WRITER_CLAIM_STALE_MSdefault: 90000

Writer claim staleness threshold in milliseconds.

WRITER_CLAIM_HEARTBEAT_MSdefault: 30000

Writer claim heartbeat interval in milliseconds.

WATCH_PENDING_ESCALATIONS_MAX_NONTERMINALdefault: 1000

Cap on pending nonterminal escalations.

GW_ARM_WINDOW_MSdefault: 86400000 (24h)

Arm validity window in milliseconds.

GW_ARM_SIGNED_WINDOWdefault: true

Whether the arm window must be signed.

GW_ARM_ATTEST_KEYS_PATH

Attestation keys path for arming.

GW_ARM_OTC_HASHES_PATHRETIRED

Retired. Warns if set.

DUP_CHARGE_AUTO_DISARMdefault: off

Auto-disarm on duplicate charge.

SENTINELS_CONFIG_PATHdefault: /etc/gateway/sentinels.yaml

Sentinel definitions file.

PRECEDENT_INDEX_PATH

Precedent index path.

Council server

Key

Meaning

COUNCIL_DEV_NO_AUTH

1 disables auth. Loopback development only; never on a network-accessible service.

COUNCIL_MAX_CONCURRENT_DELIBERATIONSdefault: 4

Maximum concurrent deliberations.

COUNCIL_MAX_BUDGET_USDdefault: 10.0

Maximum deliberation budget in USD.

COUNCIL_CORS_ORIGINS

Allowed CORS origins.

COUNCIL_PROVIDER_TIMEOUT_SECSdefault: 1800

Provider call timeout in seconds.

COUNCIL_SESSIONS_DIRdefault: sessions

Sessions directory.

COUNCIL_RUNS_DIRdefault: runs

Runs directory.

COUNCIL_WEBHOOK_SLACK / _DISCORD / _GENERIC / _TELEGRAM

Webhook URLs for drift notifications.

COUNCIL_MAPMAKER_ROOTS

Mapmaker roots.

COUNCIL_VIA_GATEWAY

1 means Governed routing through the gateway.

COUNCIL_SOVEREIGN_MODE

Sovereign mode toggle.

Providers

Key

Meaning

ANTHROPIC_API_KEY / OPENAI_API_KEY / XAI_API_KEY

First-party provider keys.

NVIDIA_API_KEY, NOUS_API_KEY, DEEPSEEK_API_KEY, GROQ_API_KEY, OPENROUTER_API_KEY, MISTRAL_API_KEY, TOGETHER_API_KEY, FIREWORKS_API_KEY, PERPLEXITY_API_KEY, SAMBANOVA_API_KEY, CEREBRAS_API_KEY, MOONSHOT_API_KEY, COHERE_API_KEY

OpenAI-compatible provider keys.

VERTEX_PROJECT / GOOGLE_CLOUD_PROJECT

Vertex project id.

VERTEX_LOCATIONdefault: global

Vertex location.

VERTEX_GEMINI_MODEL

Vertex Gemini model override.

COUNCIL_CLAUDE_FORCE_API / COUNCIL_CLAUDE_API_FALLBACK

Force the Claude API path, or fall back to it.

COUNCIL_GPT_API_FALLBACK

GPT API fallback.

COUNCIL_PREFER_GROK_CLI / COUNCIL_GROK_CLI_FALLBACK_API

Prefer the Grok CLI, or fall back to the API.

COUNCIL_GROK_CLI_SERIALIZEdefault: on

Serialize Grok CLI calls.

COUNCIL_CLI_TIMEOUT_SECSdefault: 300

CLI provider timeout in seconds.

COUNCIL_GROK_CLI_MAX_TURNSdefault: 8

Maximum Grok CLI turns.

COUNCIL_GROK_CLI_SEAT_MAX_TURNSdefault: 6

Maximum Grok CLI turns per seat.

COUNCIL_NIM_ENABLE_THINKING / COUNCIL_INCLUDE_REASONINGdefault: off

Reasoning and thinking toggles.

EXA_API_KEY / TAVILY_API_KEY / FIRECRAWL_API_KEY / SEMANTIC_SCHOLAR_API_KEY

Evidence backend keys.

COUNCIL_SHELDON_CITATION_OVERRIDEdefault: contradicted

Sheldon citation override policy.

COUNCIL_SHELDON_SKIP_OPINION_ROUNDdefault: off

Skip the Sheldon opinion round.

COUNCIL_SHELDON_EVIDENCE_CACHEdefault: on

Sheldon evidence cache.

COUNCIL_SHELDON_WEB_EVIDENCEdefault: auto

Sheldon web evidence mode.

GATEWAY_URL + GW_API_KEY

Council-to-gateway transport credentials.

Scripts and demo

Key

Meaning

DEMO_ALLOW_BUILD

Allow the demo scripts to build images.

DEMO_PULL

Pull images for the demo scripts.

DEMO_GW_PORT / DEMO_COUNCIL_PORT

Demo gateway and council ports.

IRIN_TAILSCALE_SERVE

Tailscale serve toggle for scripts.

IRIN_DOCKER_WAIT_SECSdefault: 180

How long scripts wait for Docker, in seconds.

Where the files disagree

The example env file and the code do not always tell the same story. These are the four known deltas. When in doubt, the code wins.

Known example-vs-code deltas

WATCH_CANARY_TENANT: example says canary, code default is sovereign.
DAILY_SPEND_CAP_USD: example says 25, code default is 50.
WATCH_MAX_FANOUT_COST_USD: example says 2.50, code default is 5.0.
GW_ARM_OTC_HASHES_PATH: retired. The code warns if you set it.

Applying changes

make runtime-restart

OperatorAdd credentials to your shell profile, open a new terminal, then restart the runtime so the new environment takes effect.

Fine print

Discovery reports variable names only, never key values, and never makes a billable call.
Credentials go in your shell profile. Open a new terminal, then run make runtime-restart.
GATEWAY_DURABLE unset means in-memory state: a real data-loss risk on restart.
Local layout: ~/.config/irin/gateway.env (mode 0600), ~/.irin/ledger_key.pem (mode 0600), and the Docker volume gateway_sidecar_data.