--- title: Models description: How Beeuni picks a model, and how billing works for managed vs. your-own-key models. --- Beeuni runs each [session](/docs/work/sessions) 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](/docs/feature-flags), **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](/docs/work/harnesses). 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](/docs/project/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. 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](/docs/project/secrets). 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 `_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. ### OpenCode Zen and Go (sign in with OpenCode) Connect OpenCode Zen or OpenCode Go with an API key, or sign in with your OpenCode Console account instead: 1. Open **Customize → Models → Providers** and find **OpenCode Go**. 2. Choose **Sign in with OpenCode**. Copy the code, choose **Open auth page**, and approve the device in your OpenCode workspace. 3. 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](https://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.) 1. An explicit pin — a session, channel, or trigger's own `model:` field. 2. The [agent's](/docs/project/agents) default for this project. 3. The project's default. 4. The account's default. 5. 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](/docs/project/manifest) for the trigger `model:` field. :::warning[Billing surprises on BYOK] Credit usage on a paid account: - Credits cover model calls, tools, and computer usage. Check Billing for your balance and Usage for a breakdown. - **Silent failover.** If your BYOK key hits a rate limit or billing error mid-turn, Beeuni retries on a managed model and bills your credits instead of failing the session. If you see credit charges on a BYOK-only project, check the usage details before reporting a billing bug. ::: 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. 1. Create a key in **Customize → Gateway**, tab **Gateway**. 2. Start Claude Code with the gateway as its API endpoint: ```bash 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](#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.