Providers

A provider is the ACP-compatible command CompozyOS launches for an agent. The provider owns the actual LLM integration. CompozyOS owns definition resolution, process lifecycle, workspace boundaries, permissions, MCP server wiring, and event persistence.

Provider IDs appear in AGENT.md:

---
name: implementation
provider: codex
---
You implement scoped changes and verify them before handoff.

Or they can be selected globally:

[defaults]
agent = "general"
provider = "claude"

Built-in providers

The built-in registry lives in internal/config/provider.go.

Authentication modes

Provider authentication is explicit. CompozyOS does not infer that every provider needs a CompozyOS-managed API key.

Direct ACP providers and the direct pi provider default to native_cli. Pi-backed API-key wrappers default to bound_secret because their public provider contract is an API key managed by CompozyOS. Custom providers with credential_slots default to bound_secret; custom providers without slots default to native_cli unless auth_mode = "none" is set explicitly.

native_cli providers cannot define credential_slots. If you intentionally want CompozyOS to inject a key into a native ACP command, set auth_mode = "bound_secret" in the provider override and define the slots there. This keeps secret injection opt-in and prevents daemon shell variables from silently overriding a provider's own login state.

Provider config fields

Provider overrides and custom providers are configured in config.toml.

auth_mode = "none" is an explicit No auth required contract, not an authenticated state. Set none_security to describe why the provider is safe without credentials: local_transport for local-only transports, external_identity when another system authenticates the caller, or public_readonly for public read-only providers. No-auth providers cannot define credential_slots, auth_status_command, or auth_login_command; CompozyOS rejects those combinations at config load time.

CompozyOS overlays provider config on top of a built-in provider when the name matches. Unknown provider names are accepted only when they have a [providers.<name>] entry.

Configure and inspect native login

auth_login_command is a write-only configuration input. Set it in config.toml, with the operator CLI, or through the compozy__config_set native tool. For example:

compozy config set providers.local-agent.auth_login_command "local-agent auth login" -o json

The command is accepted for the write but is redacted in the response. It is also redacted from compozy config show, list, get, and diff; configuration reads, provider status and doctor, Settings, HTTP, and UDS never reveal the command, its arguments, or its resolved path.

Those read surfaces expose a login descriptor instead. It contains only configured, the fixed source value auth_login_command, the executable basename, presence (present, missing, or unknown), and a recovery recommended_action: install_cli, login, bind_secret, retry, inspect, or no_retry. Use that action and the provider auth state to decide what to do next; do not treat the descriptor as a command you can copy or execute.

Built-in provider aliases are intentionally small and resolve before launch. Common aliases such as claude-code, ai-gateway, vercel, kimi, glm, x.ai, grok, open-code, and qwen resolve to their canonical provider IDs. Model IDs do not alias: configuration, catalog rows, session diagnostics, CLI, and ACP negotiation use the exact canonical model ID. A shorthand or unknown model ID never resolves to the provider default.

The old providers.<id>.aliases config key was removed for v1. Reference providers by canonical name only; config files that set aliases = [...] under a provider are rejected during load.

The flat keys default_model, supported_models, and supports_reasoning_effort are no longer accepted. Config that still sets them is rejected at load time with a deterministic hard-cut error that names the exact path. Move every value into the nested [providers.<id>.models] block below.

Provider models

Each provider declares pre-session model defaults and curated metadata under [providers.<id>.models]. Pre-session model selection is served by the daemon-owned model catalog. The catalog merges builtin defaults, the operator config, the optional models.dev enrichment source, live provider discovery sources, and extension model sources, then projects them through HTTP, UDS, CLI, the OpenAI-compatible projection, the Host API, and the web. Active ACP configOptions continue to govern model and reasoning controls inside a running session.

Rate changes apply to subsequent usage updates. CompozyOS does not reprice stored token statistics, and an agent-reported actual amount always takes precedence over catalog estimation. Every nonzero input, output, cache-read, cache-write, or reasoning bucket requires its own finite, non-negative rate. CompozyOS does not substitute input rates for cache tokens or output rates for reasoning tokens.

Provider Settings PUTs distinguish omission from an explicit membership change. If models.curated is omitted, CompozyOS preserves the server-owned raw membership even when catalog sources are temporarily unavailable. A present empty array is an explicit membership clear and fails with 503 Service Unavailable when CompozyOS cannot enumerate the current catalog sources. For a present array, CompozyOS compares every entry with the current effective catalog projection and persists only explicit deltas, including the five pricing fields, without copying unchanged catalog enrichment into config.toml. Use the request-level model_curation object or the atomic curation endpoint when the change is limited to hidden, featured, deprecated, or a default reasoning effort.

Discovery uses the resolved provider auth, env, and home policy. Most adapters do not create an ACP session. Cursor is the exception: cursor-agent acp starts a short-lived inspection session that reads the exact values advertised by Cursor's model option. The human-readable cursor-agent models aliases are not model IDs for CompozyOS. When a discovery path is unavailable or fails, the model catalog records a source status and falls back to stale or lower-priority rows. An explicit Cursor model refreshes this catalog before creation and must match a fresh advertised value; leaving the model blank preserves Cursor's native default. Cursor uses the operator home required by its native login and runs again only through an explicit catalog refresh. Changes under models.discovery apply live: CompozyOS atomically rebinds and refreshes only the changed provider source. Model metadata edits do not invoke provider discovery, and a failed live refresh keeps prior rows stale instead of rejecting the config write.

Session creation can override provider, model, reasoning_effort, and speed for one launch. Speed is provider-neutral, accepts normal | fast, and defaults to normal. Authoring accepts a custom model ID as a candidate because models.curated is metadata, not an allowlist. The active ACP adapter must still advertise or accept that exact ID; otherwise start fails with model_unavailable instead of falling back.

modelcatalog.ReasoningEffort is the single enum: none | minimal | low | medium | high | xhigh | max. Each model exposes only its actual subset. Catalog/config/live observations are the only sources; model-name prefixes never fabricate effort levels. supports_reasoning=true with an empty effort list is valid and means the provider decides.

Claude and Codex built-ins use models.reasoning.apply = "acp_option"; custom and pi_acp providers default to none unless explicitly configured. Strategy none means CompozyOS has no effort application strategy. It is distinct from explicit effort none, which is sent through ACP when the active model advertises it.

Negotiation order is deterministic: session mode, model, the refreshed config-option snapshot returned by that model change, reasoning effort, speed, then the first prompt. Empty effort sends no RPC; explicit none does. The live ACP snapshot is authoritative even when its effort set is empty. Missing or unsupported model/reasoning options fail before the first prompt with stable diagnostics. Speed V1 writes only an unambiguous ACP select/value-ID option; boolean speed options remain unsupported until the released ACP capability contract can advertise boolean writes. Missing or ambiguous speed options report a durable unsupported outcome, while provider rejection returns speed_rejected before the first prompt.

See Provider Model Catalog for the curated Claude/Codex seeds, curated/all views, curation surfaces, and error codes.

Native provider auth state belongs to the provider. Run the provider's own login command, such as claude auth login, codex login, opencode auth login, or Pi's /login, outside CompozyOS or through a configured auth_login_command. The built-in claude, codex, opencode, and pi providers expose those login commands through compozy provider auth login <provider>. That CLI command executes the configured login command locally and attaches the terminal when stdin, stdout, and stderr are TTYs, so OAuth URLs and provider prompts remain visible. It then returns the redacted provider status and safe login descriptor. Use --no-tty for deterministic non-interactive runs and --timeout when scripts need a bounded login attempt; these are its only flags. When a provider uses home_policy = "isolated", CompozyOS runs the native login with its provider home so credentials land where CompozyOS will use them, without displaying the environment prefix or resolved command. HTTP and UDS never execute login commands; they only run non-interactive auth_status_command probes. Wrapped API-key providers use their configured credential_slots instead of Pi login. Custom providers should set auth_mode to match the runtime's real authentication contract.

Override a built-in provider

Use this when you need to pin a different adapter command or change the default model used by agents that omit model.

[providers.claude]
auth_mode = "native_cli"
auth_status_command = "claude auth status"
auth_login_command = "claude auth login"

[providers.claude.models]
default = "claude-sonnet-5"

[providers.claude.models.reasoning]
apply = "acp_option"

[[providers.claude.models.curated]]
id = "claude-sonnet-5"
display_name = "Claude Sonnet 5"

[[providers.claude.models.curated]]
id = "claude-fable-5"
display_name = "Claude Fable 5"
featured = true
release_date = "2026-06-09"

[[providers.claude.mcp_servers]]
name = "github"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
secret_env = { GITHUB_TOKEN = "env:GITHUB_TOKEN" }

Only non-empty scalar fields replace the built-in values. MCP servers merge by name.

Configure wrapped API-key providers

OpenRouter, z.ai, Moonshot/Kimi, Vercel AI Gateway, xAI, MiniMax, Mistral, and Groq are built-in wrapped providers. Operators select them directly, and CompozyOS uses Pi only as the underlying ACP adapter. These built-ins default to auth_mode = "bound_secret" with required provider-key slots. Override the slot when you want CompozyOS Vault, rather than the daemon environment, to own the launch-time credential.

[providers.openrouter]
display_name = "OpenRouter"
harness = "pi_acp"
auth_mode = "bound_secret"
runtime_provider = "openrouter"
command = "npx -y pi-acp@latest"

[providers.openrouter.models]
default = "openai/gpt-5.4"

[[providers.openrouter.models.curated]]
id = "openai/gpt-5.4"
display_name = "OpenAI GPT-5.4"

[[providers.openrouter.credential_slots]]
name = "api_key"
target_env = "OPENROUTER_API_KEY"
secret_ref = "env:OPENROUTER_API_KEY"
kind = "api_key"
required = true

For CompozyOS-managed encrypted storage, use a vault:providers/<provider>/<slot> ref and save the value through the settings API or web provider editor. The <provider> and <slot> segments are lowercase provider/slot identifiers using letters, numbers, hyphens, underscores, or dots; path traversal, whitespace, and arbitrary vault paths are rejected.

[[providers.openrouter.credential_slots]]
name = "api_key"
target_env = "OPENROUTER_API_KEY"
secret_ref = "vault:providers/openrouter/api-key"
kind = "api_key"
required = true

CompozyOS never exposes provider secret values through settings reads. Status surfaces report only whether the bound credential is present.

Add a custom provider

A custom provider needs an ACP-compatible command. CompozyOS will launch it the same way it launches the built-ins.

[providers.local-agent]
command = "local-agent --acp --stdio"
auth_mode = "native_cli"
auth_status_command = "local-agent auth status"
auth_login_command = "local-agent auth login"

[providers.local-agent.models]
default = "local-default"

[[providers.local-agent.models.curated]]
id = "local-default"
display_name = "Local Default"

[[providers.local-agent.mcp_servers]]
name = "filesystem-index"
command = "local-index-mcp"
args = ["serve"]

Then point an agent at the custom provider:

---
name: local-operator
provider: local-agent
permissions: approve-reads
---
You inspect this repository with the local agent runtime.
Report risks and cite exact files.

If the custom provider has no authentication at all, set auth_mode = "none" and document the reason with none_security:

[providers.local-readonly]
command = "local-readonly-agent --acp"
auth_mode = "none"
none_security = "local_transport"

No-auth providers render as No auth required in status, doctor, web, and CLI output. They cannot define credential slots or login/status commands. If a custom provider requires a CompozyOS-managed key, use auth_mode = "bound_secret" and define credential_slots:

[providers.team-gateway]
command = "team-gateway acp"
auth_mode = "bound_secret"

[[providers.team-gateway.credential_slots]]
name = "api_key"
target_env = "TEAM_GATEWAY_API_KEY"
secret_ref = "vault:providers/team-gateway/api-key"
kind = "api_key"
required = true

Command parsing

Provider commands are parsed with shell-style quoting, then launched without a shell. That means:

• quoted arguments are preserved
• shell expansion is not performed
• the executable must be available on the daemon process PATH
• npx-based built-ins can download and run their adapter package through the local Node toolchain

For example, this is valid:

[providers.reviewer]
command = "reviewer-acp --profile \"team default\""

But shell-only behavior is not applied:

[providers.bad-example]
command = "MY_FLAG=1 reviewer-acp"

Set environment variables before starting the daemon instead.

Models and authentication

model and models.default are resolved and exposed as runtime metadata. Direct acp providers receive the normal ACP startup flow. Native pi sessions receive the resolved runtime_provider/model through ACP model selection. Wrapped Pi-backed API-key providers receive session-local Pi settings.json and models.json so Pi can run with the CompozyOS-selected provider, model, and injected credential while the operator-facing provider remains OpenRouter, z.ai, Moonshot/Kimi, Vercel AI Gateway, xAI, MiniMax, Mistral, or Groq.

The practical rule is:

• use model in AGENT.md when you want CompozyOS metadata and provider-specific wrappers to agree on the intended model
• use native_cli when the provider command owns login state, session files, or browser/device auth
• use bound_secret plus credential_slots when CompozyOS should inject a specific API key into the subprocess
• use env: refs for service-manager-owned secrets and vault:providers/<provider>/<slot> refs for CompozyOS-managed encrypted provider credentials

MCP server merge order

MCP servers can be declared at several levels. Startup uses this order:

1. Top-level mcp_servers from resolved config
2. Provider mcp_servers
3. Agent mcp_servers
4. Active skill MCP servers

Config/provider/agent merges are field overlays by server name. Agent-local mcp.json sidecars replace same-name inline servers as whole objects before that cross-scope merge happens. Configured MCP env values are passed through as literal strings. Pi-backed providers are launched through pi-acp; current Pi ACP support does not wire CompozyOS MCP server declarations into Pi's own MCP configuration.

Choosing a provider

Use the provider that already owns your credentials and preferred operating path:

Then keep provider-specific behavior in the provider command or provider config, and keep the agent's role, permissions, MCP servers, and startup prompt in AGENT.md.

Related pages

• Agent Definitions explains the AGENT.md fields that reference providers.
• Spawning shows exactly how the resolved provider command becomes a running ACP process.
• Provider Model Catalog covers the daemon-owned catalog, sources, refresh lifecycle, OpenAI-compatible projection, and extension model.source.
• CLI agent reference lists the current compozy agent inspection commands.
• compozy provider models CLI inspects and refreshes the catalog without a UI.