> 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 Codna is configured through process environment variables, the OS keychain (`codna key set`), and an optional `codna.yaml` file in the working directory. A packaged install needs no local database, Docker, Node, Bun, or separate Telys install. `pip install codna` installs the CLI, MCP server, local repository-intelligence SDK/core, packaged Telys runtime/license, and self-contained agent-core sidecar. ## Quick Start Most local users set one Codna key plus one model-provider key: ```bash export CODNA_API_KEY=... # Codna license / metering key export OPENAI_API_KEY=... # or 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 should use environment variables or `codna key set`. ### Codna and Model Keys | Variable | Purpose | Required When | | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | `CODNA_API_KEY` | Codna license / metering key. | `triage`, `fix`, `review`, `secure`, MCP, Action, and App flows that require an authenticated Codna account. | | `OPENAI_API_KEY` | OpenAI provider key (alias `openai`). | Local model execution with an OpenAI model. | | `ANTHROPIC_API_KEY` | Anthropic provider key (alias `anthropic`). | Local model execution with an Anthropic model. | | `GEMINI_API_KEY` | Gemini provider key (alias `gemini`). | Local model execution with a Gemini model. | | `GOOGLE_API_KEY` · `GROQ_API_KEY` · `MISTRAL_API_KEY` · `OPENROUTER_API_KEY` · `XAI_API_KEY` · `CURSOR_API_KEY` | Other managed provider keys (aliases `google`, `groq`, `mistral`, `openrouter`, `xai`, `cursor`). | Local model execution with that provider. | 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 ``` These are the providers `codna key set` will store. 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 and open a pull request. Read-only `triage`, `review` without posting, and `secure` classification do not need them. | Variable | Purpose | | -------------------- | --------------------------------------------------------------------------- | | `GITHUB_TOKEN` | Write-scope token used to push a branch and open a pull request. | | `CODNA_GITHUB_TOKEN` | Alternate write-token name checked before `GITHUB_TOKEN` by `fix`/`secure`. | Per-command precedence: * `codna fix --open-pr`: `--github-token`, then `CODNA_GITHUB_TOKEN`, then `GITHUB_TOKEN`. * `codna secure --fix --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 worker environments that run untrusted repository code. Keep write tokens in PR-opening steps, not scanner/build/test steps. {% endhint %} ### Local Runtime The default runtime is local and packaged. Repository intelligence runs in-process through the bundled SDK/core. Verified planning starts or reuses the packaged agent-core sidecar on loopback when needed. Step state is stored as local files under the runtime root. | Variable | Purpose | Default | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | | `CODNA_RUNTIME_ROOT` | Root for Codna runtime state, logs, and local artifacts. | `~/.codna` | | `CODNA_PORT_BASE` | Base port for the local runtime: the engine uses this port, the sidecar uses `base + 1` (18601). Change it only to avoid a port collision. | `18600` | | `CODNA_AGENT_CORE_READY_TIMEOUT_SECONDS` | Time to wait for packaged agent-core readiness. | `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 ``` ### Telys License Codna wheels bundle the Telys runtime and an OEM license, so on-device memory works with no configuration. These variables cover headless/CI and enterprise licensing: | Variable | Purpose | | -------------------------- | ------------------------------------------- | | `CODNA_TELYS_LICENSE_JWT` | Inline Telys license, for CI/headless runs. | | `CODNA_TELYS_LICENSE_PATH` | Path to a Telys license file. | ### 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 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. ``` ### GitHub App The hosted GitHub App needs no local configuration — install it on your repositories and it works. See [GitHub App](/guides/github-app.md) for triggers, the permissions it requests, and metering. ## Config file (`codna.yaml`) Codna also loads a config file from the working directory: `./codna.yaml`, then `./.codna.yaml` (JSON is accepted if PyYAML isn't installed). Point at a specific file with `--config PATH`, or scaffold one with `codna init`. The file is applied per command — `codna fix` applies both the `model:` and `privacy:` blocks, while `triage`, `review`, and `secure` load only the `privacy:` posture (`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 # sets CODNA_REQUIRE_EGRESS_DENY=1 (also: deny, none) redact_secrets: true # false is ignored with a warning; redaction cannot be disabled ``` `model.provider` maps to that provider's `*_API_KEY` and sets `CODNA_AGENT_PROVIDER`; a `key: env:NAME` that is unset fails closed. See [Models & BYOK](/concepts/models-and-byok.md) for the full model-selection reference. ## Common Scenarios ### Local Triage and Fix Preview ```bash export CODNA_API_KEY=ck_live_... export OPENAI_API_KEY=sk-... 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 a focused 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@v7 - uses: thyn-ai/codna-action@v1 env: OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} with: api-key: ${{ secrets.CODNA_API_KEY }} issue: "CI failed on ${{ github.ref_name }}" model: openai/gpt-5 ``` The Action installs the public `codna` package from PyPI and runs the same packaged local runtime as the CLI. ### Privilege-Separated Security Remediation ```bash # Worker domain: scanner/build/test/fix. No write token here. export CODNA_API_KEY=ck_live_... export OPENAI_API_KEY=sk-... export CODNA_ATTESTATION_KEY="$(openssl rand -hex 32)" codna secure . --from-sarif results.sarif --verification codna-security.yaml --fix ``` ```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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` 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 optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.