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 provider you configure 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. Appears automatically on supported Macs.
• OpenAI-compatible endpoints — anything that speaks the OpenAI chat completions shape: Ollama, LM Studio, xAI, OpenRouter, your own internal gateway. One-click presets ship for Ollama, LM Studio, xAI, and OpenRouter; anything else (vLLM, a custom gateway) is added via the generic OpenAI-compatible endpoint flow. 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.

Adding a per-provider key

Open Settings → Providers and click Add provider (top-right), or Connect on a provider’s row under Available providers. 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. On a Mac that supports it, Polycode adds an Apple Intelligence row automatically — no key, no setup; it runs on-device, offline. Every fan-out includes it unless you opt the model out, and every 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, the Cloud gateways section in Settings → Providers configures Vertex AI, Bedrock, and Azure OpenAI Service. Each instance is 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

Tap a provider row to drill into its per-model list. Open a model’s advanced drawer (Settings → Providers → the provider → a model) 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 are scoped per-conversation, separate from providers. A tool — local filesystem, an MCP server, a shell runner — can ask any active peer to call it; the peer decides when to invoke and Polycode prompts you for approval. See tools and approvals for the full model.

Troubleshooting validation

When Save rejects a key, the error message names the failure cause:

• HTTP 401 — wrong key shape or a revoked key. Re-copy from the provider’s console.
• HTTP 403 — key is valid but the account isn’t entitled to the model Polycode probed. Common with new OpenAI projects that haven’t been funded.
• Network timeout — proxy, firewall, or VPN intercepting the request. Custom endpoints that point at internal IPs need the address as Polycode’s process sees it, not as your browser does.

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 configured provider 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.