Provider setup and identity

Anima supplies the durable agent identity, chat routing, queue, memory, and activity trail. Claude Code, Codex, Kimi Code, Grok Build, OpenCode, pi, or Antigravity CLI supplies the model work and developer tools.

The provider CLI is a machine-level dependency. Anima launches the executable found on the host's PATH and uses that provider's existing local authentication. Provider login state is not copied into an agent home or stored by Anima.

Choose one provider

Install and authenticate at least one before creating the first agent.

Provider	Official setup	Verify on the Anima host
Claude Code	Install and authenticate Claude Code	claude --version
Codex	Install Codex CLI and sign in with your ChatGPT account or configured API access	codex --version
Kimi Code	Install Kimi Code CLI and use /login on first launch	kimi --version
Grok Build	Install Grok Build and sign in with grok login or configure its supported API-key authentication	grok --no-auto-update --version
OpenCode	Install OpenCode and add a DeepSeek API key with opencode auth login --provider deepseek	opencode --version
pi	npm install -g @earendil-works/pi-coding-agent, then run pi and /login (or add the provider API key to ~/.pi/agent/auth.json)	pi --version
Antigravity	Install Antigravity CLI (it installs to ~/.local/bin/agy), then run agy once and sign in	agy --version

Run the verification command from the same host user and service environment that runs Anima. A CLI installed only inside another shell profile or user account may work interactively while remaining invisible to the Anima services.

How onboarding detects readiness

The create-agent flow checks whether claude, codex, kimi, grok, opencode, pi, and agy resolve on PATH.

• Missing providers are disabled.
• If one available provider exists, onboarding can select it automatically.
• If none are found, creation stops with Install a provider first.

Detection proves that an executable exists. The first real turn proves that its authentication and provider account are usable.

Customize the runtime launch

Each provider has machine-wide Runtime command and Arguments fields under Settings > Providers. Leave the command blank to use the default shown in the placeholder: claude, codex, kimi, grok, opencode, pi, or agy. Set it to another executable name or an absolute executable path when every Anima agent using that provider should launch through a compatible wrapper, for example mcodex for Codex.

The command is one executable name or absolute path, not a shell command. Put optional CLI arguments in Arguments, one exact argv entry per line. Spaces within a line are preserved; Anima does not invoke a shell or split quotes, pipes, redirects, or environment assignments. For example, add --chrome as one line for Claude Code when that machine has a paired Claude in Chrome extension.

Arguments are inserted before Anima's managed transport and subcommand arguments. Anima validates the executable before saving it. A command or argument change applies only to agents using that provider, after their active turn and provider background work reach a safe boundary.

The same setting can be written directly in config.json:

{
  "providerArgs": {
    "claude-code": ["--chrome"]
  }
}

These settings change runtime launch only. Provider detection, version reporting, installation, and updates continue to use the official CLI named in the table above. Any wrapper or added arguments remain operator-owned and must preserve the provider protocol that Anima expects.

Authentication ownership

Sign in through the provider's own CLI. Do not paste provider login tokens into an Anima agent, Slack, Feishu, or an agent env entry.

The Providers panel can run that CLI sign-in for you. Each supported provider row has a Sign-in block that shows whether the CLI reports a signed-in account and offers two ways to sign in:

• Sign in on this machine runs <runtime command> login. The CLI opens its sign-in page on the machine that runs Anima and finishes through its local callback, so use it when you are at that machine.
• Sign in with a code runs <runtime command> login --device-auth. The panel shows the link and the one-time code the CLI prints; open the link on any device, enter the code, and sign in there, including any two-factor step. Anima notices when the CLI exits.

The sign-in uses the runtime command configured for the provider (see Customize the runtime launch). A wrapper such as a multi-account router therefore receives the login instead of the bare CLI, and the credential lands where that wrapper expects it. Anima never sees the credential: it only relays the link and code, reports how the CLI exited, and reruns login status afterwards. One sign-in runs at a time per machine; cancel it from the panel if you started the wrong mode. Currently supported: Codex.

All Anima agents launched under the same host user can reach the same provider credential store unless the provider itself is configured differently. Choosing a different provider for an agent does not create a separate machine account boundary.

The Providers panel shows the account label or identifier when the provider exposes one safely. It never stores or displays access tokens. An unavailable usage check can still show the last account Anima identified from local credentials.

Claude accounts are managed outside Anima (native Claude Code login or your own switcher). Anima does not add, switch, or pin Claude accounts in the dashboard. The Providers connection card distinguishes subscription login from API key or gateway configuration. Subscription connections can show quota; API connections leave usage and billing with the API provider. Agents share that host credential; there is no per-agent credential isolation in Anima.

Read connection status

For Claude Code and Codex, Providers distinguishes Subscription, API key, and Cloud provider from quota availability. Configured means a credential or helper is configured; it does not prove a successful request. API key and gateway connections do not require subscription login and do not show invented subscription quotas.

This is a machine-default snapshot of the CLI's user settings and Anima's service environment, not the authentication of every running agent. Project or managed settings, agent launch environment, CLI arguments and custom wrappers can override it. Claude's CLAUDE_CONFIG_DIR and Codex's CODEX_HOME select the inspected native directory. Claude key/bearer/helper configuration takes priority over a saved subscription login. Codex inspects the default profile/provider and file-based login; keyring, ephemeral, unsupported or unreadable configurations remain Not inspected.

Credential-store read failures stay unknown; they do not imply a missing login. After a credential is found, quota-query errors do not erase that connection evidence. The built-in Codex endpoint respects the selected openai_base_url override.

Only credential source and a sanitized endpoint origin reach the dashboard. Keys, tokens, helper commands and URL paths/query strings stay local. Detection never runs a credential helper, tests a model request, or writes authentication settings. Existing subscription usage readers retain their own behavior; Claude usage remains read-only. See the native Claude authentication rules and Codex authentication options.

Pick the provider for an agent

During agent creation, select the provider, model, and reasoning level. The effort menu follows the selected model exactly:

Provider	Models	Reasoning effort
Claude Code	Opus, Sonnet, Fable; Claude Opus 4.8	low, medium, high, xhigh, max
Claude Code	Claude Opus 4.6, Claude Sonnet 4.6	low, medium, high, max
Claude Code	Haiku	Provider default; no adjustable effort
Codex	GPT-6.1 Sol, GPT-6 Astra, GPT-6 Sol, GPT-5.6 Sol, GPT-5.6 Terra	low, medium, high, xhigh, max, ultra
Codex	GPT-6 Luna, GPT-5.6 Luna	low, medium, high, xhigh, max
Codex	GPT-5.5	low, medium, high, xhigh
Kimi Code	K3	low, high, max
Kimi Code	K2.7 Coding, K2.7 Coding Highspeed	Always thinking; no adjustable level
OpenCode	DeepSeek V4 Pro, DeepSeek V4.1 Flash	high, max
pi	Live from pi (get_available_models)	minimal, low, medium, high, xhigh, max (pi --thinking; the model decides what it honors)
Grok Build	Live model catalog	Whatever the selected model advertises
Antigravity	Live from the signed-in account (for example Gemini 3.8 Flash)	Whatever the selected model advertises (thought_level, for example low, medium, high)

OpenCode agents can use DeepSeek V4 Pro or DeepSeek V4.1 Flash. Their DeepSeek API key stays in OpenCode's machine-level credential store; Anima does not copy it into the agent's Launch environment.

pi agents address models as provider/id (for example google/gemini-2.5-pro or deepseek/deepseek-v4-pro). The dashboard model menu is read live from pi (get_available_models), so it lists only the models the machine's pi credentials can reach; until a credential exists the menu is empty and the panel says so. Provider credentials stay in pi's machine-level store (~/.pi/agent/auth.json) or the Anima service environment; per-agent *_API_KEY values are not passed to pi.

For Grok Build, Anima reads the current model catalog from the installed CLI (for example grok-4.5 and grok-composer-2.5-fast) and records the actual model ID returned by the runtime. Reasoning effort is per model: only models that advertise effort support show an effort control (Composer does not). The grok-build marketing alias is never stored as model authority.

Antigravity agents use the models the signed-in Google account can reach; the dashboard reads that list live from agy acp. Plans differ: Gemini 4 Argon needs a paid Google AI plan, while Gemini 3.8 Flash works on the free tier. If an agent is configured for a model the account does not offer, its turn fails with the list of available models instead of silently running a different one. The sign-in stays in Antigravity's machine-level keychain entry; Anima does not copy it. The Antigravity desktop app installs its own agy editor launcher; Anima refuses that one, so keep the CLI's ~/.local/bin/agy first on the service PATH.

You can change the provider later from the agent's Profile tab. A provider change starts a fresh provider session after the current work reaches a safe boundary. The agent's MEMORY.md, notes, files, Anima activity, and chat identity remain intact; the previous provider session is archived.

Manage provider versions

Open Settings > Providers in the dashboard to inspect the machine-wide CLI that Anima actually resolves. Each provider row reports its path, installed version, detected installation source, latest check, update state, affected agents, and usage information when those sources expose it.

Anima offers an Update action only when it can prove that the active installation channel can be updated in place without changing PATH ownership or requiring elevated privileges. Other rows show a Copy update command action and the reason automation is unavailable. Copying a command does not install an update: run the displayed command in this machine’s terminal. Copy actions support plain HTTP dashboards and show whether copying succeeded; if copying is blocked, select the displayed command manually.

A provider update:

• changes the shared binary for the host user
• does not log out or edit provider credentials, configuration, MCP servers, plugins, skills, or history
• does not interrupt provider children already running
• takes effect for each agent when its provider session next restarts

Only one machine-wide provider update runs at a time, and new provider children wait until the install and self-check finish. Use the row's running-version state to distinguish the installed binary from a child that is still using the previous version.

Claude Code custom launchers can also offer Update when claude doctor identifies a native version in the host's Claude versions directory, and that binary reports the same version as the launcher. This requires Claude Code 2.1.207 or later, which preserves custom launchers during native updates. Anima runs the verified native updater with its private update profile, then checks the version through the original launcher and verifies that the launcher has not changed. The launcher and its account settings remain operator-owned. See the official custom launcher update behavior.

A launcher with CLAUDE_PIN_VERSION stays manual; Anima does not remove or rewrite that setting. Other launcher-specific pins can prevent the new version from becoming active. If the original entry still reports the old version after installation, the update fails its self-check. An unrecognized doctor response or native path also leaves the row manual. Custom launchers do not receive an automatic reinstall command, because Anima has not verified how to restore that entry.

Limit Kimi and Grok context cost

The Providers panel includes one machine-wide Context limit control for Kimi Code and Grok Build. It is global for every Anima agent using that provider; it is not copied into each agent's Launch environment.

Anima writes the provider's supported model setting in the host user's CLI configuration:

• Kimi: max_context_size in the model table;
• Grok: auto_compact_threshold_percent in the session table, calculated from the installed model catalog so the automatic compaction threshold is at or below the selected token count.

The recommended choices are 256k for Kimi and 200k for Grok. A smaller window makes the provider compact a long session earlier; No Anima limit removes Anima's managed cap. The change applies when each provider session next starts, so saving it does not interrupt current work.

Anima marks the exact lines it owns and preserves the rest of each TOML file. The first explicit save adopts an existing value for the setting it manages; choosing No Anima limit later removes that adopted key. Older Anima-managed Grok context_window lines are removed when the setting is next saved or applied at launch.

Troubleshooting

The CLI works in a terminal but onboarding says it is missing

Compare the service environment with your interactive shell. Confirm the executable is on the service PATH, then restart the Anima services only after existing work is idle or drained.

The provider is present but the first turn fails authentication

Open the provider CLI directly under the same host user and complete its login flow. Do not use Anima Restart as a remedy for quota, billing, or authentication errors.

The account shown is not the one you expected

The label reflects the provider credential store available to the Anima host user. For Claude Code, check the machine default in Providers and any CLI or launcher overrides. Resolve the account choice inside the provider CLI or your external account switcher. Logging out can clear shared credentials, configuration, MCP servers, plugins, skills, or history, so review the provider's behavior before changing a shared machine login.

For data and credential boundaries, see Security and data. For adapter implementation details, see Provider layer.