Models

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

Beeuni runs each session on a model. This page explains managed models vs. your own provider key (BYOK), how Beeuni 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 → Feature flags .

With the flag off, the project manages models directly through the default runtime. The experimental runtime requires the gateway.

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. The default runtime connects each provider from its key automatically.
Model ids use provider/model refs, like anthropic/claude-opus-4-8. Managed bare ids and beeuni/… 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 (the harness 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; the harness resolves the default model in the sandbox.

Managed models and BYOK

A model id has one of three shapes:

Managed — a bare id, like glm-5.2, deepseek-v4-pro-0813, or grok-4.6. Beeuni supplies the credentials. Cloud accounts pay with Beeuni 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.

Each provider reads its own key. Some providers share one env var on models.dev, for example OpenCode Zen (opencode) and OpenCode Go (opencode-go) both list OPENCODE_API_KEY. The provider that owns the name keeps it. Every other provider reads <PROVIDER_ID>_API_KEY: OpenCode Go reads OPENCODE_GO_API_KEY, Z.ai Coding Plan reads ZAI_CODING_PLAN_API_KEY, and Moonshot China reads MOONSHOTAI_CN_API_KEY. A Zen key therefore never lists Go models. The connect form and beeuni providers set use the right name.

Connect OpenCode Zen or OpenCode Go with an API key, or sign in with your OpenCode Console account instead:

Open Customize → Models → Providers and find OpenCode Go.
Choose Sign in with OpenCode. Copy the code, choose Open auth page, and approve the device in your OpenCode workspace.
The key field shows the provider as connected. Remove the key to sign out.

From the CLI: beeuni providers login opencode-go, or beeuni providers login opencode for Zen. Zen models are used by id, for example opencode/glm-5.3-flash; the picker does not list them. Zen and Go each hold their own login, so signing in to one never connects the other. The login lasts 30 days, and Beeuni renews it before it expires. When OpenCode refuses a login, Beeuni renews it once and retries the request. When the renewal fails too, the request returns provider_reauth_required: sign in again.

Beeuni-managed models

The picker lists these under Beeuni, with their token rates. The platform supplies the credentials through its configured model gateway.

Model	Id
GPT-6 Astra	`gpt-6-astra`
GPT-6 Sol (platform default)	`gpt-6-sol`

Use other models through a BYOK key or a ChatGPT plan. A BYOK key offers its provider’s whole catalog, for example anthropic/claude-opus-5-5 with an Anthropic key. A ChatGPT plan offers every model Codex offers a ChatGPT account, for example codex/gpt-6.1-sol. The picker shows the newest model of each family by default.

Both lists update automatically. The API reads models.dev and the Codex CLI’s published model list every hour, so a new release appears within an hour of its listing, without a Beeuni release. When you connect a provider, its newest stable model with tool calling becomes the default.

Disable providers or models

Open Customize → Models → Providers. Open the ⋯ menu in the Beeuni row and choose Disable provider to use only your own providers. Beeuni 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 Beeuni 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 default runtime 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): default runtime 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 → Models → Routing → Advanced → 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 Beeuni 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.

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

When a fallback model answers, the session says so. The composer shows Running on and the model’s name beside the model selector. Each turn’s details name the model that answered, the model it replaced, and what Beeuni billed for the turn. Customize → Models → Costs counts that spend under the model that answered.

Per-project model enablement

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

Provider keys and member access

With Pooled provider secrets off, a connected provider key applies to the whole project. Personal overrides for these project secrets return llm_credentials_project_wide.

Enable Pooled provider secrets and LLM Gateway in Settings → Feature flags to use provider secret resources. Open Customize → Models → Providers and choose Add key beside a provider. Give each key a distinct label. The value is write-only; later screens show its label and access list.

New keys belong to this project. Everyone in this project can use them by default. Open a key’s ⋯ → Manage access and choose Specific members to restrict access. Legacy account-wide resources retain their member grants. Account membership, project permissions, the agent’s secret permissions, and session selection still apply. A member grant permits use without revealing the key. Rotating a key preserves its access and session selections. Deleting it removes access for everyone.

Choose keys for a session

Open the composer’s Session overrides → Provider keys. Choose a provider, then select up to ten keys. Choose Save changes in the panel footer. For a new session, the selection is sent with the first prompt.

Without an explicit selection, the existing project key remains available.
Selecting no keys disables that provider for the session. It does not restore the project key.
Reset to project default removes the explicit selection.
Revoked or inactive keys appear as unavailable. Remove them from the selection, select another key, or reset the selection.
Deleting the last selected key leaves an empty pool. The session settings still show that provider so you can reset it.
A failed read shows Try again. It never appears as an inherited selection.

On a rate limit before output starts, the gateway tries another selected key. It never replays a partial answer across keys. If every key is rate-limited, retry after the earliest cooldown, capped at 60 seconds. An explicit pool does not silently borrow another member’s key or the legacy project credential.

ChatGPT accounts

Choose Add account under ChatGPT Plus/Pro. Each authorization creates a separate named connection in this project. Everyone in this project can use it by default. Use Manage access → Specific members to restrict access.

A session can select multiple granted ChatGPT accounts. Without a selection, the member’s newest usable connection is the default. Another member’s shared connection requires an explicit selection. The legacy project login remains available when the member has no usable connection of their own. A shared gateway key cannot borrow its creator’s private ChatGPT connection.

Google Gemini API keys use Google’s OpenAI-compatible endpoint with the gateway on. Native default runtime mode continues to use project secrets.

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.

Provider selections stay as drafts until you click Save changes in the session overrides footer. This saves changes for every provider, including a reset to the default. You can switch sections or close and reopen the panel without losing these drafts. Reloading the page discards unsaved changes. If a save fails, the panel stays open and shows the error. Correct the selection or retry. Providers already saved remain saved; unfinished changes stay in the panel.

Budgets

A gateway budget caps what a project, or one member in it, spends on models per day, week, or month. Block refuses new requests at the limit; Warn only lets them run. Set budgets on the project’s Models page.

At 80% and at 100% of a budget’s limit, Beeuni emails the account owners and admins and the project managers, once per threshold per period.

Use the gateway from Claude Code

The gateway serves the Anthropic Messages API at POST /v1/messages. Claude Code and Anthropic SDKs can call any gateway model through it.

Create a key in Customize → Gateway, tab Gateway.
Start Claude Code with the gateway as its API endpoint:

ANTHROPIC_BASE_URL=https://gateway.beeuni.ai \
ANTHROPIC_AUTH_TOKEN=beeuni_gw_... \
claude --model kimi-k3

The gateway reads the key from Authorization: Bearer or from x-api-key, so ANTHROPIC_API_KEY also works.

The gateway translates these Claude Code fields for every provider:

thinking: {type: "adaptive"} with output_config.effort becomes reasoning_effort. See Thinking effort.
Usage on the final message_delta carries input_tokens, cache_read_input_tokens, and cache_creation_input_tokens. Claude Code uses them for /context and auto-compaction.
Images that a tool returns, such as a Read of a screenshot, reach the model in a user message after the tool result.
A provider stream that ends before completion returns an api_error event, so Claude Code retries the turn.

Limits:

/v1/messages/count_tokens returns 404. Claude Code then estimates counts from characters.
Reasoning text is not returned as thinking blocks.
ChatGPT models (codex/*) need a ChatGPT connection shared with Everyone in this project. A gateway key cannot use a private connection.
Claude Code cannot set a context window per model. Set CLAUDE_CODE_MAX_CONTEXT_TOKENS to the smallest window you use.