Models

SingulaComp runs each session on a model. This page explains managed models vs. your own provider key (BYOK), how SingulaComp 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 singulacomp/… 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. SingulaComp supplies the credentials. Cloud accounts pay with SingulaComp 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.

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

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