Setting up providers
A provider in Polycode is anything that can answer a prompt — a frontier API behind a key, an on-device Apple model, a local Ollama instance, or an enterprise cloud gateway. Every model you enable from an un-muted provider becomes a peer in the fan-out: each one gets a copy of your prompt, each one streams back, and the inspector records what they cost. This article walks the catalog and the settings that go with it.
The catalog
Polycode supports eight provider kinds out of the box, grouped into a few families:
- Anthropic, OpenAI, Google — direct calls to the frontier APIs using your own keys. Each gets a row in Settings → Providers.
- Apple Intelligence (Foundation Models) — runs on the Neural Engine. No key, no network, no cost. Its row is always listed; one click on Enable connects it on a Mac that can run Apple Intelligence.
- OpenAI-compatible endpoints — anything that speaks the OpenAI chat completions shape: Ollama, LM Studio, xAI, OpenRouter, vLLM, your own internal gateway. All of them go through the same OpenAI-compatible endpoint sheet — name it, point it at the base URL, add a key if the endpoint wants one. Add one or many from Add provider.
- Cloud gateways — Vertex AI, AWS Bedrock, and Azure OpenAI Service for teams that already have cloud spend committed.
What the tab shows
Settings → Providers leads with what happens when you hit Send, not with accounts. At the top sits the primary card — the model that writes the final answer, ringed in accent, with its role and per-1M pricing. Below it, the peers strip shows one removable chip per model that answers in parallel, and an Add model menu lists each provider’s full roster so you can grow the panel without leaving the page. Only models you explicitly enable fan out — Polycode never dispatches a model you didn’t pick.
Under the strip, a status line keeps the run honest. With at least one peer it shows an estimated cost per exchange, computed from each participating model’s published pricing (“how is this estimated?” discloses the token assumptions; models without pricing metadata are called out rather than silently priced at zero). If the primary would run alone, the line becomes a solo warning — “Primary is running solo — add at least one peer for consensus.” And a provider whose model list hasn’t synced yet gets a warning chip (model list not synced) in place of a model chip. Polycode still dispatches that provider, but with no model to name the call fails until the list syncs — the strip says so up front rather than letting it fail silently. Refresh models, mute the provider, or remove it.
Provider accounts live underneath in the Connections list — one row per configured provider, each with a Mute control. Muting keeps the provider connected and remembers which models you had enabled, but stops its models from answering in parallel until you unmute — one click each way. You can even mute the provider that holds the primary: its other models stop fanning out while the primary still writes the answer.
Adding a per-provider key
Open Settings → Providers and click Add provider (top-right), or Connect on a Not connected row in the Connections list. Paste your API key and press Save & Connect. Polycode validates the key against a lightweight provider endpoint (a models list or a token-count probe) before persisting anything — an invalid key surfaces as a red banner so you can fix it without leaving the sheet.
Once validated, the key is written exclusively to the macOS Keychain. There is no plaintext copy on disk, no environment variable, no config file. If you ever want every key gone, Settings → Privacy → Clear all credentials removes them all in one action — see data lifecycle for the full set of removal paths.
For an extra layer at rest, Settings → Privacy → Gate credentials with Touch ID re-stores every key behind a biometric ACL, so reads prompt for Touch ID (you unlock once per session). It’s available on Macs with Touch ID and is off by default.
OpenRouter as the fast path
If you don’t already have accounts at the major frontier providers, the shortest distance from install to a working fan-out is an OpenRouter key. One signup covers Anthropic, OpenAI, Gemini, xAI, Mistral, Meta, DeepSeek, and dozens of smaller models — single invoice, single key, single rotation point.
The trade-offs are real and worth knowing: OpenRouter sits in the network path between you and the upstream model, and most routes carry a small markup over the underlying API price. Per-provider keys are more direct and slightly cheaper at scale. OpenRouter wins for breadth and onboarding speed; per-provider keys win once you’ve decided which models you actually rely on. You can mix them — an OpenRouter key for breadth plus a direct Anthropic key for your primary peer, for instance.
Apple Intelligence and local endpoints
Apple Intelligence is the free fan-out partner. Polycode always lists an Apple Intelligence row in Connections — it starts as Not connected · Apple on-device, runs offline, and Enable connects it with nothing to paste. It needs macOS 26 on an eligible Mac with Apple Intelligence turned on in System Settings; short of that there’s no model to enable and calls report “Apple Intelligence is not available” with the reason. Once it’s connected, enable its model and every fan-out includes it — each call runs on the Neural Engine without a network round-trip.
For local OpenAI-compatible endpoints, point Polycode at the base URL. Ollama
running at http://localhost:11434 is the canonical example; LM Studio’s
server, vLLM, and any internal gateway that speaks the same shape work the
same way. Polycode discovers the model list at the endpoint and lets you pick
which ones to include in fan-out. A local endpoint plus Apple Intelligence is
enough to use Polycode entirely offline.
Cloud gateways for enterprise
If your team has already negotiated spend with Google Cloud, AWS, or Microsoft, Add provider → Cloud gateway… in Settings → Providers configures Vertex AI, Bedrock, or Azure OpenAI Service. Each configured instance then appears as an ordinary row in the Connections list, with Edit… in its context menu. Instances are per-account / per-project / per-resource — you can have many Vertex projects configured at once.
The credentials you provide (a Vertex service-account JSON, an AWS access-key
pair, or an Azure resource api-key) are stored in the Keychain under a
per-instance slot. Polycode mints request-time auth headers from them: Vertex
gets a short-lived OAuth2 token, Bedrock gets a fresh SigV4 signature per
request, Azure gets the api-key as a header. Prompts flow directly to
<region>-aiplatform.googleapis.com, bedrock-runtime.<region>.amazonaws.com,
or <resource>.openai.azure.com — there is no Polycode-operated server in the
path. The mechanics are spelled out in the
data lifecycle cloud gateways section.
Per-model overrides
Click Manage models on a provider’s Connections row to open the Manage
models drawer — a side panel over the tab with the provider’s model list,
a filter field, enable checkboxes, and a custom-model add (Replace API key and
Disconnect live in the drawer’s header menu). From an enabled model’s row,
expand its advanced drawer to pin an alias, set the reasoning effort,
toggle extended thinking, set a temperature or a max-output cap, or supply a
per-model systemPromptOverride that replaces the default project-context
block for that model only. Per-model settings live alongside your other
preferences in the local store.
When a tool wants to talk to a provider
Tools come from your active project and your MCP servers, separate from providers — and which models see a tool follows an audience rule. Native file tools split by what they do: reads go to every model answering in parallel, while Write, Edit, Delete, and Rename are reserved for the primary. MCP tools split by server instead: a server set to Offer tools to every model gives every parallel model all of its tools — including any that write — and a server left primary-only gives them none. Either way the model decides when to invoke, and your per-tool Always / Ask / Deny approval settings apply. See tools and approvals for the full model.
Troubleshooting validation
When validation rejects a key, the sheet shows the error the provider’s own probe returned:
- invalid API key — the provider answered 401 or 403. Polycode reports both the same way, so this covers a wrong or revoked key and a valid key whose account isn’t entitled to the model Polycode probed (common with new OpenAI projects that haven’t been funded). Re-copy the key from the provider’s console first; if it’s definitely current, check the account’s billing and model access.
- rate limited — the provider answered 429, sometimes with a retry delay. Wait and try again; nothing is wrong with the key.
- network unavailable — the request never got a usable answer. Proxy, firewall, or VPN interception is the usual cause. Custom endpoints pointing at internal IPs need the address as Polycode’s process sees it, not as your browser does.
- HTTP status with the vendor’s message — anything else the provider returned, passed through verbatim so you can match it against their docs.
For ongoing visibility into what each provider returned on a real prompt, the inspector shows the full per-call trace.
What’s next
- Fan-out and consensus — how Polycode runs every enabled model in parallel and synthesizes one answer.
- Tools and approvals — MCP servers, the per-tool toggle, and the per-call approval sheet.
- Data lifecycle — where keys, conversations, and project state live on your Mac.
- Getting started — install, onboard, send your first prompt.