Choose an AI provider for CoWork OS

CoWork OS is free and open source. Running a task requires a working model connection: a supported cloud API, an eligible account sign-in route or a local model. CoWork OS does not resell model access.

Pick one route before adding fallbacks

Open Settings → AI & Models → Model Access, connect your route, refresh the model list and test the connection. Choose a model that supports your task. For local operation, the documentation covers Ollama, MLX on Apple Silicon and other local options; check the runtime requirements before installing a model.

A task access profile controls what the agent may do. It does not change your provider’s billing, subscription eligibility or data handling. Cloud models and connected services can receive task data even though the app stores work locally.

Download CoWork OS and follow the first-task setup if you have not installed it yet. The reference tables below describe individual connections.

Access Types

Supported accounts and subscriptions

Account-based routes use provider-controlled authentication. They are not universal subscription compatibility, and an eligible plan does not guarantee that every request is included in a subscription allowance.

APIs, gateways, and cloud credentials

Direct API routes are billed by the configured provider. Compatible endpoints and gateways let organizations use existing routing infrastructure while keeping the CoWork work surface.

Local models

Ollama, MLX-LM, Hugging Face local routes, and the optional Atomic Chat adapter can keep inference on the machine. Cloud routes send prompts and authentication data to the configured provider as required to complete requests. See the dedicated MLX-LM Local Inference guide for Apple Silicon setup, runtime details, and troubleshooting. See Atomic Chat inference for the inference-only local API integration.

Built-in Model Routes

Compatible, Gateway, and Additional Routes

Your usage is billed directly by your provider. CoWork OS does not proxy or resell model access or promise that a commercial provider includes third-party-harness usage in a plan.

---

Ordered LLM Fallback Chains

CoWork OS can route a task through an explicit provider/model fallback chain instead of relying on a single primary provider.

Configure this in Settings > AI & Models:

• choose your primary provider/model
• add fallback providers in order
• optionally choose capability-based routing for workflow phases or specialized tasks

Fallback chains are used when a provider is unavailable, rate-limited, rejected by policy, or lacks the required capability for the task. Runtime surfaces in the app and Mission Control show the active provider, routing reason, and whether a fallback occurred.

For LLM chains, retryable provider failures such as 429 rate limits and transient upstream errors move execution to the next configured provider/model in the ordered list. Once a fallback route is active, CoWork OS preserves that working route briefly so retries do not immediately bounce back to the primary provider.

You can control when the primary route is tried again in Settings > AI & Models > Provider Failover > Retry primary after (seconds):

• leave it blank to use the default 60-second cooldown
• set it to 0 to retry the primary on the next route refresh
• set a value up to 3600 seconds to keep the active fallback route longer before probing the primary again

---

Mixture of Agents

Mixture of Agents is a virtual LLM provider for preset-based model collaboration. A preset runs one or more reference advisor models first, then passes their bounded advisory notes to a final aggregator model that answers the task.

Configure it in Settings > AI & Models > AI Model > Mixture of Agents:

• create an enabled preset
• choose the aggregator provider/model
• add reference advisor provider/model slots
• tune advisor token limits, advisory context size, and advisor concurrency
• save settings, then select Mixture of Agents as the provider and the preset as the model

Advisor calls are intentionally tool-free. The aggregator receives the original task messages, tools, and tool choice, so workspace edits, shell commands, browser actions, and MCP calls still happen through the final route.

MoA has two failover layers:

• slot-level failover from each selected provider's own fallback chain
• optional MoA-provider failover for falling back from the whole preset to another provider/model

MoA does not automatically inherit global fallback providers. Configure MoA provider failover only when you want the entire preset to fall back after the MoA route fails.

See Mixture of Agents for preset design, runtime behavior, UI testing, and corporate TLS troubleshooting.

---

Prompt Caching

CoWork OS enables prompt caching by default in auto mode for supported model routes. The cacheable prefix is built from session-scoped prompt sections, while volatile turn context stays outside the stable prefix so follow-ups and routed turns can keep reusing the same provider-side foundation.

Strategy by provider family

• Claude API / Azure Anthropic / Anthropic-compatible: CoWork sends structured systemBlocks and prefers Anthropic automatic caching. If a route rejects automatic cache control, the session downgrades to explicit Anthropic breakpoints.
• OpenRouter Claude: CoWork uses explicit cache breakpoints over the stable system prefix plus the last 3 non-system messages, with a maximum of 4 total breakpoints.
• OpenAI / Azure OpenAI: CoWork derives a deterministic stable-prefix cache key and sends it through OpenAI-style prompt-cache fields. This keeps GPT routes such as gpt-5.4 and gpt-5.4-mini aligned under the same stable-prefix strategy.
• OpenAI ChatGPT subscriptions: CoWork forwards the stable cache session and the configured short/long retention to the Codex Responses transport, so subscription calls use the provider's cache-write path as well as API-key calls.
• OpenRouter automatic routes: CoWork participates in stable-prefix partitioning and cache-epoch tracking, sends model-scoped OpenRouter session affinity, and does not add Anthropic-specific markers.
• OpenRouter Qwen/DeepSeek explicit-cache routes: CoWork uses Anthropic-compatible cache_control breakpoints where OpenRouter documents that syntax; other OpenRouter models use router-managed implicit caching and fall back cleanly if a route rejects the optional metadata.
• Bedrock Claude and Pi-backed Claude/OpenAI routes: CoWork forwards the provider-native cache retention controls (Bedrock cache points or pi-ai cache options) and preserves cache-read/cache-write usage in telemetry.

What stays cacheable

Cacheable prefix material comes from stable session-scoped sections such as:

• identity and safety core
• workspace / worktree context
• mode and task-domain contracts
• role, personality, and guidelines
• tool policy and rendered tool schema

Dynamic turn-scoped material such as current time, layered memory sections (<cowork_hot_memory>, <cowork_structured_memory>), and turn guidance is intentionally kept outside the stable prefix. Session transcript recall, verbatim quote recall, archive recall, and topic-pack recall are tool-driven, so they only enter the active turn after explicit search_sessions, search_quotes, search_memories, or memory_topics_load use.

Defaults and overrides

• Default mode: auto
• Default TTL: 5m
• Optional long TTL: 1h
• Advanced disable: set promptCaching.mode to off in saved LLM settings or launch with COWORK_PROMPT_CACHE_MODE=off
• Advanced TTL override: COWORK_PROMPT_CACHE_TTL=5m|1h

Telemetry

When an upstream provider reports prompt-cache usage, CoWork records:

• cachedTokens: tokens served from the provider cache
• cacheWriteTokens: tokens spent creating or extending the cache entry, when available
• cacheWriteTtl: the provider-reported 5m or 1h write window when available; otherwise CoWork uses the configured request TTL for local cost estimation

These values flow into Usage Insights and cost accounting.

---

Adaptive Output Budgeting

When COWORK_LLM_OUTPUT_POLICY=adaptive is enabled, CoWork OS applies a shared output-budget policy for agentic execution turns across the main provider families instead of relying on provider defaults.

What it covers

The current rollout resolves explicit output limits for:

• Anthropic-family routes
• Bedrock Claude routes
• OpenAI routes
• Azure OpenAI routes
• Gemini routes
• OpenRouter routes
• a conservative generic fallback for the remaining providers

This policy currently targets execution and follow-up turns first. Explicit chat keeps its separate behavior for now, and legacy mode preserves the older executor path.

Default request budgets

Internal defaults are:

• first execution turn: 8000
• tool-follow-up turn: 16000
• one-shot escalated retry after truncation: 48000
• one-shot escalated retry for Anthropic-family routes: 64000
• generic fallback escalation: 16000

Budget selection is resolved in this order:

1. task-level agentConfig.maxTokens, when present
2. COWORK_LLM_MAX_OUTPUT_TOKENS
3. adaptive family defaults
4. final clamping by known hard caps and context headroom

Transport fields by provider shape

CoWork maps the chosen budget into the provider-appropriate request field:

• max_tokens for Anthropic-style, OpenRouter-style, and most compatible chat-completions routes
• max_completion_tokens for newer OpenAI-style reasoning/chat-completions routes
• max_output_tokens for Gemini and OpenAI-style responses routes

This mapping is resolved centrally so execution behavior stays consistent even when providers differ in field names.

Truncation recovery behavior

If an execution turn hits the output limit:

1. CoWork retries the same request once with a larger budget
2. if the retried response still truncates but contains visible partial output, CoWork falls back to a continuation prompt
3. if the retried response contains only reasoning or no usable answer text, CoWork stops retrying continuations and surfaces targeted guidance instead

This avoids wasting turns on repeated truncation loops that produce no visible answer.

Internal controls

This rollout is currently controlled by environment flags rather than UI settings:

• COWORK_LLM_OUTPUT_POLICY=legacy|adaptive
• COWORK_LLM_MAX_OUTPUT_TOKENS
• COWORK_LLM_AGENTIC_INITIAL_MAX_TOKENS
• COWORK_LLM_AGENTIC_ESCALATED_MAX_TOKENS

COWORK_LLM_OUTPUT_POLICY defaults to legacy unless explicitly set. COWORK_LLM_TOOL_RESPONSE_MAX_TOKENS remains available for legacy compatibility but is no longer the primary behavior in adaptive mode.

---

Azure Anthropic

Use Azure-hosted Claude models through your Azure subscription.

Setup

1. Deploy a Claude model in your Azure AI Studio account.
2. Open Settings > AI & Models > Model Access and select Azure Anthropic.
3. Enter your Azure API key, endpoint URL (e.g. https://<resource>.services.ai.azure.com), and deployment name.

Notes

• Uses the Anthropic messages API format, not the Azure OpenAI format.
• Separate from the existing Azure OpenAI provider — use this for Claude models, Azure OpenAI for GPT models.
• All billing goes through your Azure subscription.

---

Ollama (Local LLMs)

Run inference locally without hosted-model usage charges. After the required models and dependencies are installed, this route can operate offline; hardware and electricity costs remain yours.

Setup

brew install ollama
ollama pull llama3.2
ollama serve

Recommended Models

---

HuggingFace Local AI (hf-agents + llama.cpp)

Run compatible local models through CoWork's HuggingFace Local AI provider.

Setup

pip install huggingface_hub
hf extensions install hf-agents

Then open Settings > AI & Models > Model Access, choose HuggingFace Local AI, select or enter a model, and start the local llama.cpp server from the provider panel.

Notes

• Default local endpoint: http://localhost:8080/v1
• API key is optional for local runs
• Best fit when you want a private local provider but do not want to depend on Ollama

---

MLX-LM (mlx)

Run quantized models natively on Apple Silicon through Apple's open-source MLX framework and the MLX-LM OpenAI-compatible local server. The complete setup, API, lifecycle, privacy, and troubleshooting contract is documented in MLX-LM Local Inference.

Setup

python3 -m pip install --upgrade mlx-lm

Then open Settings > AI & Models > Model Access, choose MLX (Apple Silicon), select a model, and start the MLX Server. CoWork connects to http://localhost:8080/v1.

Recommended starting models:

• mlx-community/Qwen3-8B-4bit for a smaller, faster local model
• mlx-community/Qwen3-14B-4bit for a balanced model
• mlx-community/Qwen3.6-35B-A3B-4bit-DWQ for larger Apple Silicon systems

The MLX server downloads models from Hugging Face on first use and keeps inference local. It is intended for local development, not as a production-exposed service.

---

Atomic Chat (Local)

CoWork can connect to an already-running Atomic Chat instance through its OpenAI-compatible API. This route is an inference adapter: CoWork keeps ownership of the task loop, tools, permissions, approvals, evidence, and persistence. It does not start Atomic Chat, install models, or import Atomic Agent's tool loop.

Setup

1. Start Atomic Chat and load a model.
2. Open Settings > AI & Models > Model Access and choose Atomic Chat (local).
3. Keep the default endpoint http://127.0.0.1:1337/v1, or enter the endpoint exposed by the running instance.
4. Use Refresh Models and select the exact model ID returned by /v1/models.
5. Add an API key only when the Atomic Chat proxy requires authentication.

The initial adapter uses non-streaming /v1/chat/completions requests with a 60-second inference deadline. Discovery has a five-second deadline and retains the existing model selection when discovery fails. See Atomic Chat inference for typed failure states, troubleshooting, and qualification limits. The optional local-model execution profile adds bounded budgets and local admission control without changing the permission model.

---

Google Gemini

1. Get API key from Google AI Studio
2. Configure in Settings > Google Gemini

Models: gemini-2.0-flash (default), gemini-2.5-pro (most capable), gemini-2.5-flash (fast)

---

OpenRouter

Access multiple AI providers through one API.

1. Get API key from OpenRouter
2. Configure in Settings > AI & Models > Model Access > OpenRouter

Available: Claude, GPT-4, Gemini, Llama, Mistral, and more — see openrouter.ai/models

Jev decision support

CoWork also supports Jev Decision Support as a separate structured decision route. Jev can choose an agent team and leader for Collaborative mode and /multitask, and Active harness mode can make bounded model-routing, task-strategy, lane, browser, loop, context, skill/tool, output, and tool-review decisions without replacing the OpenRouter chat model that executes the work. Jev tokens and provider-reported cost are recorded separately from normal LLM usage; Jev does not use the LLM pricing table. To use the OpenRouter route for Jev, save the OpenRouter key here, then select OpenRouter in Settings > AI & Models > Jev and leave key reuse enabled. The same key is used once for both routes.

Pareto Code Router

OpenRouter's Pareto Code Router is available as a normal OpenRouter model selection, not as a separate provider:

When one of those models is selected, Settings > AI & Models > OpenRouter shows a Pareto Router field for the optional minimum coding score.

• min_coding_score is a decimal number from 0 to 1; do not enter percentages such as 80.
• Leave the field blank to let OpenRouter use its default strongest/high coding tier.
• Current OpenRouter tiers are >= 0.66 for high, 0.33 to < 0.66 for medium, and < 0.33 for lower-cost low-tier routing.
• The score is sent through OpenRouter's pareto-router plugin only for openrouter/pareto-code and openrouter/pareto-code:nitro.
• In headless or VPS installs, pass the same value through Control Plane as settings.paretoMinCodingScore, for example {"providerType":"openrouter","model":"openrouter/pareto-code","settings":{"paretoMinCodingScore":0.8}}.
• The response model field can report the concrete underlying model that handled the request, so usage and cost records may show a Claude, GPT, Gemini, DeepSeek, or other routed model rather than the router id.
• The fallback local catalog lists both Pareto models with OpenRouter's documented 200,000 token context. When the live OpenRouter model catalog returns metadata, CoWork keeps the live catalog value instead of overriding it.

The Pareto Router itself adds no extra fee. Billing follows whichever underlying OpenRouter model handles the request, so cost can vary by tier and availability.

Reference: OpenRouter Pareto Router docs and Pareto Code Router model page.

CoWork OS also sends OpenRouter app attribution headers by default so usage is associated with the app in OpenRouter analytics and rankings. The current defaults are:

• HTTP-Referer: https://github.com/CoWork-OS/CoWork-OS
• X-OpenRouter-Title: CoWork OS
• X-Title: CoWork OS
• X-OpenRouter-Categories: personal-agent,programming-app

The category pairing is intentional: CoWork OS is positioned primarily as a personal AI agent, with programming workflows as a secondary fit.

For prompt caching, OpenRouter Claude routes use explicit Anthropic-style cache breakpoints, while GPT-style OpenRouter routes participate in the shared stable-prefix prompt-cache pipeline.

---

OpenAI / ChatGPT

• Option 1: API Key — Standard pay-per-token access to GPT models
• Option 2: ChatGPT OAuth — Sign in with an eligible ChatGPT account

Models with ChatGPT OAuth

The current built-in catalog includes the following GPT-5.6 Codex routes. The signed-in account and OpenAI backend remain the source of truth for which models and controls are actually available:

Reasoning effort is a request control, not a separate model ID. Choose the model first, then set its effort from either:

• the main model picker's Intelligence section for the active task route
• Settings > AI & Models > OpenAI Request Controls for the saved OpenAI provider configuration

The UI only lists efforts supported by the selected GPT-5.6 model. In particular, Ultra is available for Sol and Terra but not Luna. Max requests the deepest standard reasoning mode; Ultra requests maximum reasoning with the ChatGPT/Codex automatic task-delegation mode. The selected effort and response verbosity are forwarded to the ChatGPT Codex Responses transport for OAuth requests.

All three GPT-5.6 models support Low, Medium, and High response verbosity. The verbosity control changes final-answer detail independently of reasoning effort.

Model and effort availability remains account-, plan-, and entitlement-dependent. If a model is listed locally but the ChatGPT backend rejects it, refresh the model list, confirm the signed-in account has access, or select an available model/effort combination.

---

xAI / Grok

CoWork OS supports Grok through either direct xAI API billing or a browser OAuth account connection. Account eligibility, model access, limits, and charges remain controlled by xAI.

Option 1: Grok Account Connection

Use this when the OAuth route is available to your xAI account and you do not want to manage an XAI_API_KEY.

1. Open Settings > AI & Models > Model Access.
2. Select Grok OAuth or open the xAI provider panel and choose the account connection shown there.
3. Click Sign in with Grok.
4. Complete the xAI browser sign-in and consent flow.
5. Refresh the model list and select a model available to the connected account.
6. Click Test Connection, then save settings.

CoWork stores the OAuth tokens in encrypted LLM settings for the current profile and refreshes the access token before model calls. Logging out from the same panel clears the stored xAI OAuth tokens without removing an xAI API key.

Option 2: xAI API Key

Use this when you want pay-per-token API billing through the xAI developer console.

1. Create or copy an API key from xAI Console.
2. Open Settings > AI & Models > Model Access and select xAI API Key.
3. Paste the key, click Refresh Models, choose a model, then save.

Models

The built-in Grok catalog provides fallback model metadata for the OAuth route. Refreshing models against the connected account is the source of truth:

Transport and endpoint

The OAuth route uses xAI's Responses-style endpoint at https://api.x.ai/v1. The direct API-key route continues to use the OpenAI-compatible xAI API path. The Base URL field can override the endpoint for either mode when xAI changes deployment requirements or when testing a compatible gateway.

Troubleshooting

• If the browser sign-in times out, start Sign in with Grok again. The loopback authorization window is intentionally finite.
• If the callback port is busy, CoWork falls back to an ephemeral local port automatically.
• If token refresh fails because the xAI session was revoked, disconnect the Grok account in Settings and sign in again.
• If a model call fails with an account, plan, or entitlement error, refresh the model list and confirm that xAI permits the requested route for the signed-in account.

References: xAI Grok + Hermes announcement and Hermes xAI Grok OAuth docs.

---

Web Search Providers

Multi-provider web search for research tasks with automatic retry and fallback. DuckDuckGo is built-in and requires no setup — it serves as a free fallback so web search always works, even without API keys.

DuckDuckGo is always available as the last-resort fallback. When paid providers are configured, they are tried first in the configured order, with DuckDuckGo only used if all others fail. Search settings also support explicit primary/fallback ordering and provider cooldown behavior after repeated failures.

Configure paid providers in Settings > Web Search.