Skip to content
KortixKortix
Esc
↑↓navigate↵open⌘Jpreview
On this page

Models

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

Kortix runs each session 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 feature flag, on by default where the platform offers it — check or toggle it in Settings → Experimental (operators can default a whole deployment off with LLM_GATEWAY_DEFAULT_ENABLED=false).

Turning the flag off is a fully supported path. The project then runs native OpenCode model management:

  • Your provider API keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY, …) are injected into the sandbox as ordinary env vars — add them on the Model settings page or as secrets. OpenCode connects each provider from its key automatically.
  • Model ids are OpenCode’s native provider/model refs, like anthropic/claude-opus-4-8. Managed bare ids and kortix/… refs do not exist off-gateway.
  • The model picker shows one list before and after the sandbox boots: the providers your keys connect, plus OpenCode Zen’s free models (OpenCode connects those without a key). Thinking effort is the composer’s thinking control (the model’s own variants); the gateway’s Generation defaults do not apply.
  • The gateway surfaces on this page — managed models, the model-defaults chain, budgets, logs — do not apply; OpenCode resolves the default model in the sandbox.

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

Disable providers or models

Open Customize → Models → Providers. Open the ⋯ menu in the Kortix row and choose Disable provider to use only your own providers. Kortix appears in the same list as other providers, with its model count and credit-billing description. Every provider uses the same menu. Only disabled providers show a status badge. Choose Enable provider from the menu to restore access.

Open the Models tab to enable or disable individual models. A disabled provider blocks all of its models, including models added later. Re-enabling the provider preserves individual model choices. Credentials stay saved throughout.

The project default and its provider cannot be disabled. Select a different enabled default first. Project managers can change access; readers can inspect it.

These controls apply to new requests through the Kortix gateway, including saved session selections and fallback candidates. A request already sent to an upstream finishes normally. Disabled targets return provider_disabled or model_disabled; choose an enabled model to continue. Native OpenCode mode does not use this gateway policy.

Existing picker-only visibility preferences remain separate. Resetting the model list does not remove explicit access restrictions.

Thinking effort

The composer’s thinking control sets the session’s model variant in both modes. The choices are the model’s own published tiers (models.dev reasoning_options), never a fixed ladder; a model without a knob shows no control. Auto clears the variant.

  • Native (gateway off): OpenCode applies the variant as the provider’s own request field.
  • Gateway on: the request carries reasoning_effort; the gateway maps it per upstream (OpenAI → reasoning_effort, Claude → adaptive thinking, OpenAI on Amazon Bedrock → Bedrock’s reasoning.effort request field). For an upstream it cannot map yet (Nova, Grok on Bedrock today) the value is dropped and the model runs at its own default.
  • Amazon Bedrock refuses the bare in-region id of most current models (“on-demand throughput isn’t supported”). The picker prefers the global. / regional inference-profile id when the catalog carries one, and the gateway retries a refused bare id once per profile prefix (global., us.).
  • The sandbox learns the project’s servable model set from the API at every boot (GET /v1/llm/models?scope=picker, the same composition as the web picker), so a model the picker offers always resolves in the runtime.
  • A project default per model lives in Customize → Gateway → Routing → Generation defaults (model_generation_config). It fills only a field the request left unset, so a session’s variant always wins.

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 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 for the trigger model: field.

Per-project model enablement

The project controls which models its pickers offer. By default, the newest model of each family is offered automatically. Kortix-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.

Models hidden by older picker preferences show Hidden from picker. Direct requests remain allowed. Open that model’s menu and choose Disable model to block inference too.

Provider model-count links open the Models tab. All provider groups appear together in the same list used to enable or disable models and set defaults. Search narrows the list. Connect a provider before managing its models.

Was this page helpful?