Configuration

Where Warden reads its settings and keys, every environment variable it understands, and what lives in the local cache.

Warden keeps settings and secrets apart. Settings go in config files. Keys stay in the environment, so your shell, your secret manager, and your CI secrets all work without extra steps.

Where settings come from

Config files are read in three layers, and each later layer overrides the earlier ones:

  1. Warden's built-in defaults.
  2. Your global config, ~/.config/warden/config.jsonc, which warden setup creates.
  3. The repository's warden.jsonc, which warden setup project creates.

A config file can name the environment variable that holds a key (apiKeyEnv), but it can't contain the key itself.

Keys and other variables are read in this order, and the first value found wins:

  1. The process environment, from your shell, CI, or tools like Doppler, Infisical, or 1Password.
  2. The env files your config names, such as ~/.config/warden/env.
  3. The repository's .env and .env.local.

To add one extra env file for a single run, set WARDEN_ENV_FILE=/path/to/file.

warden mcp is the exception. It loads no env files and keeps only a short allowlist of variables, so provider keys and CI tokens never reach the MCP server or the detectors it starts. See Untrusted input.

Providers

None of these are needed for check, mcp, opencode-review, or post-pass. On the OpenCode path, the model and its credentials belong to OpenCode.

ANTHROPIC_API_KEYFor warden review. When set, the boss model is Claude Opus.
OPENAI_API_KEYFor warden review. When it's set, OpenAI models do the worker calls. With only this key, OpenAI runs the whole review.
VOYAGE_API_KEYNeeded by warden init, except with --dry-run, to embed the repository with voyage-code-3. Without it, warden review selects context from cheaper signals.
GOOGLE_GENERATIVE_AI_API_KEYOptional. Gives a Google fallback when an Anthropic call fails transiently. Calls that use tools, which includes the review loop, don't fall back.

General

WARDEN_LOG_LEVELsilent, error, warn, info (the default), or debug.
WARDEN_ENV_FILEOne extra env file to load for this run.
WARDEN_CACHE_PATHWhere the SQLite cache lives. The default is <repo>/.warden/cache.sqlite. A relative path resolves against the current directory.
WARDEN_REACT_DOCTORSet to 1 to add the react-doctor rules to the deterministic phase. Off by default.

Review tuning

These variables affect warden review, the in-process loop. The OpenCode path takes its settings from command flags instead. See Connect OpenCode.

WARDEN_SECURITY_CONFIDENCE_FLOORA number from 0.0 to 1.0 that overrides the confidence bar for security findings. The default is 0.8. Tier 1 findings ignore it.
WARDEN_REVIEW_BOSS_ROUNDSThe boss loop's step limit, from 1 to 10. The default is 5.
WARDEN_REVIEW_WORKER_BUDGETThe most workers one review can dispatch. Unlimited by default.
WARDEN_WORKER_CONCURRENCY_STRONGHow many strong-tier workers can run at once. The default is 4.
WARDEN_WORKER_CONCURRENCY_CHEAPHow many cheap-tier workers can run at once. The default is 8.
WARDEN_REVIEW_REFRESH_MAX_USDA dollar cap on re-embedding stale files during a review. The default is 0.25.
WARDEN_SECURITY_WORKER_BUDGETA cap on workers for the deep security review.

Tracing

Warden can send review traces to a self-hosted Langfuse. Tracing is off unless both keys are set. Traces contain the source code under review, so by default Warden refuses any host that isn't on your machine.

LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEYTurn tracing on.
LANGFUSE_HOSTThe default is http://localhost:3200. Remote hosts are refused.
WARDEN_LANGFUSE_ALLOW_REMOTESet to 1 to allow a remote self-hosted instance on purpose.
WARDEN_LANGFUSE_CAPTURE_IORecords full prompts and completions. On by default when tracing is on. Set it to 0 for any CI or cloud run.

The local cache

Warden keeps its state in one SQLite file, .warden/cache.sqlite at the repository root. The file is gitignored. It holds the chunks, embeddings, and Merkle state for the index, the import graph, cached type-definition lookups, and a record of each review run. You can delete it at any time. warden init rebuilds the index, and everything else is filled in again as it's needed.

Your code stays on your machine except for three kinds of call: embeddings to Voyage when you run init, model calls to the provider you've configured, and advisory checks against OSV.dev. On the OpenCode path, everything the lane reads goes to the model you set up in OpenCode.