# Models

How Machine picks a model, the models Machine manages, and how billing works for managed models, your own keys, and your own plans.

Canonical page: https://themachine.myapps.ai/docs/project/models

Machine runs each [session](/docs/work/sessions) on a model. This page
explains the kinds of model ids, how Machine picks a model automatically, how
each route is billed, and which models Machine manages today.

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 **Settings → Experimental**.

## Model id shapes

A model id has one of five shapes:

| Shape | Example | Who supplies access | Who pays |
|---|---|---|---|
| **Managed** — a bare id | `grok-4.6`, `claude-sonnet-5.5` | Machine | Your Machine credits |
| **BYOK** — `provider/model` | `anthropic/claude-opus-4-8` | Your provider key | Your provider account |
| **ChatGPT plan** — `codex/` | `codex/gpt-5.6-sol` | Your ChatGPT plan, connected once | Your ChatGPT plan |
| **Claude subscription** — `claude-subscription/` | `claude-subscription/opus` | Your Claude Pro or Max plan | Your Claude plan |
| **Cursor plan** — `cursor/` | `cursor/` plus an id from your Cursor catalog | Your Cursor plan | Your Cursor plan |

The three plan shapes cost zero Machine credits. Usage counts against your
own plan's limits instead.

Connect a BYOK key in **Settings → Models → API keys**, or set the provider's
env var directly as a [secret](/docs/project/secrets). Plans connect from the
same **API keys** list: ChatGPT with **Connect ChatGPT** on the **OpenAI** row,
and Claude and Cursor as described below.

## Use your Claude subscription

Machine runs the unmodified Claude Code CLI inside your session's workspace,
signed in to your own Claude account. The login stays in that workspace.

1. Open **Settings → Models → API keys**, find the **Anthropic** row, and
   click **Connect Claude subscription**.
2. Click **Open Anthropic sign-in** and log in with your Claude account.
3. Anthropic shows a code. Paste it into the dialog and click **Submit code**.

The connect button shows only to people who can edit the project. Connecting
needs a workspace to sign in. If no session is open on the page,
Machine uses your most recent session's workspace and wakes it if needed. You
can connect only from your own sessions — your Claude login never lands in a
teammate's workspace.

**Each session signs in on its own.** The project remembers that you connected
Claude, but a new session's workspace holds no login yet. In that session the
model picker shows a **Sign in to use Claude here** row in place of the Claude
models. Pick it to sign that session in. The login survives stops and restarts
of the session.

The subscription models appear in the picker as, for example, **Claude Opus
5.5 (Subscription)**, with a **Sub** tag instead of a price:

| Picker name | Model id |
|---|---|
| Claude Fable 5.1 (Subscription) | `claude-subscription/fable` |
| Claude Opus 5.5 (Subscription) | `claude-subscription/opus` |
| Claude Sonnet 5.5 (Subscription) | `claude-subscription/sonnet` |
| Claude Haiku 4.5 (Subscription) | `claude-subscription/haiku` |

A Claude subscription request never falls back to a Machine-managed model.
If your plan runs out, the request fails with an error instead of spending
your credits.

### claude.ai connectors

The sign-in dialog has a switch, **Use my claude.ai connectors in this
session**. It is off by default, and each new session starts with it off. When
you turn it on, Claude can use the connectors on your claude.ai account (Gmail,
Drive, and others) in that session. Those connectors run outside Machine's
approvals and activity log, including in scheduled runs. Leave it off unless
you need them.

## Use your Cursor plan

1. Open **Settings → Models → API keys** and find the **Cursor** row.
2. Choose **Sign in with Cursor** to log in on cursor.com, or **Paste a key**
   to use an API key from your Cursor dashboard.

Sign-in runs inside one of your sessions, so open a session in the project
first. After that, your Cursor models appear in the model picker in every one
of your sessions in the project. Only you see them — teammates connect their
own Cursor.

Each Cursor model is named after Cursor's own name with **via Cursor** added,
for example **Auto via Cursor**. Machine bills these turns at $0. Each step
runs Cursor's own harness, which uses about 20–40k input tokens of your
Cursor plan. Turns go to Cursor under your Cursor account's privacy settings.
Turn on Privacy Mode in Cursor if you do not want Cursor to train on them.

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

## Reasoning effort

The effort control in the composer saves a reasoning effort for the selected
model on this project. Machine sends that saved effort with every request to
that model.

**The saved effort wins over the request.** If you call the gateway directly
and send `reasoning_effort` (or `reasoning.effort`), a saved effort for that
model replaces your value. With no saved effort, your value is used. Either
way, Machine clamps the effort to the levels the model publishes. Temperature,
`top_p`, and max tokens work the other way round: a value in the request wins
over the saved one.

To see what a request really sent, open **Settings → Models → Logs** and pick
the request. Its **Reasoning effort** row shows the effort that was requested,
whether it came from the request or the project setting, and what was sent.
For example, `max requested · not sent (the model has no such level)` means
the model has no `max` level, so no effort went upstream. Requests logged
before this row existed show nothing.

## 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 in **Settings → Models →
Models**, or from the **Manage models** button in the model picker. 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.

Plan connections work differently. A Cursor connection belongs to the person
who connected it, and a Claude subscription login lives in each session's own
workspace.

## Machine-managed models

These are the managed models in Machine's built-in catalog, grouped by tier.
Use the id in a `model:` field or an API request. Machine routes every managed
model through OpenRouter and bills it to your Machine credits. The model
picker is the live view: a deployment can change the list, and your project's
enablement settings can hide models from the picker.

When nothing else sets a model, the built-in platform default is Claude Haiku
4.5 (`claude-haiku-4.5`). A deployment can set a different platform default.

| Model | Id | Tier | Context | Images |
|---|---|---|---|---|
| Claude Fable 5 | `claude-fable-5` | Flagship | 1M | Yes |
| Claude Fable 5.1 | `claude-fable-5.1` | Flagship | 1M | Yes |
| Claude Opus 4.8 | `claude-opus-4.8` | Flagship | 1M | Yes |
| Claude Opus 5 | `claude-opus-5` | Flagship | 1M | Yes |
| Claude Opus 5.5 | `claude-opus-5.5` | Flagship | 1M | Yes |
| Gemini 4 Argon | `gemini-4-argon` | Flagship | 1M | Yes |
| GLM 5.3 | `glm-5.3` | Flagship | 1M | No |
| GPT-5.5 Pro | `gpt-5.5-pro` | Flagship | 922k | Yes |
| GPT-5.6 Sol | `gpt-5.6-sol` | Flagship | 1.05M | Yes |
| GPT-5.6 Sol Pro | `gpt-5.6-sol-pro` | Flagship | 1.05M | Yes |
| GPT-6 Astra | `gpt-6-astra` | Flagship | 1.05M | Yes |
| GPT-6 Astra Pro | `gpt-6-astra-pro` | Flagship | 1.05M | Yes |
| GPT-6 Sol | `gpt-6-sol` | Flagship | 1.05M | Yes |
| GPT-6 Sol Pro | `gpt-6-sol-pro` | Flagship | 1.05M | Yes |
| GPT-6.1 Sol | `gpt-6.1-sol` | Flagship | 1.05M | Yes |
| GPT-6.1 Sol Pro | `gpt-6.1-sol-pro` | Flagship | 1.05M | Yes |
| Grok 4.5 | `grok-4.5` | Flagship | 500k | Yes |
| Grok 4.6 | `grok-4.6` | Flagship | 500k | Yes |
| Grok 4.7 | `grok-4.7` | Flagship | 500k | Yes |
| Inkling | `inkling` | Flagship | 524k | Yes |
| Kimi K3 | `kimi-k3` | Flagship | 1M | Yes |
| Muse Wonder | `muse-wonder` | Flagship | 1M | Yes |
| Claude Haiku 4.5 | `claude-haiku-4.5` | Balanced | 200k | Yes |
| Claude Sonnet 4.6 | `claude-sonnet-4.6` | Balanced | 1M | Yes |
| Claude Sonnet 5 | `claude-sonnet-5` | Balanced | 1M | Yes |
| Claude Sonnet 5.5 | `claude-sonnet-5.5` | Balanced | 1M | Yes |
| DeepSeek V4 Flash | `deepseek-v4-flash` | Balanced | 1M | No |
| DeepSeek V4 Pro | `deepseek-v4-pro` | Balanced | 1M | No |
| DeepSeek V4 Pro 0813 | `deepseek-v4-pro-0813` | Balanced | 1M | No |
| Gemini 3.1 Pro | `gemini-3.1-pro` | Balanced | 1M | Yes |
| Gemini 3.5 Flash | `gemini-3.5-flash` | Balanced | 1M | Yes |
| Gemini 3.6 Flash | `gemini-3.6-flash` | Balanced | 1M | Yes |
| Gemini 3.7 Flash | `gemini-3.7-flash` | Balanced | 1M | Yes |
| Gemini 3.8 Flash | `gemini-3.8-flash` | Balanced | 1M | Yes |
| GLM 5.2 | `glm-5.2` | Balanced | 1M | No |
| GPT-5.5 | `gpt-5.5` | Balanced | 1.05M | Yes |
| GPT-5.6 Terra | `gpt-5.6-terra` | Balanced | 1.05M | Yes |
| GPT-5.6 Terra Pro | `gpt-5.6-terra-pro` | Balanced | 1.05M | Yes |
| Grok 4.20 | `grok-4.20` | Balanced | 2M | Yes |
| Kimi K2.6 | `kimi-k2.6` | Balanced | 262k | Yes |
| MiMo V2.6 Pro | `mimo-v2.6-pro` | Balanced | 1M | Yes |
| MiMo V2.6 Pro UltraSpeed | `mimo-v2.6-pro-ultraspeed` | Balanced | 1M | Yes |
| MiniMax M3 | `minimax-m3` | Balanced | 1M | Yes |
| Mistral Large 4 | `mistral-large-4` | Balanced | 524k | Yes |
| Muse Spark 1.1 | `muse-spark-1.1` | Balanced | 1M | Yes |
| Muse Spark 1.2 | `muse-spark-1.2` | Balanced | 1M | Yes |
| Muse Spark 1.3 | `muse-spark-1.3` | Balanced | 1M | Yes |
| Qwen3.7 Max | `qwen3.7-max` | Balanced | 1M | No |
| Qwen3.8 Max | `qwen3.8-max` | Balanced | 1M | Yes |
| Claude Haiku 5.5 | `claude-haiku-5.5` | Fast | 1M | Yes |
| DeepSeek V4 Flash 0731 | `deepseek-v4-flash-0731` | Fast | 1M | No |
| Gemini 3.5 Flash Lite | `gemini-3.5-flash-lite` | Fast | 1M | Yes |
| GLM 5.3 Flash | `glm-5.3-flash` | Fast | 1M | Yes |
| GLM 5.3 FlashX | `glm-5.3-flashx` | Fast | 1M | Yes |
| GPT-5.6 Luna | `gpt-5.6-luna` | Fast | 1.05M | Yes |
| GPT-5.6 Luna Pro | `gpt-5.6-luna-pro` | Fast | 1.05M | Yes |
| GPT-6 Luna | `gpt-6-luna` | Fast | 1.05M | Yes |
| GPT-6 Luna Pro | `gpt-6-luna-pro` | Fast | 1.05M | Yes |
| GPT-OSS 20B | `gpt-oss-20b` | Fast | 131k | No |
| MiMo V2.6 Flash | `mimo-v2.6-flash` | Fast | 1M | Yes |

**Context** is the model's context window in tokens. **Images** says whether
the model accepts image input.