# Models

How Kortix picks a model, and how billing works for managed vs. your-own-key models.

Canonical page: https://kortix.com/docs/project/models

Kortix runs each [session](/docs/work/sessions) on a model. This page
explains managed models vs. your own provider key (BYOK), how Kortix picks a
model automatically, and two billing gotchas to know.

This page applies to projects with the LLM Gateway on. LLM Gateway is an
experimental setting, and it is on by default for cloud projects. Check or
toggle it in Customize → Experimental.

## Managed models and BYOK

A model id has one of three shapes:

- **Managed** — a bare id, like `claude-opus-4.8` or `glm-5.2`. Kortix
  supplies the credentials. Cloud accounts pay with Kortix credits.
- **BYOK** — a `provider/model` id, like `anthropic/claude-opus-4-8`. You
  supply the key. Your provider account pays.
- **ChatGPT** — a `codex/<id>` id. You connect your ChatGPT plan once through
  OAuth, and it pays.

Connect a BYOK key on the project's Model settings page, or set the
provider's env var directly as a [secret](/docs/project/secrets).

## How auto picks a model

Set no model, and Kortix resolves one through five layers, in order. (The
id `auto` covers this same behavior, but it is not yet a selectable option
in the model picker.)

1. An explicit pin — a session, channel, or trigger's own `model:` field.
2. The [agent's](/docs/project/agents) default for this project.
3. The project's default.
4. The account's default.
5. The platform default.

Kortix uses the first layer that has a value it can still serve. A saved
default that stops working — a disconnected key, a retired model — is
skipped automatically. A session never dies from a stale default. See the
[manifest reference](/docs/project/manifest) for the trigger `model:`
field.

> **Billing surprises on BYOK**
> Two costs are easy to miss on a paid cloud account:
>
> - **Platform fee.** Kortix adds a 10% fee, billed as credits, on top of what
> your own provider charges. Free-tier and self-hosted accounts are exempt.
> - **Silent failover.** If your BYOK key hits a rate limit or billing error
> mid-turn, Kortix retries on a managed model and bills your credits instead
> of failing the session.
>
> If you see credit charges on a BYOK-only project, check these two causes
> before reporting a billing bug.

## Shared, not private, keys

A connected provider key applies to the whole project. There is no private,
per-user key — setting a personal override for a provider key fails with a
`llm_credentials_project_wide` error. Update the shared key on the
[secrets](/docs/project/secrets) page instead.