Each section below sets up one provider. The general steps, the test and the default provider are on the overview; every setting of the file is in Configuration file.
Subscriptions need no API key: Claude Code for a Claude plan, Codex for a ChatGPT plan, Copilot for GitHub Copilot, xAI Grok for SuperGrok. Their credentials stay in CodeAlta's own state, apart from API keys.
For an API-key provider, put the key in an environment variable and name it with api_key_env:
# macOS/Linux
export CODEALTA_OPENAI_API_KEY="..."
# PowerShell
$env:CODEALTA_OPENAI_API_KEY = "..."
Set the variable where CodeAlta starts, then restart CodeAlta. Started from the Start Menu, the Dock or the applications menu, CodeAlta Desktop sees the variables of your user session, not those of a terminal.
The claude-code provider runs your sessions through the Claude Code CLI, with the account it is signed in to. This is how a Claude subscription is used from CodeAlta: Anthropic does not let other applications sign in to a Claude account.
/login. An API key or a cloud provider configured for the CLI works too.CodeAlta never sees your Claude credentials. Usage counts against the account the CLI is signed in to, with the limits of its plan.
Each version of CodeAlta is tested with one version of Claude Code. CodeAlta runs, in this order:
command names, when the provider has one;~/.alta/cache/claude-code/<version>/<platform>;PATH or where its installers put it (~/.local/bin, Homebrew, npm). When it is another version, Test says so.On Windows, CodeAlta runs the native claude.exe, not the claude.cmd of an npm installation: without the native installer, download the tested version.
Each Claude account is a provider of its own, with its own folder for Claude Code: its login, settings, memory and conversations.
claude-code-2 with the same settings.~/.claude-work, and save.A new folder starts empty: copy the settings, CLAUDE.md or MCP servers you want from your usual folder (~/.claude). The conversations of the provider are in its folder too: Copy resume command and Run in terminal set CLAUDE_CONFIG_DIR to it, and Open in VS Code is refused, because VS Code opens conversations from the folder of its own account (see Open a session in VS Code or a terminal). Changing the folder of a provider that has sessions asks first: their conversations stay in the old folder, where Claude Code no longer finds them.
When ANTHROPIC_API_KEY is set, Claude Code started by another application uses it without asking, and bills the API account of the key instead of your plan. CodeAlta follows the answer you gave Claude Code for that key: with No, it starts Claude Code without the variable, so your login is used.
When Claude Code has no answer for the key, a session does not start, and its error says what to choose: ANTHROPIC_API_KEY in the provider editor (use it, or ignore it and use your Claude login), or anthropic_api_key in the file. The variable is left alone when Claude Code uses Bedrock, Vertex AI or Foundry.
A session of this provider is a Claude Code session shown in CodeAlta:
Read, Edit, Bash...), settings, permission rules, hooks, skills and CLAUDE.md files. CodeAlta adds its own instructions (agent prompt, skills, AGENTS.md) to the prompt, and gives what changed with your next prompt when they change.mcp__codealta__<name>: the alta tool, plugin tools and the tools of the MCP servers you activated.projects of the account folder; when that transcript is gone, the session goes on in a new conversation that starts with the history CodeAlta recorded.permission_mode = "plan" in the provider, a session stays read-only and gives its plan as its answer.default, acceptEdits, plan, auto, dontAsk or bypassPermissions. Left blank, your Claude Code settings choose. In CodeAlta Desktop it is also the default mode of the provider's sessions: with bypassPermissions what the CLI asks is approved, otherwise you are asked.plan stays a provider setting. In Ask first, Claude Code still runs by itself what it holds to be safe, such as a command that only reads./compact). A prompt that starts with / is a Claude Code slash command.~/.claude/projects/<folder>/<session>/tool-results.[providers.claude-code]
type = "claude-code"
model = "sonnet" # optional
reasoning_effort = "high" # optional: low, medium, high, xhigh, max
config_dir = "~/.claude-work" # optional: the folder of the account (default: ~/.claude)
command = "~/.local/bin/claude" # optional: a Claude Code of your own
permission_mode = "default" # optional: default, acceptEdits, plan, auto, dontAsk, bypassPermissions
anthropic_api_key = "ignore" # optional: use or ignore ANTHROPIC_API_KEY (default: your answer in Claude Code)
args = ["--add-dir", "/specs"] # optional: more arguments for the CLI
config_dir is a full path or starts with ~; Claude Code gets it as CLAUDE_CONFIG_DIR. A command that is a name is looked for on PATH, then in the folders of the Claude Code installers. The provider takes no api_key, api_key_env or api_url.
The codex provider uses your ChatGPT plan. It is separate from OpenAI platform API keys.
[providers.codex]
enabled = true
display_name = "Codex"
type = "codex"
model = "gpt-5.5"
reasoning_effort = "high"
Sign in with Sign in with the browser (CodeAlta Desktop) or Continue with ChatGPT (CodeAlta TUI), and authorize CodeAlta in the system browser. No developer account or key is needed. The browser returns to 127.0.0.1 on the computer that runs CodeAlta, so it must reach that computer.
type = "codex" provider with its own display_name, even for the same email address. Account Info shows the account it signed in to.invalid_grant at the first sign-in: sign in again; the retry reuses the same registration.auth_source or set auth_source = "codealta_oauth".Credentials are written under CodeAlta's state folder, protected with Windows DPAPI or owner-only permissions on Unix: never copy them into source control or a report. Plan usage is at ChatGPT Settings → Usage; to see it in CodeAlta, see Subscription usage. For a second account whose Codex CLI uses another folder, set codex_home to that folder.
The model can search the web through your plan; OpenAI runs the search during the answer. Each search shows as a web_search tool call, and the answer cites its sources.
[providers.codex]
type = "codex"
web_search = "live" # "cached" (the default), "live" or "disabled"
cached: the index OpenAI keeps, which can be a little behind the web.live: the web as it is now.disabled: no search.What a search costs of your plan, and whether your workspace allows it, depend on your account. A compaction summary never searches.
Fast routing is off by default. To turn it on:
[providers.codex]
type = "codex"
service_tier = "priority" # "fast" is an alias
service_tier = "default", or no setting, returns to standard routing.CodeAlta offers the reasoning efforts Codex lists for each model; GPT-5.6 Sol, Terra and Luna go up to max. Codex's ultra level is not offered. A model can ask for several tool calls in one answer; CodeAlta runs them one after the other.
[providers.copilot]
enabled = true
display_name = "Copilot"
type = "copilot"
model = "claude-sonnet-4.6"
reasoning_effort = "high"
auth_source = "github_device_flow"
Sign in with Sign in with the browser or Sign in with a device code. Where nobody can sign in, set auth_source to read a GitHub token or a Copilot token from an environment variable (see Codex, Copilot and xAI). Each model is called through the endpoint Copilot lists for it: Messages for Claude, Responses for GPT and Grok, chat completions otherwise.
The xai provider uses the xAI API at https://api.x.ai/v1. Its sign-in unlocks SuperGrok and Grok Heavy on accounts that subscribed.
[providers.xai]
enabled = true
display_name = "xAI Grok"
type = "xai"
model = "grok-4.3"
reasoning_effort = "high"
auth_source = "xai_browser_oauth"
xai_browser_oauth: sign in in the browser.xai_device_flow: sign in with a device code, for a computer without a browser (SSH, server).CodeAlta renews the tokens by itself. The models listed are the text models of xAI (grok-4.3, grok-4, grok-4-fast when the list cannot be read).
[providers.openai]
enabled = true
display_name = "OpenAI"
type = "openai-responses"
model = "gpt-5.5"
reasoning_effort = "high"
api_key_env = "CODEALTA_OPENAI_API_KEY"
api_url = "https://api.openai.com/v1"
Use openai-chat for an endpoint that speaks the Chat Completions API. A reasoning model of the OpenAI API shows its reasoning summary in the timeline.
[providers.anthropic]
enabled = true
display_name = "Anthropic"
type = "anthropic"
model = "claude-sonnet-4-6"
api_key_env = "CODEALTA_ANTHROPIC_API_KEY"
An Anthropic-compatible provider uses the same type with its own api_url, and single_model_id when it lists no models.
output_token_limit in its model overrides.refusal_fallback = false turns it off for the provider.@, or a Markdown link) reaches a Claude model that reads PDFs, of Anthropic or of Claude Code, as the document itself, up to 20 MB. Other models get its text (see Attach files).google-genai uses the Gemini API with an API key. Leave model unset to choose among the models it lists:
[providers.gemini]
enabled = true
display_name = "Gemini"
type = "google-genai"
api_key_env = "CODEALTA_GEMINI_API_KEY"
model = "gemini-2.5-pro"
vertex-ai uses a Google Cloud project and location instead of a key; both are required:
[providers.vertex]
enabled = true
display_name = "Vertex"
type = "vertex-ai"
project = "my-gcp-project"
location = "europe-west4"
models_dev_provider_id = "google"
model = "gemini-2.5-pro"
reasoning_effort = "high"
Azure names models by deployment: set model, or single_model_id, to your deployment name. Azure lists no models, so the deployment of model is the one shown.
[providers.azure-openai]
enabled = true
display_name = "Azure OpenAI"
type = "azure-openai"
model = "my-gpt-4o-mini-deployment"
api_key_env = "CODEALTA_AZURE_OPENAI_API_KEY"
api_url = "https://your-resource.openai.azure.com"
network_timeout_seconds = 180
Raise network_timeout_seconds (100 seconds by default) when long answers fail on a network timeout.
[providers.mistral]
enabled = true
display_name = "Mistral"
type = "mistral"
api_key_env = "CODEALTA_MISTRAL_API_KEY"
model = "mistral-small-latest"
models_dev_provider_id = "mistral"
Alibaba Cloud Model Studio has an OpenAI-compatible Chat API:
[providers.alibaba]
enabled = true
display_name = "Alibaba"
type = "openai-chat"
model = "qwen3.7-max"
api_key_env = "CODEALTA_ALIBABA_API_KEY"
api_url = "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
CodeAlta already sends what this API expects: no developer role, no store, max_tokens for the output limit, no reasoning_effort, the usage of a streamed answer, and Alibaba's thinking with enable_thinking and preserve_thinking. Other Alibaba parameters (thinking_budget, top_k, enable_search, search_options) are yours to add in request.extra_body; see Request customizations.
Any endpoint that speaks a supported API works as a provider of your own: Custom provider… in Add provider, or a table in the file with its type, api_url and key.
openai-responses or openai-chat; see Request customizations for their headers.openai-chat with their local api_url.single_model_id (see Single-model endpoints); one that behaves differently from the API it imitates takes a compatibility profile.