Models
How Machine picks a model, and how billing works for managed vs. your-own-key models.
Machine runs each session 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.6ordeepseek-v4-pro-0813. Machine supplies the credentials. Cloud accounts pay with Machine credits. - BYOK — a
provider/modelid, likeanthropic/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.
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.)
- An explicit pin — a session, channel, or trigger's own
model:field. - The agent's default for this project.
- The project's default.
- The account's default.
- 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 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 page instead.