Connect a model account

Agents run on models from your own model accounts. Connect an account with an API key, or sign in with the provider. Owners and admins connect accounts and replace their keys or sign-ins.

Connect an account

To do it yourself, run devboxes connect in a terminal:

devboxes connect --organization <organization id> --label "<account name>"

The CLI lists the ways to connect a provider: its sign-in, such as "OpenAI (browser sign-in)", and its API key, such as "OpenAI API key" or "Anthropic API key". An option you can't connect is greyed out, with the reason: only an Organization owner or admin connects accounts. Choose one.

• API key: paste the key at the CLI's prompt, which doesn't show it. devboxes stores the key encrypted and never shows it again.
• Sign-in: the CLI prints the URL of the provider's sign-in page and opens it in your browser. Some providers show a code there that the CLI printed too; check that they match and approve, and the CLI waits until you have. Others, such as Claude, show a code after you sign in; paste it at the CLI's prompt.

The CLI prints the new account's id. To replace an account's key or sign-in, add --account <account id>.

In a terminal, type keys and codes only at that masked prompt. Scripts and agents name the provider, so the CLI doesn't ask for one, add --api-key to connect a key to a provider they could sign in to, and pipe the key or code to stdin from the command that holds it, such as a secret manager's CLI:

<command that prints the key> | devboxes connect openai --api-key --organization <organization id> --label "OpenAI"

Provider IDs come from providers.list. In its result, deviceFlow: true means that you can sign in to the provider, apiKey: true that you can connect an API key, and unavailable says why you can't connect it, or is null:

{ "organizationId": "<organization id>" }

devboxes invoke providers.list --input @organization.json

Without the CLI, connect an API key with connections.add, and sign in with providers.connect-start followed by providers.connect-complete. Call providers.connect-complete with the attemptId until it no longer answers pending, or once with the pasted code as code for a provider whose providers.connect-start returned no userCode.

Connect Claude

Claude subscription. Chat and Runs can run on a Claude plan that includes Claude Code, through the claude-subscription provider. Model requests run the official Claude Code CLI, signed in with your subscription, so Chat replies and Runs count against your plan's usage limits. Sign in from the CLI:

devboxes connect claude-subscription --organization <organization id> --label "Claude subscription"

You can also choose "Claude subscription (browser sign-in)" in devboxes connect without a provider. After you sign in on Anthropic's page, it shows a code; paste it at the CLI's prompt. devboxes exchanges the code for a token that can only run models, and stores it; neither the CLI nor any result shows the token. This sign-in uses Claude Code's OAuth client, so you don't need the Claude CLI. A code from another sign-in is refused without asking Anthropic: start again with devboxes connect. When Anthropic refuses the code, the error shows Anthropic's answer as Anthropic sent it. connections.add refuses this provider, so replace the account's token by signing in again with --account.

The account offers every Anthropic model that models.dev lists, with the context models.dev gives it. Claude Sonnet 4.6 and Claude Opus 4.6 run with their million-token context. On a Claude subscription, Anthropic bills that context to usage credits: Sonnet 4.6's on every plan, and Opus 4.6's on Pro. When Anthropic refuses a model request, the Chat reply shows Anthropic's message in full. Claude subscriptions explains how Runs keep the token from the agent.

Anthropic API key. Create a key in the Anthropic Console at console.anthropic.com, and choose "Anthropic API key" in devboxes connect, or run devboxes connect anthropic. Anthropic bills its use to the key's Console organization, which can use the API credits that some Claude plans include.

Choose models

List the models your accounts offer:

{ "organizationId": "<organization id>" }

devboxes invoke providers.models --input @models.json

The recommended field says whether devboxes recommends a model. For a Claude subscription, an Anthropic, OpenAI or xAI account, and GitHub Copilot, one model is recommended: the provider's current balanced model. Other providers have no recommendation.

Projects and Chat use a model selection: a list of candidate models, and the longest answer a model may write. Without weights, devboxes uses the first model in the list that is available:

{
  "candidates": [
    { "accountId": "<Anthropic account id>", "modelId": "claude-sonnet-4-5" },
    { "accountId": "<OpenAI account id>", "modelId": "gpt-5" }
  ],
  "outputTokenLimit": 8192
}

To split work across accounts, give candidates a weight. With the weights below, about two of every three new tasks and Chat threads go to the first account:

{
  "candidates": [
    { "accountId": "<first ChatGPT account id>", "modelId": "gpt-5", "weight": 2 },
    { "accountId": "<second ChatGPT account id>", "modelId": "gpt-5", "weight": 1 }
  ],
  "outputTokenLimit": 8192
}

To run a model at a specific reasoning effort, give its candidate a variant. A candidate without a variant runs at the provider's default effort:

{
  "candidates": [{ "accountId": "<ChatGPT account id>", "modelId": "gpt-5", "variant": "high" }],
  "outputTokenLimit": 8192
}

The efforts that providers.models lists for a model are the variants it offers, such as low, medium, high, xhigh, and max. The set depends on the model. Saving a selection with a candidate whose model does not offer its variant fails with EFFORT_UNSUPPORTED, whose details.efforts lists the model's efforts.

A Blueprint can also set the model and effort that its new tasks run on, and a task can name its own with model and effort. Start a task explains which one a task uses.

Manage accounts

To list, rename, or delete accounts, use the model account operations. An Organization can connect several accounts of one provider, each under its own name. connections.usage shows an account's usage: the limits that ChatGPT, Grok, GitHub Copilot and OpenCode Go report, such as ChatGPT's 5-hour and weekly limits, and the Runs of the last 30 days with their tokens. Chat replies record no tokens, so they aren't counted. Claude subscriptions report no limits to devboxes. In the web app, Model subscriptions shows each account with its usage, and owners and admins disconnect accounts there. Model accounts and failover explains how devboxes pauses an account that its provider refuses, and which account running work keeps.