# Accounts and model providers

A run has three parts you can choose. The **agent** is the CLI that does the work: Claude Code, Codex or Gemini CLI.
The **account** is whose login it uses: a machine can hold several Claude, Codex and Gemini CLI logins, so a team can
run on a work account while another runs on a personal one. The **provider** is the endpoint that serves the tokens,
when it isn't the account's own: an API key for OpenRouter, say, or a local Ollama server.

Credentials and keys never leave the machine. The board sees account names, whether each is signed in, and which
providers the machine can reach.

## Add an account on the machine

1. Run `andon accounts add <claude|codex|gemini> "<name>"`.
2. Sign in when the CLI asks. In the browser, use the account you want: a private window helps for a second account.
3. Press **Sync** on the machine in **Settings → Machines**, or wait for the next heartbeat. Teams can now pick it.

The other `andon accounts` commands:

```sh
andon accounts                                  # list them, and whether each is signed in
andon accounts add claude "Work"                # its own directory, then `claude auth login` in it
andon accounts add codex "Work"                 # the same for Codex (`codex login`)
andon accounts add gemini "Work"                # the same for Gemini CLI (its sign-in question)
andon accounts add claude "Personal" --current  # give the machine's own login a name
andon accounts add codex "Work" --dir <path>    # reuse a directory that is already signed in
andon accounts login claude "Work"              # sign in again (expired, or the sign-in was skipped)
andon accounts remove claude "Work"             # forget it; its directory stays
```

Each added account gets its own directory, `~/.local/state/andon/accounts/<agent>-<id>`, readable only by you. Its runs
use it as `CLAUDE_CONFIG_DIR`, `CODEX_HOME` or `GEMINI_CLI_HOME`. `--no-login` adds it without signing in.

**Nothing changes until you add one.** A machine nobody configured has one account per CLI, `default`: the login it
always used. Teams that pick no account keep running under it.

### What a new Claude account shares

A new Claude account shares `settings.json`, `CLAUDE.md`, `skills`, `agents`, `commands`, `plugins` and
`output-styles` with `~/.claude`, by symlink (`--no-share` turns this off). Its login, sessions and user-level MCP
servers (`.claude.json`) are its own: add MCP servers again in that account if its runs need them.

Nobody is at a run's terminal to answer Claude's first-run screens, so before each run under an added account Andon
marks onboarding done and trusts the run's worktree in that account's `.claude.json`. For every login, the machine's
own included, it also answers *Claude in Chrome extension detected* with *No, keep browser tools off*, so a card run
can't reach your signed-in Chrome just because the board started it. An answer already in the file stays, including
the *Yes* an earlier Andon agent gave for you: run `/chrome` in that login to turn it off. To let card runs drive your
Chrome, turn it on with `/chrome` in that login, or add `--chrome` to the machine's extra arguments for card runs only
([Extra arguments](https://andon-docs.pages.dev/machines/orca-or-direct.md#extra-arguments)).

### Sign in to Gemini CLI

Gemini CLI has no login command. `andon accounts add gemini <name>` and `andon accounts login gemini <name>` open
Gemini CLI in the account's home, at its sign-in question:

1. Pick *Use Gemini API Key* and paste the key, or *Sign in with Google*.
2. Type `/quit`.

For the machine's own Gemini login, run `andon accounts login gemini default`. Andon's Gemini homes are its own
(`~/.local/state/andon/gemini-home` for the machine's login): Andon never reads or writes `~/.gemini`, and `--dir`
refuses your home folder. A sign-in made in Gemini CLI outside Andon isn't seen, because Gemini keeps it in the OS
keychain, one per machine; Andon makes Gemini keep each sign-in in its own home instead. Setting `GEMINI_API_KEY` in
the agent's environment also works.

A home nobody signed in to fails the run with Gemini's *Please set an Auth method*.

### How the board knows an account's state

Each heartbeat reports every account's name and status. Claude and Codex accounts are read with
`claude auth status` and `codex login status`. Gemini CLI has no status command, so Andon reads the account's home:

| Gemini CLI home | Status |
|---|---|
| signed in with an API key | signed in |
| no sign-in | signed out |
| signed in with Google, or a key that could come from the environment or a `.env` file | sign-in unknown |

A signed-out account is reported but takes no runs. An unknown one still takes runs, so sign each Gemini CLI account in
on every machine that has it before a team picks it.

## Pick the agent, model and account for a team

The workspace's default is under **Settings → Automation**: **Agent**, **Model** and **When a subscription runs out**.
A team can change them:

1. Open **Settings → Teams** and pick the team.
2. Under **Overrides**, set **Agent** (Claude Code, Codex or Gemini CLI) and **Model**.
3. Set the agent's subscription, for example **Claude subscription**: **The machine's own login**, or an account the
   org's machines report.

Each row first shows what the team inherits (from the workspace or a parent team); picking that option clears the
team's own value. Sub-teams inherit the team's choices.

The reviewer's account and the team's own **When usage credits run out** list are in a section the team page doesn't
show: search Settings for **When usage credits run out** (or **Codex account**) and pick the team.

**One card, another account.** In a card's properties, **Account** sits under **Agent** and **Model**. **Default for
this team** follows the team.

### Where a run goes

A run on an account goes only to a machine where that account is signed in. Otherwise the card says why: *Mac mini has
no Work Claude account*, or *the Work Claude account is signed out on Mac mini*. The run line names the account:
`Claude – Work · Opus 5.5 · Terminal`.

A resumed session (**Continue**, **Retry**, a CI or merge-conflict fix, a model switch) stays in the account it started
under, because its files live in that account's directory. If a resume reaches the machine under another account, the
machine resumes it in the account whose directory holds the session, and its log says so (*session … is in the Work
Claude account, not …: resuming it there*). The run then names that account: its run line, the usage credits it uses
and the session's next resume. A new start takes the card's account, else the team's.

## When usage credits run out

An account's credits are tracked per account. When Work runs out on a machine, Work runs there wait, and the machine's
other accounts keep going.

**When usage credits run out** is one ordered list of accounts and models, for example *Claude account Personal →
Sonnet 5.5 → ask me*. The workspace's list (**Settings → Automation → When a subscription runs out**) applies to every
team that doesn't set its own. It is empty by default, which means the card asks you at once.

When a run stops on credits or a usage limit, Andon tries the steps in order and takes the first it can:

- **An account step** carries on under that account, when the machine has it signed in and has credits for it. It is
  a **new session in the same worktree**: the agent starts without the earlier conversation, is told so, and picks up
  from the files and git. The run says so: `Switched to Claude – Personal in a new session`.
- **A model step** switches to that model, or to the next model down from the one that ran out.

After the last step, the card asks: switch model, retry later or retry now. A run makes at most one account switch and
one model switch. Review rounds and CI fixes don't switch. Account steps are skipped on a machine that requires signed
commands, in a live Orca terminal, and when a provider's credit ran out (another account can't refill a key).

## Usage left

**Settings → Machines** shows each Claude and Codex subscription on its machine's card: signed out, out of credits, or
how much of its 5-hour and weekly limits is left and when each resets. A machine whose subscriptions are all signed out,
or all used up, reads **Needs you**.

- **Claude**: every 15 minutes the agent sends each signed-in account one tiny Haiku turn that loads nothing, about 600
  tokens, and reads the limits Claude Code reports. `usageCheckMin` in the agent's config sets the interval; 0 turns it
  off.
- **Codex**: nothing is sent. The agent reads the limits Codex writes into its session files, so an account shows
  usage after its first Codex run on that machine.
- **Gemini CLI**: not shown yet.

Only the percentages, reset times and plan name leave the machine.

## Orca's own accounts

Orca's managed accounts are machine-wide: one active Claude account and one active Codex account per Orca host,
switched in Orca's app. Orca can't pick an account per terminal, so:

- **Runs Andon starts in Orca terminals** use the team's Andon account, like terminal runs.
- **Sessions you started in Orca and Andon adopted** keep Orca's active account, and the team's setting doesn't apply.
  Switch Orca's active account before you start the work there, or start the card from Andon instead.
- An Orca-managed Codex home can be added with `andon accounts add codex <name> --dir <its home>`. Orca keeps Claude
  logins in its own credential store, so add a Claude account to Andon with its own sign-in.

## Model providers

A provider is an endpoint the machine holds a key for, or a local server that needs none. A run uses one through its
model, written `<provider>/<the provider's model id>`: `openrouter/anthropic/claude-sonnet-4.5`, `ollama/llama3.2:3b`.
A plain model id (`claude-opus-5-5`) means the account's own login.

The board has no page for providers. You add them on the machine:

```sh
andon providers list                       # what this machine can reach: key or not, models, balance
andon providers add openrouter             # a preset fills in the name, wire and URL
andon providers key openrouter             # paste the key on stdin
andon providers key openrouter --key-env OPENROUTER_API_KEY   # or read it from the environment
andon providers key openrouter --clear     # forget the key
andon providers remove openrouter          # drop the provider and its key
andon providers add mybox --name "My box" --wire openai_responses --url http://10.0.0.5:8080   # a custom one
```

Keys go into the machine's credential store (the macOS Keychain, the Secret Service, or a file only you can read),
never into the config or onto a command line. Restart the agent after you change providers.

The board's model pickers offer only Andon's own models. To run a repository's cards on a provider's model, name it as
the `model` under `automation` in the repository's `.andon/settings.json`
([Repository settings](https://andon-docs.pages.dev/reference/repo-settings.md)):

```json
{ "automation": { "executor": "claude", "model": "openrouter/anthropic/claude-sonnet-4.5" } }
```

A run goes only to a machine that has that provider with a key, or a local one that answered with models.

### Serving model calls (machine mode)

With the AI backend set to `machine` ([AI backends](https://andon-docs.pages.dev/machines/ai-backends.md)), the app hands its model calls (triage, the
assistant, recipe picks, Autopilot's placement, Start work, Auto-Done) to an online machine that serves them. The
machine runs each call on the Vercel AI SDK with its own key and sends back only the answer; the key never leaves it.
Voice never runs on a machine.

```sh
andon policy llm-serve on              # let the app hand this machine model calls (off by default)
andon llm key anthropic                # this machine's Anthropic key, pasted on stdin
andon llm key gemini                   # or a Gemini key
andon llm key gateway --key-env AI_GATEWAY_API_KEY   # or an AI Gateway key, read from the environment
andon llm backend auto                 # auto (Claude, else Gemini, else the gateway by the keys held), anthropic, direct or gateway
andon llm status                       # what it serves with
```

The keys go into the credential store, like a provider's. Without one stored, the agent uses `ANTHROPIC_API_KEY`,
`GEMINI_API_KEY` or `AI_GATEWAY_API_KEY` from its own environment. A machine with no key, or with policy `llm-serve` off, is never asked,
and neither is one whose policy requires signed commands. When no machine can serve a call, the app's own keys answer
it. These calls don't use the machine's Claude login.

### Which agent can use which provider

Each provider speaks one wire, and the wire decides which agent can use it:

| Wire | Agent |
|---|---|
| `anthropic_messages` | Claude Code |
| `openai_responses` | Codex |
| `openai_chat` | none: Codex dropped this wire, so such a row runs only behind a gateway that translates it |

**Gemini CLI uses no provider.** It runs on Google's models only, through its own sign-in. A Gemini run on a provider's
model fails with *Gemini CLI runs on Google's models only*.

A provider the agent can't speak is refused before the run starts, with the reason. Most local servers speak both
Messages and Responses, so give them two rows on the same URL: `ollama` for Claude Code and a second one with
`--wire openai_responses` for Codex.

### Presets

| Preset | Wire | Endpoint | Notes |
|---|---|---|---|
| `anthropic` | `anthropic_messages` | `https://api.anthropic.com` | The Claude API, billed per token. A Claude subscription is an account, not a provider. |
| `openrouter` | `anthropic_messages` | `https://openrouter.ai/api` | Many models behind one key, for Claude Code. |
| `openrouter-codex` | `openai_responses` | `https://openrouter.ai/api` | The same key and models, for Codex. |
| `venice` | `openai_chat` | `https://api.venice.ai/api/v1` | No agent speaks it directly: use `venice-codex`, or a gateway for Claude Code. |
| `venice-codex` | `openai_responses` | `https://api.venice.ai/api/v1` | Venice's Responses API (beta), for Codex. Same key as `venice`. |
| `freellmapi` | `anthropic_messages` | yours | A self-hosted gateway over free tiers: give it the URL (`--url`) and its key. |
| `openai` | `openai_responses` | `https://api.openai.com/v1` | OpenAI's API. A Codex subscription is an account, not a provider. |
| `ollama` | `anthropic_messages` | `http://127.0.0.1:11434` | Local models. No key. |
| `lmstudio` | `anthropic_messages` | `http://127.0.0.1:1234` | LM Studio's server (Developer tab). A key only if you turn auth on. |
| `vllm` | `anthropic_messages` | `http://127.0.0.1:8000` | A vLLM server. A key only with `--api-key`. |
| `anythingllm` | `openai_chat` | `http://127.0.0.1:3001/api/v1/openai` | Needs a Developer API key; the model is a workspace slug. No agent speaks its wire. |
| `local` | `openai_chat` | yours | Anything OpenAI-compatible on this machine or the LAN. For Codex, add it with `--wire openai_responses`. |

### Local models

A provider on this machine or the LAN (loopback, `localhost`, `10.…`, `192.168.…`, `172.16–31.…`, `.local`) needs no
key:

```sh
ollama serve
ollama pull qwen3-coder:30b
andon providers add ollama
andon providers list              # keyless, with its models
```

A local provider is offered for runs only once it answered with models, so a stopped `ollama serve` can't pull runs
onto the machine. Model ids keep the server's tag: a card on `ollama/llama3.2:3b` passes `--model llama3.2:3b`.

Know the limits before you rely on one:

- **Small models don't call tools.** Andon's prompt is a few thousand tokens before the card says anything. A 3B model
  may answer in Markdown instead of writing the file, and the run ends done with nothing on the branch.
- **Context size matters.** Ollama loads a model at its native context, which can need more memory than a laptop has.
  Too small a context (8,192 tokens) fills up with Andon's prompt before the card is read. Start the server with
  `OLLAMA_CONTEXT_LENGTH=32768`.
- **Codex warns** `Model metadata for … not found` for a local id. It is a warning, not a failure.

### When provider credits run out

The stop names the run's provider, model and agent. Switching account doesn't refill a provider's key, so account
steps are skipped. The card's credit picker and the dashboard offer another provider's model only when the run's own machine has it,
with a key and no empty balance.

Changing provider, moving from a provider to the account's own login, or switching a Codex model starts a **new
session in the same worktree**: files and uncommitted work stay, the conversation doesn't. The board says so before
the switch. A plain Claude-to-Claude model switch stays in the live session.

A balance is shown when the provider reports one (Venice does). OpenRouter's balance isn't read.

### What a run costs

| The run went through | Its cost |
|---|---|
| the account's own login | what the agent reports |
| a provider on this machine or the LAN | 0 |
| a remote provider with prices set for the model | tokens times those prices |
| a remote provider without prices | unknown |

## When the API connection drops

When a Claude Code turn is cut off by a lost API connection (*API Error: Connection error.*, a timeout, the computer
going to sleep, a 5xx from the API), an interactive run doesn't ask you. It stays Working with the note *Lost the
connection to the API; carrying on in 30 s (1 of 3)*, then types a short "carry on" into the session. The wait doubles
each time. After three tries in a row the turn ends as usual, with the error as its reply. A turn that goes through, or
a reply of your own, resets the count.

The agent's config sets it: `lostConnectionRetries` (default 3; 0 turns it off) and `lostConnectionRetrySec`
(default 30).
