> For the complete documentation index, see [llms.txt](https://docs.codna.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.codna.ai/reference/configuration.md). # Configuration Environment variables Codna reads for model keys, GitHub writes, the local runtime, code memory and security autofix, and the codna.yaml file with its model, privacy, fix and review blocks. Codna is configured through environment variables, the OS keychain (`codna key set`), and an optional `codna.yaml` file in the working directory. A packaged install needs no database, Docker, Node, Bun, or separate install of anything else. `pip install codna` installs the whole product; `pip install "codna[mcp]"` adds the MCP server. ## Quick Start Most local users set one model provider key: ```bash codna key set openai # or export OPENAI_API_KEY=... / ANTHROPIC_API_KEY=... / GEMINI_API_KEY=... codna fix . --issue "the failing test in X is ..." ``` To open pull requests, add a GitHub write token: ```bash export GITHUB_TOKEN=... # contents:write + pull-requests:write codna fix https://github.com/owner/repo.git --issue "..." --open-pr ``` ## Environment Variables All variables are read from the process environment. `keys.txt` is a source-checkout development convenience only; packaged users use environment variables or `codna key set`. ### Model Keys and the Codna Key | Variable | Purpose | Required When | | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ANTHROPIC_API_KEY` | Anthropic provider key (alias `anthropic`). | Model calls with an Anthropic model, or a model with no provider prefix. | | `OPENAI_API_KEY` | OpenAI provider key (alias `openai`). | Model calls with an OpenAI model. | | `GEMINI_API_KEY` | Gemini provider key (alias `gemini`). | Model calls with a Gemini model. | | `GOOGLE_API_KEY` · `GROQ_API_KEY` · `MISTRAL_API_KEY` · `OPENROUTER_API_KEY` · `XAI_API_KEY` · `CURSOR_API_KEY` | Other provider keys (aliases `google`, `groq`, `mistral`, `openrouter`, `xai`, `cursor`). | Model calls with that provider. | | `CODNA_API_KEY` | Your Codna key, stored by `codna login`. | Only when Codna is pointed at a remote engine (`CODNA_ENGINE_URL`). Local `triage`, `fix`, `review` and `secure` do not read it. The GitHub App meters against your linked account instead. | | `CODNA_ENGINE_URL` | A remote Codna engine to send work to. | Unset for local runs. | Use `codna key set ` when you prefer OS keychain storage instead of shell exports: ```bash printf '%s' "$OPENAI_API_KEY" | codna key set openai --stdin codna key list ``` See [Models & BYOK](/concepts/models-and-byok.md) for the alias table, resolution order, and model selection. ### GitHub Write Credentials These are needed only by commands that push a branch, open a pull request, or post a review. Read-only `triage`, `review` without `--post`, and `secure` classification do not need them. | Variable | Purpose | | -------------------- | ----------------------------------------------------------------------------------------- | | `GITHUB_TOKEN` | Write-scope token used to push a branch, open a pull request, or post a review. | | `CODNA_GITHUB_TOKEN` | Alternate write-token name checked before `GITHUB_TOKEN` by `fix`, `review` and `secure`. | Per-command precedence: * `codna fix --open-pr`: `--github-token`, then `CODNA_GITHUB_TOKEN`, then `GITHUB_TOKEN`. * `codna review --post`: `--github-token`, then `CODNA_GITHUB_TOKEN`, then `GITHUB_TOKEN`. * `codna secure --open-pr`: `--github-token`, then `CODNA_GITHUB_TOKEN`, then `GITHUB_TOKEN`. * `codna secure-open-pr`: `--github-token`, then `GITHUB_TOKEN`. {% hint style="warning" %} Codna scrubs write tokens from the environments that run untrusted repository code. Keep write tokens in PR-opening steps, not in scanner, build or test steps. {% endhint %} ### Local Runtime Codna runs on your machine. These variables control where its state lives and which loopback ports it uses. | Variable | Purpose | Default | | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `CODNA_RUNTIME_ROOT` | Root for Codna runtime state, logs, saved reports and the key index. | `~/.codna` | | `CODNA_PORT_BASE` | Base port for the local runtime on `127.0.0.1`. Codna uses this port and the next one (`18600`, `18601`). Change it only to avoid a port collision. | `18600` | | `CODNA_AGENT_CORE_READY_TIMEOUT_SECONDS` | Time to wait for the local runtime to become ready. | `120` | | `CODNA_DISABLE_KEYCHAIN` | Set to `1`, `true`, `yes`, or `on` for headless runs that must not touch the OS keychain. | unset | Useful inspection commands: ```bash codna status codna doctor codna doctor --start-stack codna doctor --stop-stack ``` ### Review window Each `codna review` turn is sized for its pull request and learns from earlier reviews. See [codna review § Large pull requests](/guides/review.md#large-pull-requests-and-the-review-window). Tuning only; the defaults need no setup. | Variable | Purpose | Default | | ----------------------------- | ------------------------------------------------------------------------------------- | ------------------------ | | `CODNA_REVIEW_HISTORY_DIR` | Directory holding the recorded review turns the forecast learns from. | `~/.codna/review-budget` | | `CODNA_REVIEW_BUDGET_EPSILON` | Accepted probability that a review turn exceeds its budget; smaller grants more time. | `0.02` | ### Code Memory Code memory works with no configuration. These variables cover headless and CI runs and ranking tuning. See [Code Memory](/concepts/memory.md). | Variable | Purpose | | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | `CODNA_TELYS_LICENSE_JWT` | Inline license for CI/headless runs. | | `CODNA_TELYS_LICENSE_PATH` | Path to a license file. | | `CODNA_TELYS_MEMORY_ROOT` | Where the MCP server keeps recall indexes. Default `~/.codna/telys-memory`. | | `CODNA_MEMORY_RERANK`, `CODNA_MEMORY_RERANK_ALPHA`, `CODNA_MEMORY_RERANK_K`, `CODNA_MEMORY_TEST_DOWNWEIGHT` | Ranking tuning. See [Code Memory § Tuning](/concepts/memory.md#tuning). | ### Security Autofix These apply to the `secure` command family. | Variable | Purpose | Default | | ------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------- | | `CODNA_MODEL_PACK_DIGEST` | Digest pinned into security analyses. | `sha256:` + 64 zeros | | `CODNA_ATTESTATION_KEY` | Shared HMAC secret used by `secure --fix` and verified by `secure-open-pr`. | generated for a local worker; required for `secure-open-pr` | | `CODNA_FIX_MODEL` | Patch-generation model for `codna secure --engine local --fix`. | generator default | `secure-open-pr` fails fast if the attestation key is missing: ``` set CODNA_ATTESTATION_KEY (shared with the worker) to verify the attestation. ``` ### CI fleet gate `codna ci` keeps a self-hosted runner fleet inside a chosen share of one machine. See [CI fleet gate](/reference/adaptive-concurrency.md) for `CODNA_CI_CPU_SHARE` and the other variables. ### GitHub App The hosted GitHub App needs no local configuration. Install it on your repositories and it works. It reads the repository's own `codna.yaml` for the `review:` and `fix:` blocks. See [GitHub App](/guides/github-app.md) for triggers, the permissions it requests, and metering. ## Config file (`codna.yaml`) Codna loads a config file from the working directory: `./codna.yaml`, then `./.codna.yaml` (JSON is accepted if PyYAML is not installed). Point at a specific file with `--config PATH`, or scaffold one with `codna init`. The file is applied per command. `codna fix` applies the `model:`, `privacy:` and `fix:` blocks; `triage`, `review`, and `secure` load only the `privacy:` posture, and `codna review` also reads the `review:` block from the pull request's head. `codna review` selects its model with the `--model` flag, not the `model:` block. An invalid file fails closed with a `config_error`. ```yaml model: provider: openai # a keystore alias: openai, anthropic, gemini, … key: env:CODNA_MODEL_KEY # env:NAME reads $NAME; a literal value is used as-is privacy: egress: fail-closed # opt-in: refuse to run tests without egress denial (also: deny, none) redact_secrets: true # false is ignored with a warning; redaction cannot be disabled fix: test_command: pixi run test # how `codna fix --tests` runs this repository's tests (default: pytest) review: min_confidence: 0.75 max_findings: 10 approve: true # false: never post an Approve blocking: enabled: false severities: [high] categories: {correctness: true, security: true, performance: true} ignore_paths: [] rules_file: .codna/review.md effort: medium # low | medium | high incremental: true ``` `model.provider` maps to that provider's `*_API_KEY`; a `key: env:NAME` that is unset fails closed. See [Models & BYOK](/concepts/models-and-byok.md) for the full model-selection reference. `privacy.egress: fail-closed` is opt-in. When set, Codna refuses to run repository tests unless it can deny them network access at the kernel level (Linux), and `codna review` makes no registry lookups. Secret redaction is always on. See [Privacy and data](/concepts/privacy.md). `fix.test_command` is read from the repository being fixed (committed alongside its code, so the GitHub App sees it too) and tells `codna fix --tests` how to run the tests when plain `pytest` is not how they run. The command runs from the repository root inside Codna's sandbox; any pytest it reaches writes the report Codna reads for per-test ids. Precedence and the runners Codna detects on its own are in [GitHub App § Test command per repository](/guides/github-app.md#test-command-per-repository). `review:` is documented key by key in [codna review § Noise control and review policy](/guides/review.md#noise-control-and-review-policy). ## Common Scenarios ### Local Triage and Fix Preview ```bash codna key set openai codna triage . --issue "checkout total is wrong when a coupon is applied" codna fix . --issue "tests/test_checkout.py::test_total_with_coupon fails" ``` Your source stays on the host. When you run a model, Codna sends only the evidence bundle to your chosen provider. ### Open a PR from CI ```yaml permissions: contents: write pull-requests: write jobs: codna-fix: runs-on: ubuntu-latest steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - uses: thyn-ai/codna-action@3fbffb7b4f9e5d93d4b8a59eee13520698fbbe3f # v1 env: OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} with: issue: "CI failed on ${{ github.ref_name }}" model: openai/gpt-5 ``` The Action installs the public `codna` package from PyPI and runs the same `codna fix` you run on your machine. The only secret it needs is the provider key. See [GitHub Action](/guides/github-action.md). ### Privilege-Separated Security Remediation ```bash # Worker domain: scanner/build/test/fix. No write token here. export OPENAI_API_KEY=sk-... export CODNA_ATTESTATION_KEY="$(openssl rand -hex 32)" codna secure . --from-sarif results.sarif --engine remote --fix \ --verification codna-security.yaml --evidence-dir ./evidence ``` ```bash # Writer domain: verifies the evidence bundle and opens the draft PR. Runs no repo code. export CODNA_ATTESTATION_KEY="$SAME_KEY_AS_WORKER" export GITHUB_TOKEN="$WRITE_TOKEN" codna secure-open-pr --evidence ./evidence --repo-slug owner/repo --base-branch main ``` ## Troubleshooting See [Troubleshooting](/reference/troubleshooting.md) for every message and its one-line fix. Fatal errors print as JSON on stderr; the `message` field carries the text. For command syntax and flags, see the [CLI Reference](/reference/cli.md). For editor integration, see [MCP Server](/guides/mcp.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.codna.ai/reference/configuration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.