# Models

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

Canonical page: https://app.teachervoiceai.com/docs/project/models

Machine runs each [session](/docs/work/sessions) on a model. This page
explains managed models vs. your own provider key (BYOK), how Machine picks a
model automatically, and how each route is billed.

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

## Managed models and BYOK

A model id has one of three shapes:

- **Managed** — a bare id, like `grok-4.6` or `deepseek-v4-pro-0813`. Machine
  supplies the credentials. Cloud accounts pay with Machine 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 Machine 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.

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

> **Connected providers use zero Machine credits**
> Machine sends BYOK requests only through your connected provider credentials.
> Machine records token usage for observability but applies zero markup and
> deducts zero Machine credits. If your provider returns a rate-limit, quota, or
> billing error, the request fails with that provider error instead of silently
> switching to a managed model.

## Per-project model enablement

The project controls which models its pickers offer. By default, the newest
model of each family is offered automatically. Machine-managed models and any
model your project's defaults or routing policy reference are always offered —
a guard never prunes them.

You can override the default for individual models on the **Manage models**
page (Customize → Models). An exception is stored per project and takes effect
immediately. The session model picker and the command palette hide anything
you turn off; new models stay on by default as the catalog grows.

Enablement governs what is offered, not what is served: a request that names a
disabled model outright (for example through the raw API) still runs. The
project's default model cannot be turned off — set a different default first.

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