Models

Kortix-managed models, your own provider keys and subscriptions, how the default is chosen, routing, budgets, and calling the LLM gateway from other tools.

A model is the LLM that a session’s agent runs on. A project can use Kortix-managed models, your own provider API keys, and a ChatGPT or OpenCode subscription. This page is for the people who choose models, connect keys, and control model spend in a project.

How a session gets a model

Every model request goes through the LLM gateway. The gateway finds the credentials, applies the project’s routing, access rules and budgets, and records the cost. A model id has one of three shapes:

Inside the sandbox, OpenCode shows every gateway model under the kortix provider, for example kortix/glm-5.3-flash. The gateway removes the kortix/ prefix. Use the bare id everywhere else.

The catalog comes from models.dev and the Codex model list. The API refreshes it every hour, so a new provider model appears without a Kortix release.

Kortix-managed models

Kortix managed models are the models Platinum Inference offers. You need no key. The picker shows the current list, with each model’s context window, image support and price. On 2026-10-21 the list was:

• The picker lists them under Kortix. The platform default is the first model Platinum Inference lists, unless the operator sets one.
• A session or default that names a retired model (for example kimi-k3) runs on its successor.
• Managed models need the Credits plan or Enterprise. On Free, every managed model, the platform default included, returns plan_upgrade_required.
• Platinum Inference serves every managed model, only through inference providers with zero data retention.
• Managed requests use credits. See Plans & credits.
• The managed lineup has no OpenAI or Anthropic models. Use your own key or a ChatGPT subscription for them.
• A self-hosted instance has no managed models. Connect your own providers.

Connect your own provider

Open Customize → Models → Providers and choose a provider. Or use the CLI on the linked project:

kortix providers set anthropic            # reads the key from stdin
kortix providers set openai sk-...        # key as an argument
kortix providers set bedrock --region us-east-1
kortix providers ls                       # what is connected
kortix providers rm anthropic             # remove the key and any login

kortix providers set stores the key as an encrypted project secret under the provider’s key name:

Other models.dev providers connect in Providers with the key name the form shows. When several providers list the same key name, the provider that owns the name keeps it. Each other provider reads <PROVIDER_ID>_API_KEY, for example ZAI_CODING_PLAN_API_KEY or MOONSHOTAI_CN_API_KEY.

Sign in instead of a key. Three providers take a device-code login:

kortix providers login openai        # ChatGPT Plus or Pro
kortix providers login opencode      # OpenCode Zen
kortix providers login opencode-go   # OpenCode Go

In the web app, use Connect ChatGPT and Connect OpenCode Go. The OpenCode Zen login runs only from the CLI. Zen and Go each need their own login. An OpenCode login lasts 30 days, and Kortix renews it one day before it expires. When a renewal is refused, requests return provider_reauth_required: sign in again.

A custom endpoint. For a self-hosted or unlisted OpenAI-compatible endpoint, open the Custom tab. Enter a provider id, a name, the base URL and one or more models (an id and a name each). Kortix stores the endpoint in the project. The gateway calls <base_url>/chat/completions with the OpenAI chat-completions format. The key is optional: Kortix saves it as the project secret CUSTOM_<ID>_API_KEY and sends it as a Bearer token. Budgets, logs, access rules and routing apply as for any other model. Kortix charges no credits for a custom endpoint. Both harnesses, OpenCode and pi, can use its models. A model id is <id>/<model>, for example my-vllm/qwen-3.

From the CLI:

printf %s "$KEY" | kortix providers custom set my-vllm \
  --base-url https://llm.example.com/v1 --model "qwen-3=Qwen 3" --key-stdin
kortix providers custom ls
kortix providers custom rm my-vllm

set creates or replaces the endpoint. --model <id>[=<name>] repeats and replaces the model list. --name <name> defaults to the id. --key-stdin reads the key from stdin. rm removes the endpoint and its key.

• The provider id cannot be a catalog provider id such as openai: that returns reserved_provider_id.
• The gateway refuses a base URL on a private, loopback or link-local address. On a self-hosted deployment, list the host in the API environment variable KORTIX_LLM_CUSTOM_PROVIDER_ALLOW_HOSTS (comma-separated) to allow it.
• A key saved by the earlier snippet flow, with no endpoint stored, shows as Add endpoint in the Custom tab. Add the base URL and models to use it.

Your provider bills a request that runs on your own key or subscription. Kortix charges nothing for the first $1,000 of key usage a month at list price, then 5% of each request’s list price, from credits (Credits). A ChatGPT subscription and OpenCode Go are never charged. The one other charge is a Kortix model that you put in your own fallback chain: see Routing and fallback.

How the default is chosen

A session that names no model uses the first of these that is set:

1. Explicit pin. The model of the session, the channel or the trigger (model:).
2. Agent pin. kortix agents model <agent> <model-id>. --clear removes it.
3. Project default. kortix models default <model-id>.
4. Account default. kortix models default <model-id> --account. It applies to every project in the account that has no project default.
5. Platform default. deepseek-v4.1-flash on Kortix Cloud.

The model: field in the agent file is not in this chain. It applies only to a prompt that names no model:

• The web composer names a model on every prompt: your pick, else the chain above. There the agent file’s model: does not apply.
• On OpenCode, a prompt that names no model runs on the agent file’s model:. The chain’s model applies to an agent whose file sets none.
• On pi, the session runs on the chain’s model. A prompt that switches to another agent and names no model runs on that agent’s model:.

A stale default never fails a session. A less specific default is not tried when a more specific one cannot run:

• An explicit pin that the project cannot run falls through to the defaults.
• A default that cannot run, for example after its key was removed, falls back to a model of another connected provider, then to the platform default.
• On the Free plan, a default that names a managed model falls back to your connected ChatGPT subscription, then a connected provider key. With neither, the session has no model until you connect one.

kortix models default prints the chain and what it resolves to. kortix models default --clear [--account] removes a default. Writes need the project.model.write permission.

When a gateway project saves a provider key, and neither the project nor the account has a default, Kortix sets that provider’s flagship model as the project default, if the project can run it. It never replaces a default that exists.

Offer vs allow

Two separate controls decide which models a project uses:

• kortix models enable <model-id>... and disable <model-id>... store exceptions to the catalog default. kortix models reset removes every exception.
• A disabled provider blocks all its models, including models the catalog adds later. Its credentials stay saved.
• Disable the Kortix provider to run only on your own providers. First set a project default on one of your providers: while the default is a Kortix model, the switch returns 409 cannot_disable_default.
• Access applies to every new request: picker choices, saved session selections and fallback candidates. A request already sent upstream finishes.
• You cannot hide the default model (project, else account, else platform), and you cannot disable it or its provider. Set another project default first.

Thinking effort

The composer’s thinking control sets the session’s model variant. The choices are the reasoning levels the model itself publishes. A model without reasoning levels shows no control. Auto clears the variant, and the model’s own default applies. The gateway translates the level into each provider’s request field.

A project can set defaults per model: Customize → Models → Routing → Advanced → Generation defaults. The fields are reasoning effort, temperature, top_p and max output tokens. A default fills only a field that the request left unset, so a session’s variant always wins.

Routing and fallback

Open Customize → Models → Routing, or use the CLI:

kortix gateway routing                      # effective policy and its sources
kortix gateway routing set \
  --default-model glm-5.3-flash \
  --fallback anthropic/<model-id>,glm-5.3-flash \
  --fallback-on transient \
  --vision-model glm-5.3-flash
kortix gateway routing preview glm-5.3-flash --image
kortix gateway routing reset

• --default-model sets the project default.
• --fallback is the chain the gateway tries in order when the model fails. It takes up to 8 models.
• --fallback-on transient moves on after a network error, a timeout, any 5xx, or a 402, 403, 404 or 429. any-error moves on after every failure.
• The project’s chain also runs when every key or ChatGPT account that the request may use is paused after a rate limit. With --fallback-on any-error, it also runs when the login needs reconnection.
• The chain covers every model in the project: the project default, an agent’s default, and a model that a session or trigger pins. A per-model override (rules in set --file, or Per-model overrides in Customize → Models → Routing) replaces the chain for one exact model.
• --vision-model takes a request that carries images when the default model accepts only text.
• set changes only the flags you pass. The rest of the policy, the generation defaults included, stays as stored. set --file policy.json replaces the whole policy; a file without modelGenerationConfig keeps the stored generation defaults.

Billing in a fallback. A request on your own key moves to a Kortix-billed model only when your project’s chain names that model and the account can pay for it. Kortix’s own platform chain never moves your request onto credits. On Kortix Cloud, the platform chain moves deepseek-v4.1-flash to glm-5.3-flash on transient errors.

When a fallback model answers, the composer shows Running on and the model name. The turn details name the model that answered and the model it replaced. Costs counts the spend under the model that answered.

Shared keys and ChatGPT accounts

By default, a provider key belongs to the whole project. A personal override of a provider key returns llm_credentials_project_wide.

Turn on the pooled_provider_secrets feature flag (off by default) to let each member bring their own keys and ChatGPT accounts.

Add a key. In Providers, choose Add key beside a provider. Give it a label. The value is write-only. A new key is Only you by default. Any member can add a key for their own use. Sharing with Everyone in this project or Specific members needs permission to manage project secrets. Change it in ⋯ → Manage access. Rotating a key keeps its access and session selections. Deleting it removes it for everyone.

Connect a ChatGPT account. In the model picker, choose Use your ChatGPT subscription, then Connect ChatGPT, and sign in with the code shown. Each sign-in adds one named account, so a member can connect more than one. When ChatGPT signs you out, the account shows Needs reconnection: choose ⋯ → Reconnect. Only the member who connected an account can reconnect it. Account owners and admins can delete any account. A project manager can turn off ChatGPT subscription for the project in Providers.

Choose keys for a session. Open Session overrides → Provider keys in the composer. Select up to 10 keys per provider, then Save changes. An empty selection turns the provider off for that session. Reset to project default removes the selection.

Which keys a session may use:

• Your private session uses keys shared with the project, plus keys and ChatGPT accounts granted to you.
• A shared session, a trigger session and a Slack or Teams session use only keys shared with the whole project.
• When you share a private session whose model runs only on your own keys, the request fails with 409 SHARED_SESSION_NEEDS_PROJECT_KEY. Share a key with the whole project, or switch the session to another model.
• A session started by the CLI, the SDK, Slack or Teams names a model and no keys. It gets every key it may use for that provider under the rules above, up to 10, and they rotate.

The agent must be allowed the key. When the running agent declares a secrets list, the list must name the key, for example CODEX_AUTH_JSON for ChatGPT or ANTHROPIC_API_KEY. Otherwise the turn fails with agent_grant_excludes. See Agents & permissions.

Rate limits. When a key returns 429 before any output, the gateway tries the next selected key. It never replays a partial answer on another key. When every key is paused, the project’s fallback chain runs. With no chain, the request fails with a Retry-After of at most 60 seconds. The gateway tries a paused key again every 15 minutes. kortix providers retry [<provider>] ends the pause now, for example after you reset ChatGPT usage.

Budgets and costs

A budget caps what a project, or one member in it, spends on models in a period. Open Customize → Models → Costs, or use the CLI:

kortix gateway budget                                   # budgets with their spend this period, and this month's project spend
kortix gateway budget set --limit 20 --scope project --period month --action block   # 20 USD = 2,000 credits
kortix gateway budget set --limit <limit> --scope member --user <user-id> --period week --action warn
kortix gateway budget rm <budget-id>

• --limit takes US dollars, the unit of the API’s limit_usd field. One credit is $0.01, so --limit 20 is a 2,000-credit budget. The CLI shows budgets and spend in credits, and --json returns the API’s dollar fields.
• --period is day, week or month, in UTC. A week starts on Monday. A month starts on the 1st.
• Block (block) refuses new requests at the limit with 402 budget_exceeded. Warn only (warn) lets them run.
• A budget counts all spend: Kortix credits and the cost on your own keys.
• Each budget shows its spend in its own period, for example 1,500 of 2,000 credits per day · blocks at limit · 75% used, and when the period resets. This is the number the gateway compares with the limit. GET /v1/projects/<project-id>/gateway/budgets returns it per budget in US dollars as spent_usd, period_start and resets_at, and a member budget’s member as subject_email. project_spend and members in the same response are month-to-date.
• Every member cap has a row in the list, also when its member has spent nothing this month.
• At 80% and at 100% of the limit, Kortix emails the account owners and admins and the project managers, once per threshold per period.
• Setting a budget needs project.gateway.budget.set. Reading spend needs project.gateway.spend.read.
• A project manager reads every member’s spend and cap. A plain member reads the project budget, their own cap and their own spend row, and never another member’s id or email.

Read spend and requests:

kortix gateway usage --days 7      # requests, errors and cost by model
kortix gateway sources --hours 24  # spend by trigger, member, channel and API
kortix gateway logs --failed       # recent failed requests
kortix gateway logs <log-id>       # one request in full
kortix gateway test deepseek-v4.1-flash glm-5.3-flash --prompt "Say hi"

The Costs and Logs tabs show the same data. For account-wide usage, see Plans & credits.

A project manager reads every log and every session’s spend. A plain member reads only the logs and session spend of their own requests and of sessions they may open. kortix gateway test spends credits on real model calls, so it needs project.model.write, the Manager permission that changes the project’s models.

Use the gateway from your own tools

A gateway key lets any OpenAI- or Anthropic-compatible client call the project’s models. The client gets the same keys, routing, access rules and budgets as a session.

1. Create a key in Customize → Models → Gateway, or run kortix gateway keys new <name>. The key starts with kortix_gw_. Kortix shows it once. kortix gateway keys lists keys, and kortix gateway keys rm <key-id> revokes one. Managing keys needs project.gateway.keys.manage.
2. Point the client at the gateway. On Kortix Cloud the base URL is https://gateway.kortix.com. A self-hosted instance shows its own URL in the Gateway tab.

The gateway reads the key from Authorization: Bearer, and on /v1/messages also from x-api-key, so ANTHROPIC_API_KEY works as well as ANTHROPIC_AUTH_TOKEN.

curl https://gateway.kortix.com/v1/chat/completions \
  -H "Authorization: Bearer kortix_gw_..." \
  -H "Content-Type: application/json" \
  -d '{"model": "glm-5.3-flash", "messages": [{"role": "user", "content": "Hello"}]}'

Claude Code:

ANTHROPIC_BASE_URL=https://gateway.kortix.com \
ANTHROPIC_AUTH_TOKEN=kortix_gw_... \
claude --model glm-5.3-flash

Codex CLI speaks only the Responses protocol. Add a provider to ~/.codex/config.toml:

model = "glm-5.3-flash"
model_provider = "kortix"

[model_providers.kortix]
name = "Kortix"
base_url = "https://gateway.kortix.com/v1"
env_key = "KORTIX_GATEWAY_KEY"
wire_api = "responses"

Then run KORTIX_GATEWAY_KEY=kortix_gw_... codex.

Limits:

• /v1/messages/count_tokens returns 404. Claude Code then estimates token counts itself.
• Reasoning text is not returned as thinking blocks.
• Claude Code cannot set a context window per model. Set CLAUDE_CODE_MAX_CONTEXT_TOKENS to the smallest window of the models you use.
• A request with more than 20 inline images keeps the 12 newest. A text notice replaces each older image.
• A request body over 128 MiB returns 413.
• codex/* models need a ChatGPT account shared with Everyone in this project. A gateway key never uses a private account.

Errors

Slack and Microsoft Teams show the same failures in their own words. See Models and keys in a channel.