> 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/concepts/models-and-byok.md).

# Models & BYOK

Codna uses two credentials:

| Credential           | Env var                  | Authenticates                 | Used for                    |
| -------------------- | ------------------------ | ----------------------------- | --------------------------- |
| Engine / account key | `CODNA_API_KEY`          | Your Codna account (metering) | Talking to the Codna engine |
| Model key (BYOK)     | e.g. `ANTHROPIC_API_KEY` | Your LLM provider             | The agent's model calls     |

{% hint style="warning" %}
`CODNA_API_KEY` is not a model key. To run `codna fix` with your own model, add a provider key.
{% endhint %}

## Bring your own key

The provider key stays on your device, in the OS secure store (macOS Keychain, Windows Credential Manager, Linux Secret Service) via `keyring`. It's never written to `.env`, passed on the command line, or printed.

```bash
codna key set anthropic     # hidden prompt; the key is not echoed
codna key list              # shows which providers are stored (never the values)
codna key rm anthropic      # remove a stored key
```

For CI, pipe the secret in:

```bash
echo "$ANTHROPIC_API_KEY" | codna key set anthropic --stdin
```

### Supported providers

`codna key set` accepts an alias or the raw `*_API_KEY` name:

| Alias              | Environment variable |
| ------------------ | -------------------- |
| `anthropic`        | `ANTHROPIC_API_KEY`  |
| `openai`           | `OPENAI_API_KEY`     |
| `gemini`           | `GEMINI_API_KEY`     |
| `google`           | `GOOGLE_API_KEY`     |
| `groq`             | `GROQ_API_KEY`       |
| `mistral`          | `MISTRAL_API_KEY`    |
| `openrouter`       | `OPENROUTER_API_KEY` |
| `xai`              | `XAI_API_KEY`        |
| `cursor`           | `CURSOR_API_KEY`     |
| `codna` / `engine` | `CODNA_API_KEY`      |

### Resolution order

Codna resolves a provider key first-match-wins:

1. An environment variable (e.g. `ANTHROPIC_API_KEY`).
2. The OS keychain (anything set with `codna key set`).
3. A legacy `keys.txt` (dev/source checkout only; never read from an installed wheel).

Set `CODNA_DISABLE_KEYCHAIN=1` to skip the keychain and use environment variables only.

## Choosing a model

### Default

By default Codna uses its bundled planner, the sentinel model id `repository.verified_agentic_v1`. This isn't a specific provider model — it routes to the local agent-core runtime and takes the provider/model from your configuration. It's the default for `codna fix` and the Action's `model` input.

### `--model`

Pass a `provider/model_id` pair:

```bash
codna fix . --tests --apply --model openai/gpt-5.4
codna review . --pr 123 --model anthropic/claude-opus-4-8
```

A value with no slash is treated as a bare model id and paired with the command's default provider.

### Pin a model in `codna.yaml`

For a repo-wide default, add a `model:` block (`codna init` scaffolds one):

```yaml
model:
  provider: openai            # required when a model block is present
  key: env:OPENAI_API_KEY     # read from the environment; fails closed if unset
```

* `provider` is required and must be a supported alias, or the config is rejected.
* `key: env:NAME` reads `$NAME` at load time and fails closed if it's unset or empty. A plain value is used literally.
* The `model:` block applies to `codna fix`. `codna review` selects its model with the `--model` flag (or the provider default); `triage` and `secure` classification don't call a model.

## Managed vs. self-billed

* **BYOK:** your provider key bills to your own account, uncapped.
* **Managed:** an engine key (`CODNA_API_KEY`) draws on a Codna account allowance. The [GitHub App](/guides/github-app.md) uses this path — keyless per repo, metered against the linked org.

## See also

* [Configuration](/reference/configuration.md) — full `codna.yaml` and environment reference.
* [Operations](/reference/operations.md) — `codna status` shows key state.


---

# 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/concepts/models-and-byok.md?ask=<question>&goal=<endgoal>
```

`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.