> ## Documentation Index
> Fetch the complete documentation index at: https://squad.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Choose models and manage AI accounts
> Add more AI accounts, read each account's status and usage, set the fallback order, choose the default and fallback models, pin models per agent, and set the workspace model settings.
Your squad runs on AI accounts that you connect: your own subscriptions and API keys. Two screens control them:
* **AI Tokens**: your accounts on each provider, their order, their usage, and **Model routing** (the default model, the fallback models, and per-agent pins).
* **Agent Configuration**: the workspace model settings (**Workspace defaults**) and each agent's model, heartbeat, and scheduled tasks.
To connect your first account, see [Connect your AI subscription](/docs/connect-your-ai).
To open **AI Tokens**, use one of these:
* the key icon **AI Tokens** at the bottom of the sidebar
* the account menu > **AI Tokens**
* **Settings** > **AI Tokens**.
To open **Agent Configuration**, click the **Agent Configuration** icon at the bottom of the sidebar, or go to **Settings** > **Agent Configuration**.
## How Squad picks a model and an account
Every run follows the same order:
1. The run starts on the agent's pinned model. An agent without a pin uses the workspace default model.
2. On that model's provider, Squad uses the accounts in the order on the provider's card. An account that is expired, invalid, or at its limit is skipped.
3. When the model fails or hits a rate limit, the run moves to the next model under **FALLBACK ORDER** in **Model routing**.
4. Screenshots and photos go to the image model: the agent's image pin, or the workspace **Default image** model.
In **Runs**, open a run. **Technical details** shows the **Model** and **Provider** that ran. See [See what your agents did](/docs/runs-and-health).
## Add another account for a provider
You can connect more than one account for each provider, for example two ChatGPT accounts.
Open **AI Tokens**.
On the provider's card, click **＋ Add account**.
In **Token name**, type a name after the fixed prefix, for example "work". Only letters, digits, - and \_ are kept. The dialog shows the full name under the field.
Complete the sign-in or paste the key, as the dialog tells you.
If the name is already in use, the dialog says that connecting would overwrite that account, and the connect button stays off. Pick another name, or use **Replace** on the existing account.
Some providers have rules for extra accounts:
* Extra Qwen Cloud keys must come from the same plan.
* Extra Cloudflare Workers AI tokens must use the same account ID.
* MiniMax has no **Token name** field.
* Claude Code uses one active account at a time. See [Set the order in which accounts are used](#set-the-order-in-which-accounts-are-used).
To add a provider that has no account yet, click its tile under **ADD A PROVIDER**.
## Read a provider card
Each provider with at least one account has a card. From top to bottom, the card shows:
| Part | What it shows |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Name line | The provider's name. **Rate-limited · cooling down** shows next to it after a recent run on this provider failed with a rate-limit error. |
| Method line | How it connects, for example **Device code**, **API key**, or **Setup token**, and the number of accounts. |
| Role chip | **Default model**, **Fallback 1**, and so on, when **Model routing** uses a model from this provider. |
| **＋ Add account** | Adds another account. |
| **Highest first; the runtime tries accounts in this order.** | Shows when the card has two or more accounts. Each row then has a number and **Move up** and **Move down**. |
| Account rows | One row for each account. See the next section. |
| Usage note | "doesn’t publish usage data, so there’s no meter to show here" for providers without usage meters. |
| **See usage details on the** provider **website.** | A link to the provider's own usage page. |
### Read an account row
Each row shows the account name, one status word, a detail line, usage meters when the provider reports them, and the buttons **Replace** and **Disconnect**.
| Status word | Meaning |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **IN USE** | This account serves the next run on this provider. |
| **STANDBY** | This account is healthy and waits in the fallback order. |
| **CONNECTED** | This account is connected. The provider does not report usage, so Squad does not rank it by limits. |
| **AT LIMIT** | This account used up a limit window, or its balance is spent. It cannot serve runs until the limit resets. |
| **OUT OF SYNC** | Some agents hold an older copy of this credential. See [Fix credentials that are out of sync](#fix-credentials-that-are-out-of-sync). |
| **EXPIRED** | The login expired. Click **Replace** to connect it again. |
| **LOGIN INVALID** | The provider says the login is no longer valid. Click **Replace** to connect it again. |
Hover over a status word to read the full sentence.
The detail line shows the account's email or plan, or a masked key. It can also show:
* for ChatGPT · Codex: when the login expires, for example "expires in 5 days", and **renews automatically**. See [Keep ChatGPT accounts renewed](#keep-chatgpt-accounts-renewed).
* for Grok: **expired**, or, when only some agents hold an expired copy, "expired on 3 of 9 agents".
Usage meters show for ChatGPT · Codex, Claude, Claude Code, OpenRouter, Kimi, Z.ai, and GitHub Copilot:
* Each limit window has a meter with the percentage used and the time until it resets, for example "62% used · resets in 3 hours".
* A meter turns amber from 80% used and red from 95% used.
* Some providers show **Balance:** and the amount left.
* A thin bar shows while Squad checks the usage. **We couldn’t read this account’s usage right now.** means that the check failed. The account can still work.
Under the rows, the card can show one of these lines:
| Line | Meaning |
| ------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| **FALLING BACK TO** and an account name | The accounts ranked above cannot serve runs now. Your agents use this account. |
| **FALLING BACK TO THE NEXT PROVIDER IN MODEL ROUTING** | No account on this card can serve runs now. Runs move to the next model in **Model routing**. |
Row buttons:
* **Replace** connects the same account again. The dialog is titled **Replace** and the account name, and the new login overwrites exactly that account. Use it for an expired or invalid login.
* **Disconnect** removes the account. The button shows **Disconnecting…** while it works. Squad refuses to disconnect the Claude Code account that your agents use now: "This is the account your agents are using right now. Switch to another Claude account first, then disconnect this one." Move another account to the top and save the order first.
* **Set email** or **Edit email** shows on Claude Code rows only, because a Claude Code token does not show which account it belongs to. Type the email and click **Save**. To remove the email, clear the field and save.
## Set the order in which accounts are used
On a card with two or more accounts, the order is the fallback order. Squad tries the top account first. When that account cannot serve a run, for example because it reached a usage limit, Squad tries the next one.
1. On the provider's card, use **Move up** and **Move down** on the account rows.
2. In the bar that shows **Priority order changed**, click **Save changes**. **Reset** undoes the change.
The bar shows **Saving the new account order…** while it saves.
Claude Code uses one account at a time, the active account. The others show **STANDBY**. When the active account reaches its usage limit, the next account in the order becomes active, and the full account is skipped until its limit resets. If the refused run had not done any work yet, it runs again once on the new account. A run that already did work is not repeated. The next run uses the new account. The newest connection becomes the active account. When you save a new order, the first account becomes the active account.
A standby Claude Code account shows the note "This account is connected and takes over when the active Claude Code account reaches its usage limit." A Claude Code account that ran out shows **AT LIMIT** until its limit resets. If no other Claude Code account can take over, Claude Code runs start again when the limit resets or when you connect another account.
## Fix credentials that are out of sync
The strip at the top of **AI Tokens** shows **Credentials synced across all agents** when every agent has the same credentials. When an account does not match on every agent, it shows **Some credentials are out of sync across agents**.
1. Click **Sync now**.
2. Wait until the strip shows **Credentials synced across all agents**.
## Keep ChatGPT accounts renewed
A ChatGPT · Codex account row shows when its login expires, for example "expires in 5 days", and **renews automatically**, sometimes with the time of the last renewal. You do not need to act while it renews. Hover over the expiry to see the exact time. If the row shows **automatic renewal failed - reconnect this account**, click **Replace** and sign in again.
When ChatGPT reports a banked limit reset for an account, the row shows "One banked limit reset is available on this account." or the number of resets, and a **Use one now** button.
1. Click **Use one now**.
2. In **Use one banked reset?**, click **Use one reset**.
This refreshes the account's usage limits now. You cannot get a spent reset back. The row then shows how many banked resets are left.
## Choose the default model and fallback models
The **Model routing** card is on **AI Tokens**, above the provider cards. It says: "Your Squad starts every run on the default model. When it fails or hits a rate limit, the run moves to the next model in this list, in the order shown."
Open **AI Tokens** and find **Model routing**.
In the **Default** row, pick a model.
To add a fallback, pick a model in **Add a fallback model…**.
Use **Move up** and **Move down** to order the list under **FALLBACK ORDER**. **Make default** swaps a fallback with the default. If no default is saved, the fallback becomes the default and leaves the list. **Remove** takes it off the list.
In the bar that shows **Model routing changed**, click **Save changes**. **Reset** undoes your edits.
Each row shows "via" and the provider name that serves it. The lists show only models in **Allowed models**. The last option in each list, **＋ Add other models…**, opens **Agent Configuration**, where you allow more models.
If the list has no fallbacks, the card says "No fallbacks are set. When the default model fails, runs on it fail until it recovers." Add at least one fallback on a different provider.
The **Default image** row sets the model that reads screenshots and photos. By default it shows **follows the default model**. If no default model is saved, the **Default** row shows **Not set**. The **Default image** row also shows **Not set** while it follows the default model. If the chosen image model cannot read images, the card shows a warning.
If the card cannot load, it shows **We couldn’t read the model routing from your workspace.** Click **Try again**.
## Pin a model for one agent
**AGENT OVERRIDES** at the bottom of **Model routing** lists the agents that skip the workspace defaults. Each pin reads "starts on" and a model, or "reads images on" and a model. With no pins, it says **No agent pins yet. Every agent starts on the workspace default.**
1. In **Pin a model for an agent…**, pick the agent.
2. In **Choose a model…**, pick the model.
3. Click **Pin model**.
For an image model, use **Pin an image model for an agent…** and **Pin image model**. **Clear** removes a pin. Pins save at once.
You can also pin models on the agent's tab in **Agent Configuration**. See [Add, change, and pause agents](/docs/agents#change-an-agents-model).
## Set the workspace model settings
These settings are on **Agent Configuration** > **Workspace defaults**. The page says: "Defaults every agent inherits unless it sets its own override. The allowed list below gates every other model choice."
| Setting | What it controls | When nothing is saved |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| **Default model** | The model that agents use when they have no pin. This is the same setting as the **Default** row in **Model routing**. | Setup saves a model for the AI provider you connected. If no model is saved, the field shows **Not set**. |
| **Image model** | The model that reads screenshots and photos. **Same as default model** follows the default model. If the model cannot read images, the screen shows a warning. | **Same as default model** |
| **Reasoning effort** | How hard models think before they answer. Higher is slower and costs more of your provider's usage. | **Auto (per-model default)** |
| **Default timeout** | The maximum number of seconds that one agent run may take before it is stopped. See [Limits and defaults](/docs/limits-and-defaults). | New workspaces get 2,147,000 seconds (about 24.8 days). The field shows 600 only when no value is saved. |
| **Allowed models** | The only models that can be picked anywhere in the workspace. Every other model list is limited to this list. | Every model is allowed. |
The **Reasoning effort** levels are **Auto (per-model default)**, **Off: disable reasoning**, **Minimal**, **Low**, **Medium**, **High**, **Extra High**, **Max (GPT-5.6 family)**, and **Adaptive (model picks)**. **Max** shows only when your workspace computer supports it. The GPT-5.6 models do not support **Minimal**, so it is not offered when one of them is the default model. A saved level that the default model does not support shows **· not supported**, and Squad refuses to save until you pick another level.
Reasoning effort applies to the whole workspace only. You cannot set it for one agent or one schedule. Scheduled tasks have their own model and timeout fields. See [Schedule recurring work](/docs/scheduled).
**Allowed models** groups models by provider. Each group shows "N of M enabled" or **None enabled**. Click a group to open or close it, and click a model to allow or disallow it. Models from your plan that are not in the standard list show in a **From your plan** group. If the default model is not allowed, the screen says so. Pick an allowed model or allow it again.
To save:
1. Change the settings.
2. In the bar that shows **Unsaved changes**, click **Save changes**. **Reset** undoes your edits.
The page shows **✓ Saved**, and a notice says **Saved. Applying changes in the background (usually a minute or two).** The workspace computer restarts in the background to apply the change.
If the page cannot load, it shows **Couldn’t load your workspace configuration** and a **Retry** button. Nothing is editable until the real values load.
The **Workspace defaults** tab can also show **On your computer, not in your squad**. See [Add, change, and pause agents](/docs/agents#remove-an-agent).
## What your agents can do here
Squad gives agents no tool to connect, replace, or disconnect AI accounts, or to change **Model routing** or **Allowed models**. Make these changes yourself on the screens on this page.
## Check that it works
* **AI Tokens** shows one account as **IN USE** on each provider that reports usage.
* **Model routing** shows your default model with "via" and the provider name, and your fallbacks under **FALLBACK ORDER**.
* In **Runs**, open a run. **Technical details** shows the **Model** and **Provider** that ran.
## Troubleshooting
**A banner says that a provider is rate-limiting your agents.** Cause: three or more runs in a row failed with rate-limit errors from that provider in the last six hours. The **AI Tokens** card shows **Rate-limited · cooling down** after one recent rate-limit failure. Fix: add another account for that provider, or add a fallback model on a different provider. The banner says that agents retry automatically, but Squad does not start a run again after it failed with a rate-limit error. The only exception is the Claude Code account switch described in [Set the order in which accounts are used](#set-the-order-in-which-accounts-are-used). Send the request again, or wait for the next scheduled run, after the limit resets.
**Chat shows "Your AI connection expired. Replies will fail until you reconnect."** Cause: the login for the model's provider expired. Fix: click **Reconnect →**, then click **Replace** on the expired account.
**AI Tokens says that a provider "is signed out on your workspace".** Cause: the provider's login is no longer valid on the workspace computer. Runs that use it fail until you reconnect it. Fix: click **Replace** on the account on its card.
**AI Tokens shows "This agent is asleep".** Cause: the dashboard could not reach the workspace computer. Fix: click **Wake & retry**.
**A model is missing from a list.** Cause: the model is not in **Allowed models**. Fix: turn it on in **Agent Configuration** > **Allowed models**, then click **Save changes**.
**An account shows AT LIMIT, but you have usage left on the provider's website.** Cause: one of the account's limit windows is full, or its balance is spent. Fix: wait for the reset time on the meter, or move another account to the top.
## Common questions
No. Runs use your own subscriptions and API keys. See [What Squad costs](/docs/costs).
The run fails. It shows **Run failed** in **Runs**. Add accounts or fallbacks on other providers so that a run always has somewhere to go.
No. **Pin model** and **Clear** save at once. The **Model routing** bar is only for the default, image, and fallback models.