--- 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. pi uses the Beeuni LLM gateway. Both are standard behavior with no per-project switch. ## Managed models and BYOK A model id has one of three shapes: - **Managed** — a bare id, like `gpt-6-sol`. 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 the default model is chosen Beeuni uses the first configured choice in this order: 1. An explicit session, channel, or trigger selection. 2. The agent default for this project. 3. The project default. 4. The account default. 5. The platform default. If a saved default is no longer available, Beeuni uses an available fallback or the platform default. It does not try each less-specific default in turn. In v2, set the model in the agent Markdown file's frontmatter. In v3, use `agents..model` in `beeuni.yaml`. The composer sends its selected model with each prompt. A provider configuration in `opencode.jsonc` applies to v1/v2. :::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. - **Configured fallbacks.** Beeuni tries another model only when a matching fallback rule applies to the error. If the fallback uses a Beeuni-managed model, its usage is charged to your credits. 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. These visibility preferences only hide models from the picker. An API request can still use a hidden model if access is allowed. Disabling a model or provider with the access controls above blocks new gateway requests, including API calls. The project's default model cannot be hidden; 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.