add providers and clients

2026-08-31 03:01:30 +02:00 · 2026-08-20 16:17:53 -04:00
parent 62b0d81ebb
commit 7d27ffb36a
24 changed files with 669 additions and 29 deletions
--- a/docs.json
+++ b/docs.json
@@ -189,13 +189,43 @@
                                "icon": "robot",
                                "pages": [
                                    "manage/ai/overview",
-                                    "manage/ai/claude",
-                                    "manage/ai/codex",
-                                    "manage/ai/opencode",
-                                    "manage/ai/gemini",
-                                    "manage/ai/open-webui",
-                                    "manage/ai/claude-desktop",
-                                    "manage/ai/openclaw"
+                                    {
+                                        "group": "Providers",
+                                        "pages": [
+                                            "manage/ai/providers/overview",
+                                            "manage/ai/providers/configuration",
+                                            "manage/ai/providers/openai",
+                                            "manage/ai/providers/anthropic",
+                                            "manage/ai/providers/google-gemini",
+                                            "manage/ai/providers/vertex-ai",
+                                            "manage/ai/providers/bedrock",
+                                            "manage/ai/providers/microsoft-foundry",
+                                            "manage/ai/providers/open-router",
+                                            "manage/ai/providers/vercel-ai-gateway",
+                                            {
+                                                "group": "Custom",
+                                                "pages": [
+                                                    "manage/ai/providers/custom",
+                                                    "manage/ai/providers/custom/ollama",
+                                                    "manage/ai/providers/custom/vllm",
+                                                    "manage/ai/providers/custom/bifrost",
+                                                    "manage/ai/providers/custom/cloud-apis-through-a-site"
+                                                ]
+                                            }
+                                        ]
+                                    },
+                                    {
+                                        "group": "Configure AI Clients and Agents",
+                                        "pages": [
+                                            "manage/ai/configure-ai-clients/claude",
+                                            "manage/ai/configure-ai-clients/codex",
+                                            "manage/ai/configure-ai-clients/opencode",
+                                            "manage/ai/configure-ai-clients/gemini",
+                                            "manage/ai/configure-ai-clients/open-webui",
+                                            "manage/ai/configure-ai-clients/claude-desktop",
+                                            "manage/ai/configure-ai-clients/openclaw"
+                                        ]
+                                    }
                                ]
                            },
                            "manage/endpoints-and-pops",
@@ -494,6 +524,34 @@
        {
            "source": "/manage/sites/configure-site#nat-traversal-tweaks",
            "destination": "/manage/clients/nat-traversal"
+        },
+        {
+            "source": "/manage/ai/claude",
+            "destination": "/manage/ai/configure-ai-clients/claude"
+        },
+        {
+            "source": "/manage/ai/codex",
+            "destination": "/manage/ai/configure-ai-clients/codex"
+        },
+        {
+            "source": "/manage/ai/opencode",
+            "destination": "/manage/ai/configure-ai-clients/opencode"
+        },
+        {
+            "source": "/manage/ai/gemini",
+            "destination": "/manage/ai/configure-ai-clients/gemini"
+        },
+        {
+            "source": "/manage/ai/open-webui",
+            "destination": "/manage/ai/configure-ai-clients/open-webui"
+        },
+        {
+            "source": "/manage/ai/claude-desktop",
+            "destination": "/manage/ai/configure-ai-clients/claude-desktop"
+        },
+        {
+            "source": "/manage/ai/openclaw",
+            "destination": "/manage/ai/configure-ai-clients/openclaw"
        }
    ],
    "seo": {
--- a/manage/ai/configure-ai-clients/claude-desktop.mdx
+++ b/manage/ai/configure-ai-clients/claude-desktop.mdx
--- a/manage/ai/configure-ai-clients/claude.mdx
+++ b/manage/ai/configure-ai-clients/claude.mdx
--- a/manage/ai/configure-ai-clients/codex.mdx
+++ b/manage/ai/configure-ai-clients/codex.mdx
--- a/manage/ai/configure-ai-clients/gemini.mdx
+++ b/manage/ai/configure-ai-clients/gemini.mdx
--- a/manage/ai/configure-ai-clients/open-webui.mdx
+++ b/manage/ai/configure-ai-clients/open-webui.mdx
--- a/manage/ai/configure-ai-clients/openclaw.mdx
+++ b/manage/ai/configure-ai-clients/openclaw.mdx
--- a/manage/ai/configure-ai-clients/opencode.mdx
+++ b/manage/ai/configure-ai-clients/opencode.mdx
--- a/manage/ai/overview.mdx
+++ b/manage/ai/overview.mdx
@@ -7,15 +7,15 @@ An AI Gateway resource is a normal Pangolin resource that proxies requests to on

 ## How it fits together

- **Providers** are configured once per organization - the upstream URL and API key for OpenAI, Anthropic, etc.
+- **[Providers](/manage/ai/providers/overview)** are configured once per organization - the upstream URL, API key, and capabilities for OpenAI, Anthropic, etc.
 - **Resources** (type `AI Gateway`) attach one or more of those providers and get a normal Pangolin domain.
 - **Keys** are what clients authenticate to the resource with. Public resources check them; private resources don't, since only devices on the Pangolin network can reach them at all.

-A resource only understands the API format(s) its attached providers support. An Anthropic provider makes the resource speak the Anthropic Messages API; an OpenAI provider makes it speak Chat Completions/Responses; a Gemini provider makes it speak Gemini's `generateContent` API. Attach whichever providers match the clients you plan to connect.
+A resource only understands the API format(s) its attached providers support. An Anthropic provider makes the resource speak the Anthropic Messages API; an OpenAI provider makes it speak Chat Completions/Responses; a Gemini provider makes it speak Gemini's `generateContent` API. Attach whichever providers match the clients you plan to connect. See [AI Providers](/manage/ai/providers/overview) for per-type setup and [Provider Configuration](/manage/ai/providers/configuration) for capabilities, auth, and model lists.

 ## 1. Add a provider

-Sidebar → **AI Gateway** → **Providers** → **Create**. Pick a provider type, paste in its API key, and save. You can add as many as you need.
+Create an org-level provider so the gateway has an upstream to call. Sidebar → **AI Gateway** → **Providers** → **Create**, or follow the [AI Providers](/manage/ai/providers/overview) guide. Pick a type, paste in its API key, and save. You can add as many as you need.

 {/*
 Screenshot: `/images/ai/create-provider.png`
@@ -70,29 +70,31 @@ Every resource's Keys page has ready-to-copy setup for common clients, and `pang

 | Client | Needs a provider that speaks | Guide |
 |---|---|---|
-| Claude Code | Anthropic Messages | [Setup guide](/manage/ai/claude) |
-| Codex | OpenAI Chat/Responses | [Setup guide](/manage/ai/codex) |
-| OpenCode | Anthropic Messages and/or OpenAI Chat | [Setup guide](/manage/ai/opencode) |
-| Gemini CLI | Gemini `generateContent` | [Setup guide](/manage/ai/gemini) |
+| Claude Code | Anthropic Messages | [Setup guide](/manage/ai/configure-ai-clients/claude) |
+| Codex | OpenAI Chat/Responses | [Setup guide](/manage/ai/configure-ai-clients/codex) |
+| OpenCode | Anthropic Messages and/or OpenAI Chat | [Setup guide](/manage/ai/configure-ai-clients/opencode) |
+| Gemini CLI | Gemini `generateContent` | [Setup guide](/manage/ai/configure-ai-clients/gemini) |

 There are also guides for pointing other tools at a Pangolin AI Gateway resource:

- [Open WebUI](/manage/ai/open-webui)
- [Claude Desktop](/manage/ai/claude-desktop)
- [OpenClaw](/manage/ai/openclaw)
+- [Open WebUI](/manage/ai/configure-ai-clients/open-webui)
+- [Claude Desktop](/manage/ai/configure-ai-clients/claude-desktop)
+- [OpenClaw](/manage/ai/configure-ai-clients/openclaw)

 ## Supported providers

-| Provider | Speaks |
-|---|---|
-| OpenAI | Chat Completions, Responses |
-| Anthropic | Messages |
-| Google Gemini | `generateContent` |
-| Vertex AI | Google `generateContent`/`rawPredict` |
-| Bedrock | Converse |
-| Microsoft Foundry | Chat Completions, Responses, Messages |
-| OpenRouter | Chat Completions |
-| Vercel AI Gateway | Chat Completions, Responses |
-| Custom | Whatever you configure |
+Each type has its own configuration guide. Capabilities (which API formats a provider speaks) are explained in [Provider Configuration](/manage/ai/providers/configuration#capabilities).

-Use **Custom** for any OpenAI- or Anthropic-compatible endpoint that isn't in the list above - for example a Moonshot AI (Kimi) endpoint, which is Anthropic-compatible.
+| Provider | Default capabilities | Guide |
+|---|---|---|
+| OpenAI | Chat Completions, Responses | [Configure](/manage/ai/providers/openai) |
+| Anthropic | Messages | [Configure](/manage/ai/providers/anthropic) |
+| Google Gemini | `generateContent` | [Configure](/manage/ai/providers/google-gemini) |
+| Vertex AI | Google `generateContent`/`rawPredict` | [Configure](/manage/ai/providers/vertex-ai) |
+| Amazon Bedrock | Converse | [Configure](/manage/ai/providers/bedrock) |
+| Microsoft Foundry | Chat Completions, Responses, Messages | [Configure](/manage/ai/providers/microsoft-foundry) |
+| OpenRouter | Chat Completions | [Configure](/manage/ai/providers/open-router) |
+| Vercel AI Gateway | Chat Completions, Responses | [Configure](/manage/ai/providers/vercel-ai-gateway) |
+| Custom | Whatever you select | [Configure](/manage/ai/providers/custom) |
+
+Use [Custom](/manage/ai/providers/custom) for any upstream that isn't in the typed list. Assign whichever capabilities it speaks - OpenAI, Anthropic, Gemini, Vertex, Bedrock, or a mix. A Moonshot AI (Kimi) endpoint is one example: select Anthropic Messages and point at its Anthropic-compatible URL.
--- a/manage/ai/providers/anthropic.mdx
+++ b/manage/ai/providers/anthropic.mdx
@@ -0,0 +1,41 @@
+---
+title: "Anthropic"
+description: "Connect Anthropic as an AI Gateway provider"
+---
+
+An Anthropic provider forwards Messages requests to Anthropic's API. Attach it to an AI Gateway resource when you want Claude Code, Claude Desktop, OpenCode, OpenClaw, or any other Anthropic-compatible client to use your org's Anthropic key.
+
+See [AI Providers](/manage/ai/providers/overview) if you haven't created a provider before. Field options are in [Provider Configuration](/manage/ai/providers/configuration).
+
+## Defaults
+
+| Setting | Value |
+|---|---|
+| Upstream URL | `https://api.anthropic.com` |
+| Auth type | `x-api-key` |
+| Capabilities | Anthropic Messages, Anthropic Models |
+
+Anthropic Models (`GET /v1/models`) is answered from this provider's allow and block lists. See [Capabilities](/manage/ai/providers/configuration#capabilities).
+
+## Configure
+
+1. Sidebar → **AI Gateway** → **Providers** → **Create**.
+2. Set **Provider Type** to **Anthropic**. Name, capabilities, upstream URL, and auth type fill in from the defaults above.
+3. Paste your Anthropic API key.
+4. Set **Allow** and **Block** lists. `*` allows every model key; `claude-*` is a typical narrower pattern.
+5. Save, then attach the provider to an [AI Gateway resource](/manage/ai/overview).
+
+Leave the upstream URL as the default unless you are pointing at a compatible Anthropic-style base URL.
+
+<Tip>
+Clients can send `anthropic-version` themselves. You can also set it as a [custom header](/manage/ai/providers/configuration#headers-and-tls) on the provider (`anthropic-version: 2023-06-01`). A header set on the provider is always sent upstream and overrides the same header from the client.
+</Tip>
+
+## Clients
+
+| Client | Guide |
+|---|---|
+| Claude Code | [Setup guide](/manage/ai/configure-ai-clients/claude) |
+| Claude Desktop | [Setup guide](/manage/ai/configure-ai-clients/claude-desktop) |
+| OpenCode | [Setup guide](/manage/ai/configure-ai-clients/opencode) |
+| OpenClaw | [Setup guide](/manage/ai/configure-ai-clients/openclaw) |
--- a/manage/ai/providers/bedrock.mdx
+++ b/manage/ai/providers/bedrock.mdx
@@ -0,0 +1,33 @@
+---
+title: "Amazon Bedrock"
+description: "Connect Amazon Bedrock as an AI Gateway provider"
+---
+
+An Amazon Bedrock provider forwards Converse requests to Bedrock Runtime in the region you configure. Use it when clients call Bedrock's Converse API.
+
+See [AI Providers](/manage/ai/providers/overview) if you haven't created a provider before. Field options are in [Provider Configuration](/manage/ai/providers/configuration).
+
+## Defaults
+
+| Setting | Value |
+|---|---|
+| Upstream URL | You enter the regional Bedrock Runtime base URL |
+| Auth type | Bearer |
+| Capabilities | Bedrock Converse |
+
+Bedrock Model Invoke (`InvokeModel` / `invoke-with-response-stream`) is available as an extra capability if the client uses that API instead of Converse.
+
+## Configure
+
+1. Sidebar → **AI Gateway** → **Providers** → **Create**.
+2. Set **Provider Type** to **Amazon Bedrock**. Capabilities and auth type fill in from the defaults above.
+3. Set **Upstream URL** to your regional Bedrock Runtime host, for example `https://bedrock-runtime.us-east-1.amazonaws.com`.
+4. Paste a Bearer credential the upstream accepts. Pangolin sends `Authorization: Bearer <key>` on every request.
+5. Set **Allow** and **Block** lists. Use Bedrock model ids (for example `anthropic.claude-sonnet-4-20250514-v1:0` or an inference profile id).
+6. Save, then attach the provider to an [AI Gateway resource](/manage/ai/overview).
+
+Add **Bedrock Model Invoke** on the **General** tab if the client calls `/model/{id}/invoke` rather than Converse. Add other capabilities only if this endpoint actually speaks those API formats.
+
+## Clients
+
+Clients that call Bedrock Converse work with the default capability. Claude Code talks Anthropic Messages (`POST /v1/messages`), so it needs a provider that advertises Anthropic Messages, such as [Anthropic](/manage/ai/providers/anthropic), [Microsoft Foundry](/manage/ai/providers/microsoft-foundry), or a [custom](/manage/ai/providers/custom) Anthropic-compatible endpoint.
--- a/manage/ai/providers/configuration.mdx
+++ b/manage/ai/providers/configuration.mdx
@@ -0,0 +1,72 @@
+---
+title: "Provider Configuration"
+description: "Capabilities, auth, routing, and model lists for AI Gateway providers"
+---
+
+This page is the field reference for every AI provider type. Type-specific defaults (URL, auth header, capabilities) live on each provider page. See [AI Providers](/manage/ai/providers/overview) for what a provider is and how it attaches to a resource.
+
+Sidebar → **AI Gateway** → **Providers** → **Create**. After you save, the provider has tabs for **General**, **Network**, **Models**, **Authentication**, and **Budget**.
+
+## Capabilities
+
+A capability is an API format the gateway will accept and proxy. The incoming request path selects a capability, and only attached providers that advertise that capability can handle the request. That is why Claude Code needs a provider with Anthropic Messages, and Codex needs a provider with OpenAI Chat Completions or Responses.
+
+| Capability | What the gateway accepts |
+|---|---|
+| OpenAI Chat Completions | `POST /v1/chat/completions` |
+| OpenAI Responses | `POST /v1/responses` |
+| Anthropic Messages | `POST /v1/messages` |
+| Anthropic Models | `GET /v1/models` (answered from the gateway's allow and block lists, not proxied upstream) |
+| Gemini Generate Content | Gemini `generateContent` / `streamGenerateContent` |
+| Vertex Generate Content | Vertex AI Gemini format |
+| Vertex Raw Predict | Vertex AI `rawPredict` for Anthropic models |
+| Bedrock Converse | Amazon Bedrock Converse API |
+| Bedrock Model Invoke | Amazon Bedrock InvokeModel |
+
+Typed providers start with recommended capabilities. Custom providers need at least one selected. You can change capabilities later on the provider's **General** tab. Select every format the upstream actually speaks. Custom providers can mix any combination.
+
+If two attached providers share a capability for the same model, the gateway picks one using allow lists and catalog ownership. Two providers of the same type both allowing `*` can leave the request ambiguous.
+
+## Auth Type
+
+How the gateway authenticates to the upstream. Typed providers prefill the header that upstream expects.
+
+| Auth type | What Pangolin sends |
+|---|---|
+| Bearer | `Authorization: Bearer <key>`. Used by OpenAI and most compatible APIs. |
+| `x-api-key` | `x-api-key` header. Used by Anthropic and Anthropic-compatible APIs. |
+| `x-goog-api-key` | `x-goog-api-key` header. Used by Google Gemini. |
+| Cloudflare AI Gateway | `cf-aig-authorization: Bearer <key>`. |
+| Splunk HEC | `Authorization: Splunk <key>`. |
+| Passthrough | Forward the caller's remaining API key headers to the upstream (after Pangolin strips its own virtual key). |
+| No Auth | Send the request without authentication headers. |
+
+Bearer, `x-api-key`, `x-goog-api-key`, Cloudflare AI Gateway, and Splunk HEC all require an API key on the provider.
+
+## Routing
+
+Where the gateway sends the request after it has selected this provider.
+
+| Mode | When to use |
+|---|---|
+| **Upstream URL** | Call a public or private API base URL. Typed providers with a public API prefill this. Vertex AI, Amazon Bedrock, and Microsoft Foundry ask you to enter a regional or resource base URL. |
+| **Site Targets** | Route through HTTP targets on your Pangolin sites, the same way a public resource reaches an internal service. Available on [Custom](/manage/ai/providers/custom) providers only. |
+
+If you choose **Site Targets**, configure the targets on the provider's **Network** tab after you save.
+
+See [Ollama](/manage/ai/providers/custom/ollama), [vLLM](/manage/ai/providers/custom/vllm), [Bifrost](/manage/ai/providers/custom/bifrost), and [Cloud APIs Through a Site](/manage/ai/providers/custom/cloud-apis-through-a-site) for Site Targets walkthroughs.
+
+## Models
+
+Allow and block lists restrict which model keys this provider may serve. A request must match an allow entry and must not match a block entry. An empty allow list denies all traffic. Patterns support `*` and `?` (`gpt-*`, `claude-3-5-sonnet-?`).
+
+When you attach a provider to a resource you can **inherit** these lists or **select** a subset for that resource only.
+
+OpenRouter, Vercel AI Gateway, and Custom are treated as aggregators: a wildcard allow such as `*` matches at request time but does not expand in `GET /v1/models`. Add exact model keys to make those models show up in discovery.
+
+## Headers and TLS
+
+On **Network** you can also set:
+
+- **Custom headers** sent on every request to this provider (`Header-Name: value`, one per line)
+- **Skip TLS verification** for the upstream connection
--- a/manage/ai/providers/custom.mdx
+++ b/manage/ai/providers/custom.mdx
@@ -0,0 +1,48 @@
+---
+title: "Custom"
+description: "Connect any upstream endpoint and assign whichever API capabilities it speaks"
+---
+
+A custom provider is for an upstream that is not in the typed list: a self-hosted model server, a vendor API, a proxy, or an internal service reached through a Pangolin site. You assign any mix of [capabilities](/manage/ai/providers/configuration#capabilities). The gateway will accept those API formats on resources that attach this provider.
+
+Custom providers start blank. You choose capabilities, [routing](/manage/ai/providers/configuration#routing), and [auth](/manage/ai/providers/configuration#auth-type). At least one capability is required. Site Targets routing is available on Custom only.
+
+See [AI Providers](/manage/ai/providers/overview) if you haven't created a provider before, and [Provider Configuration](/manage/ai/providers/configuration) for the field reference.
+
+## Configure
+
+1. Sidebar → **AI Gateway** → **Providers** → **Create**.
+2. Set **Provider Type** to **Custom** and give it a name.
+3. Select every **API capability** the upstream speaks. You can add any combination.
+4. Choose **Routing Mode**. For **Upstream URL**, paste the base URL. For **Site Targets**, add targets after save.
+5. Pick **Auth Type** and paste a key if that type needs one.
+6. Set **Allow** and **Block** lists. Add exact model keys if you want them listed in `GET /v1/models`. See [Models](/manage/ai/providers/configuration#models).
+7. Save, then attach the provider to an [AI Gateway resource](/manage/ai/overview).
+
+## Reach a Self-Hosted API
+
+Site Targets send the request over a Pangolin tunnel to a host Newt can reach. [Install a site](/manage/sites/install-site) on the same network as the model server so the gateway can route to that API over the tunnel. See [Understanding Sites](/manage/sites/understanding-sites).
+
+After the site is connected, add the process as a target on the provider's **Network** tab (host, port, HTTP or HTTPS). Worked examples: [Ollama](/manage/ai/providers/custom/ollama), [vLLM](/manage/ai/providers/custom/vllm), and [Bifrost](/manage/ai/providers/custom/bifrost).
+
+## Examples
+
+Worked Custom setups:
+
+- [Ollama](/manage/ai/providers/custom/ollama): local models on a site, OpenAI Chat Completions
+- [vLLM](/manage/ai/providers/custom/vllm): a vLLM OpenAI server on a site
+- [Bifrost](/manage/ai/providers/custom/bifrost): downstream model routing with Pangolin identity headers
+- [Cloud APIs Through a Site](/manage/ai/providers/custom/cloud-apis-through-a-site): send OpenAI or Anthropic out through a site so the vendor sees that site's IP
+
+The same Custom pattern works for llama.cpp server, LM Studio, LocalAI, and other OpenAI-compatible listeners: pick Chat Completions, point Site Targets at the process, and allow the model ids it serves.
+
+## Example: Kimi K2
+
+This is one custom setup: Moonshot AI's Kimi K2 endpoint speaks the Anthropic API, so you select Anthropic capabilities. A different upstream would get a different capability set.
+
+1. Create a **Custom** provider.
+2. Select **Anthropic Messages** and **Anthropic Models**.
+3. Set routing to **Upstream URL** and use Moonshot's Anthropic-compatible base URL.
+4. Set auth to **`x-api-key`** and paste the Moonshot key.
+5. Allow the Kimi model ids you plan to call.
+6. Attach the provider to a resource, then point [Claude Code](/manage/ai/configure-ai-clients/claude) or [Claude Desktop](/manage/ai/configure-ai-clients/claude-desktop) at that resource.
--- a/manage/ai/providers/custom/bifrost.mdx
+++ b/manage/ai/providers/custom/bifrost.mdx
@@ -0,0 +1,25 @@
+---
+title: "Bifrost"
+description: "Point a Custom provider at Bifrost for downstream model routing and identity-aware access control"
+---
+
+[Bifrost](https://www.getmaxim.ai/bifrost) is an OpenAI-compatible LLM gateway that routes to many upstream model providers. Use it as a Custom AI Gateway provider when Pangolin should authenticate clients and Bifrost should pick models, fail over, or apply its own access controls.
+
+Pangolin talks to Bifrost at `/v1/chat/completions` (default port `8080`). Add [Anthropic Messages](/manage/ai/providers/configuration#capabilities) as well if clients will call Bifrost's Anthropic-compatible paths.
+
+See [Capabilities](/manage/ai/providers/configuration#capabilities) for the full capability list.
+
+[Install a site](/manage/sites/install-site) on the same network as Bifrost so Pangolin can reach it over the tunnel. See [Reach a Self-Hosted API](/manage/ai/providers/custom#reach-a-self-hosted-api).
+
+## Configure
+
+1. Sidebar → **AI Gateway** → **Providers** → **Create**.
+2. Set **Provider Type** to **Custom** and give it a name.
+3. Select **OpenAI Chat Completions** (and any other formats Bifrost should accept).
+4. Set **Routing Mode** to **Site Targets** if Bifrost runs on a site's network. Use **Upstream URL** (`http://<host>:8080`) only when the Pangolin node can reach Bifrost directly.
+5. Set **Auth Type** to **No Auth** on a private LAN. Use **Bearer** if Bifrost requires a virtual key or other API key.
+6. Allow the model ids Bifrost should serve, including provider-prefixed keys such as `openai/gpt-4o-mini` if that is how Bifrost names them. See [Models](/manage/ai/providers/configuration#models).
+7. Save. On the **Network** tab, add a target: the Bifrost host, port `8080`, method HTTP.
+8. Attach the provider to an [AI Gateway resource](/manage/ai/overview).
+
+Then point a client at that resource: [Codex](/manage/ai/configure-ai-clients/codex), [OpenCode](/manage/ai/configure-ai-clients/opencode), or [Open WebUI](/manage/ai/configure-ai-clients/open-webui). Clients still call the Pangolin resource. Bifrost only sees the request after Pangolin has authenticated it.
--- a/manage/ai/providers/custom/cloud-apis-through-a-site.mdx
+++ b/manage/ai/providers/custom/cloud-apis-through-a-site.mdx
@@ -0,0 +1,34 @@
+---
+title: "Cloud APIs Through a Site"
+description: "Send OpenAI or Anthropic traffic out through a Pangolin site so the vendor sees a fixed egress IP"
+---
+
+Typed [OpenAI](/manage/ai/providers/openai) and [Anthropic](/manage/ai/providers/anthropic) providers send requests from the Pangolin node's own egress. A [Custom](/manage/ai/providers/custom) provider with **Site Targets** sends the same APIs out through a chosen site (Newt), so OpenAI or Anthropic see that site's public IP.
+
+Use this when the vendor allowlists IPs, or all inference must leave from one network. The site is only the egress path. Auth still lives on the provider: paste the real vendor key.
+
+Those typed provider types use **Upstream URL** only. This walkthrough uses Custom plus targets.
+
+See [Capabilities](/manage/ai/providers/configuration#capabilities) for the full capability list.
+
+## Configure
+
+1. Pick a [site](/manage/sites/understanding-sites) that can reach the public internet. That box's public IP is what the vendor will see.
+2. Sidebar → **AI Gateway** → **Providers** → **Create**. Set **Provider Type** to **Custom**.
+3. Select capabilities that match the cloud API:
+   - OpenAI: **OpenAI Chat Completions** and **OpenAI Responses**
+   - Anthropic: **Anthropic Messages** and **Anthropic Models**
+4. Set **Routing Mode** to **Site Targets**.
+5. Set **Auth Type** to **Bearer** for OpenAI, or **`x-api-key`** for Anthropic, and paste the vendor API key.
+6. Allow the model ids you plan to call, then save.
+7. On the **Network** tab, add a target on that site. Use the API hostname as the address so TLS Host and SNI match:
+
+   | Vendor | Address | Port | Method |
+   |---|---|---|---|
+   | OpenAI | `api.openai.com` | `443` | HTTPS |
+   | Anthropic | `api.anthropic.com` | `443` | HTTPS |
+
+   The target address is sent as the Host header.
+8. Attach the provider to an [AI Gateway resource](/manage/ai/overview).
+
+The site must resolve and reach that hostname. Clients still point at the resource URL, not at OpenAI or Anthropic directly: [Codex](/manage/ai/configure-ai-clients/codex), [Claude Code](/manage/ai/configure-ai-clients/claude), and the other [client guides](/manage/ai/overview#4-connect-a-client).
--- a/manage/ai/providers/custom/ollama.mdx
+++ b/manage/ai/providers/custom/ollama.mdx
@@ -0,0 +1,25 @@
+---
+title: "Ollama"
+description: "Point a Custom provider at Ollama on a Pangolin site"
+---
+
+[Ollama](https://ollama.com) serves local models with an OpenAI-compatible HTTP API. Create a [Custom](/manage/ai/providers/custom) provider and route to that API so Codex, OpenCode, Open WebUI, and other Chat Completions clients can use models running on a site.
+
+Pangolin talks to Ollama at `/v1/chat/completions`. Use that OpenAI-compatible listener, not Ollama's native `/api/chat` path.
+
+See [Capabilities](/manage/ai/providers/configuration#capabilities) for the full capability list.
+
+[Install a site](/manage/sites/install-site) on the same network as Ollama so Pangolin can reach it over the tunnel. See [Reach a Self-Hosted API](/manage/ai/providers/custom#reach-a-self-hosted-api).
+
+## Configure
+
+1. Sidebar → **AI Gateway** → **Providers** → **Create**.
+2. Set **Provider Type** to **Custom** and give it a name.
+3. Select **OpenAI Chat Completions**.
+4. Set **Routing Mode** to **Site Targets** if Ollama runs on a site's network. Use **Upstream URL** (`http://<host>:11434`) only when the Pangolin node can reach Ollama directly.
+5. Set **Auth Type** to **No Auth** on a private LAN. Use **Bearer** if you set an Ollama API key.
+6. Allow the exact model ids you plan to call, for example `llama3.2`. See [Models](/manage/ai/providers/configuration#models).
+7. Save. On the **Network** tab, add a target: the Ollama host, port `11434`, method HTTP.
+8. Attach the provider to an [AI Gateway resource](/manage/ai/overview).
+
+Then point a client at that resource: [Codex](/manage/ai/configure-ai-clients/codex), [OpenCode](/manage/ai/configure-ai-clients/opencode), or [Open WebUI](/manage/ai/configure-ai-clients/open-webui).
--- a/manage/ai/providers/custom/vllm.mdx
+++ b/manage/ai/providers/custom/vllm.mdx
@@ -0,0 +1,25 @@
+---
+title: "vLLM"
+description: "Point a Custom provider at a vLLM OpenAI server on a Pangolin site"
+---
+
+[vLLM](https://docs.vllm.ai) can expose an OpenAI-compatible HTTP server for local or GPU-hosted models. Create a [Custom](/manage/ai/providers/custom) provider and route to that server so Codex, OpenCode, Open WebUI, and other Chat Completions clients can use it.
+
+Pangolin talks to vLLM at `/v1/chat/completions` on the OpenAI server (default port `8000`).
+
+See [Capabilities](/manage/ai/providers/configuration#capabilities) for the full capability list.
+
+[Install a site](/manage/sites/install-site) on the same network as vLLM so Pangolin can reach it over the tunnel. See [Reach a Self-Hosted API](/manage/ai/providers/custom#reach-a-self-hosted-api).
+
+## Configure
+
+1. Sidebar → **AI Gateway** → **Providers** → **Create**.
+2. Set **Provider Type** to **Custom** and give it a name.
+3. Select **OpenAI Chat Completions**.
+4. Set **Routing Mode** to **Site Targets** if vLLM runs on a site's network. Use **Upstream URL** (`http://<host>:8000`) only when the Pangolin node can reach vLLM directly.
+5. Set **Auth Type** to **No Auth** if the server has no key. Use **Bearer** and paste the key if you started vLLM with `--api-key`.
+6. Allow the exact served model id (the `--model` name or `--served-model-name`). See [Models](/manage/ai/providers/configuration#models).
+7. Save. On the **Network** tab, add a target: the vLLM host, port `8000`, method HTTP.
+8. Attach the provider to an [AI Gateway resource](/manage/ai/overview).
+
+Then point a client at that resource: [Codex](/manage/ai/configure-ai-clients/codex), [OpenCode](/manage/ai/configure-ai-clients/opencode), or [Open WebUI](/manage/ai/configure-ai-clients/open-webui).
--- a/manage/ai/providers/google-gemini.mdx
+++ b/manage/ai/providers/google-gemini.mdx
@@ -0,0 +1,34 @@
+---
+title: "Google Gemini"
+description: "Connect Google Gemini as an AI Gateway provider"
+---
+
+A Google Gemini provider forwards `generateContent` requests to Google's Gemini API. Attach it to an AI Gateway resource when you want Gemini CLI (or another client that speaks the Gemini API) to use your org's Gemini key.
+
+See [AI Providers](/manage/ai/providers/overview) if you haven't created a provider before. Field options are in [Provider Configuration](/manage/ai/providers/configuration).
+
+This type is the Gemini Developer API (`generativelanguage.googleapis.com`). For Vertex AI's `generateContent` / `rawPredict` paths, use [Vertex AI](/manage/ai/providers/vertex-ai) instead.
+
+## Defaults
+
+| Setting | Value |
+|---|---|
+| Upstream URL | `https://generativelanguage.googleapis.com` |
+| Auth type | `x-goog-api-key` |
+| Capabilities | Gemini Generate Content |
+
+## Configure
+
+1. Sidebar → **AI Gateway** → **Providers** → **Create**.
+2. Set **Provider Type** to **Google Gemini**. Name, capabilities, upstream URL, and auth type fill in from the defaults above.
+3. Paste your Gemini API key.
+4. Set **Allow** and **Block** lists. `*` allows every model key; `gemini-*` is a typical narrower pattern.
+5. Save, then attach the provider to an [AI Gateway resource](/manage/ai/overview).
+
+Leave the upstream URL as the default unless you are pointing at a compatible Gemini API base URL.
+
+## Clients
+
+| Client | Guide |
+|---|---|
+| Gemini CLI | [Setup guide](/manage/ai/configure-ai-clients/gemini) |
--- a/manage/ai/providers/microsoft-foundry.mdx
+++ b/manage/ai/providers/microsoft-foundry.mdx
@@ -0,0 +1,38 @@
+---
+title: "Microsoft Foundry"
+description: "Connect Microsoft Foundry as an AI Gateway provider"
+---
+
+A Microsoft Foundry provider forwards OpenAI-format and Anthropic-format requests to your Azure AI Foundry (or Azure OpenAI) resource. One Foundry provider can serve both Codex-style clients and Claude Code, because the defaults include Chat Completions, Responses, and Anthropic Messages.
+
+See [AI Providers](/manage/ai/providers/overview) if you haven't created a provider before. Field options are in [Provider Configuration](/manage/ai/providers/configuration).
+
+## Defaults
+
+| Setting | Value |
+|---|---|
+| Upstream URL | You enter your Foundry or Azure OpenAI resource base URL |
+| Auth type | Bearer |
+| Capabilities | OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, Anthropic Models |
+
+## Configure
+
+1. Sidebar → **AI Gateway** → **Providers** → **Create**.
+2. Set **Provider Type** to **Microsoft Foundry**. Capabilities and auth type fill in from the defaults above.
+3. Set **Upstream URL** to the resource base, for example `https://<resource-name>.services.ai.azure.com` or `https://<resource-name>.openai.azure.com`.
+4. Paste a Bearer credential the resource accepts (typically the Azure API key).
+5. Set **Allow** and **Block** lists. Use the deployment or model names the Foundry resource exposes.
+6. Save, then attach the provider to an [AI Gateway resource](/manage/ai/overview).
+
+Leave capabilities at the defaults if you want both OpenAI-compatible and Anthropic-compatible clients on the same resource. Trim them if this Foundry resource only hosts one API family.
+
+## Clients
+
+| Client | Guide |
+|---|---|
+| Codex | [Setup guide](/manage/ai/configure-ai-clients/codex) |
+| Claude Code | [Setup guide](/manage/ai/configure-ai-clients/claude) |
+| OpenCode | [Setup guide](/manage/ai/configure-ai-clients/opencode) |
+| Open WebUI | [Setup guide](/manage/ai/configure-ai-clients/open-webui) |
+| Claude Desktop | [Setup guide](/manage/ai/configure-ai-clients/claude-desktop) |
+| OpenClaw | [Setup guide](/manage/ai/configure-ai-clients/openclaw) |
--- a/manage/ai/providers/open-router.mdx
+++ b/manage/ai/providers/open-router.mdx
@@ -0,0 +1,39 @@
+---
+title: "OpenRouter"
+description: "Connect OpenRouter as an AI Gateway provider"
+---
+
+An OpenRouter provider forwards Chat Completions requests to OpenRouter. Use it as an aggregator when you want one key to reach many upstream models through OpenAI Chat Completions.
+
+See [AI Providers](/manage/ai/providers/overview) if you haven't created a provider before. Field options are in [Provider Configuration](/manage/ai/providers/configuration).
+
+## Defaults
+
+| Setting | Value |
+|---|---|
+| Upstream URL | `https://openrouter.ai/api/v1` |
+| Auth type | Bearer |
+| Capabilities | OpenAI Chat Completions |
+
+OpenRouter's default capability is Chat Completions only. Clients that require Responses or Anthropic Messages need a different provider, extra capabilities this OpenRouter account actually supports, or a [custom](/manage/ai/providers/custom) endpoint.
+
+## Configure
+
+1. Sidebar → **AI Gateway** → **Providers** → **Create**.
+2. Set **Provider Type** to **OpenRouter**. Name, capabilities, upstream URL, and auth type fill in from the defaults above.
+3. Paste your OpenRouter API key.
+4. Set **Allow** and **Block** lists. OpenRouter model keys are often vendor-prefixed, for example `openai/gpt-4o` or `anthropic/claude-sonnet-4`.
+5. Save, then attach the provider to an [AI Gateway resource](/manage/ai/overview).
+
+## Models
+
+OpenRouter is an aggregator. See [Models](/manage/ai/providers/configuration#models) for how allow lists and `GET /v1/models` discovery work. Add exact keys such as `openai/gpt-4o` or `anthropic/claude-sonnet-4`.
+
+## Clients
+
+| Client | Guide |
+|---|---|
+| Codex | [Setup guide](/manage/ai/configure-ai-clients/codex) |
+| OpenCode | [Setup guide](/manage/ai/configure-ai-clients/opencode) |
+| Open WebUI | [Setup guide](/manage/ai/configure-ai-clients/open-webui) |
+| OpenClaw | [Setup guide](/manage/ai/configure-ai-clients/openclaw) |
--- a/manage/ai/providers/openai.mdx
+++ b/manage/ai/providers/openai.mdx
@@ -0,0 +1,35 @@
+---
+title: "OpenAI"
+description: "Connect OpenAI as an AI Gateway provider"
+---
+
+An OpenAI provider forwards Chat Completions and Responses requests to OpenAI's API. Attach it to an AI Gateway resource when you want Codex, OpenCode, Open WebUI, OpenClaw, or any other OpenAI-compatible client to use your org's OpenAI key.
+
+See [AI Providers](/manage/ai/providers/overview) if you haven't created a provider before. Field options are in [Provider Configuration](/manage/ai/providers/configuration).
+
+## Defaults
+
+| Setting | Value |
+|---|---|
+| Upstream URL | `https://api.openai.com/v1` |
+| Auth type | Bearer |
+| Capabilities | OpenAI Chat Completions, OpenAI Responses |
+
+## Configure
+
+1. Sidebar → **AI Gateway** → **Providers** → **Create**.
+2. Set **Provider Type** to **OpenAI**. Name, capabilities, upstream URL, and auth type fill in from the defaults above.
+3. Paste your OpenAI API key.
+4. Set **Allow** and **Block** lists. `*` allows every model key; `gpt-*` is a typical narrower pattern.
+5. Save, then attach the provider to an [AI Gateway resource](/manage/ai/overview).
+
+Leave the upstream URL as the default unless you are pointing at a compatible OpenAI-style base URL.
+
+## Clients
+
+| Client | Guide |
+|---|---|
+| Codex | [Setup guide](/manage/ai/configure-ai-clients/codex) |
+| OpenCode | [Setup guide](/manage/ai/configure-ai-clients/opencode) |
+| Open WebUI | [Setup guide](/manage/ai/configure-ai-clients/open-webui) |
+| OpenClaw | [Setup guide](/manage/ai/configure-ai-clients/openclaw) |
--- a/manage/ai/providers/overview.mdx
+++ b/manage/ai/providers/overview.mdx
@@ -0,0 +1,59 @@
+---
+title: "AI Providers"
+description: "Connect upstream model APIs once per organization, then attach them to AI Gateway resources"
+---
+
+A provider is an organization-level connection to an upstream model API. It stores the provider type, credentials, base URL, API capabilities, and optional model allow and block lists. Create providers once, then attach them to any AI Gateway resource in the org. Clients call the resource's domain, not the provider directly.
+
+See [AI Gateway Overview](/manage/ai/overview) for creating a resource and issuing keys. See [Provider Configuration](/manage/ai/providers/configuration) for capabilities, auth, routing, and model lists.
+
+## What a Provider Is
+
+Sidebar → **AI Gateway** → **Providers** → **Create**.
+
+Each provider is:
+
+- A **type** (OpenAI, Anthropic, Google Gemini, and others) that fills in recommended defaults
+- **Credentials** and a **base URL** the gateway uses when it forwards a request
+- **Capabilities** that declare which API formats the provider can handle
+- Optional **allow** and **block** lists that restrict which model keys may be used
+
+Providers are reused across resources. The resource still owns the public URL and the keys clients authenticate with.
+
+{/*
+Screenshot: `/images/ai/create-provider.png`
+The AI Gateway → Providers → Create form, showing the provider type dropdown and API key field filled in for OpenAI or Anthropic.
+<Frame>
+  <img src="/images/ai/create-provider.png" alt="Creating an AI provider" />
+</Frame>
+*/}
+
+## Attach to a Resource
+
+On an AI Gateway resource, attach one or more providers from the **AI Gateway** settings tab. For each attachment you can inherit the provider's model lists or select a subset. Details are in [Provider Configuration](/manage/ai/providers/configuration#models).
+
+The resource only speaks the API formats its attached providers advertise. Attach whichever providers match the [clients](/manage/ai/overview#4-connect-a-client) you plan to connect.
+
+{/*
+Screenshot: `/images/ai/create-resource.png`
+The new resource dialog with Type set to "AI Gateway" and a provider selected in the AI Providers section.
+<Frame>
+  <img src="/images/ai/create-resource.png" alt="Attaching providers to an AI Gateway resource" />
+</Frame>
+*/}
+
+## Provider Types
+
+| Provider | Default capabilities | Guide |
+|---|---|---|
+| OpenAI | Chat Completions, Responses | [Configure OpenAI](/manage/ai/providers/openai) |
+| Anthropic | Messages, Models | [Configure Anthropic](/manage/ai/providers/anthropic) |
+| Google Gemini | Gemini Generate Content | [Configure Google Gemini](/manage/ai/providers/google-gemini) |
+| Vertex AI | Vertex Generate Content, Raw Predict | [Configure Vertex AI](/manage/ai/providers/vertex-ai) |
+| Amazon Bedrock | Bedrock Converse | [Configure Amazon Bedrock](/manage/ai/providers/bedrock) |
+| Microsoft Foundry | Chat Completions, Responses, Messages, Models | [Configure Microsoft Foundry](/manage/ai/providers/microsoft-foundry) |
+| OpenRouter | Chat Completions | [Configure OpenRouter](/manage/ai/providers/open-router) |
+| Vercel AI Gateway | Chat Completions, Responses | [Configure Vercel AI Gateway](/manage/ai/providers/vercel-ai-gateway) |
+| Custom | Whatever you select | [Configure Custom](/manage/ai/providers/custom) |
+
+Custom also covers local engines, downstream routers, and cloud APIs sent through a site. See [Ollama](/manage/ai/providers/custom/ollama), [vLLM](/manage/ai/providers/custom/vllm), [Bifrost](/manage/ai/providers/custom/bifrost), and [Cloud APIs Through a Site](/manage/ai/providers/custom/cloud-apis-through-a-site).
--- a/manage/ai/providers/vercel-ai-gateway.mdx
+++ b/manage/ai/providers/vercel-ai-gateway.mdx
@@ -0,0 +1,37 @@
+---
+title: "Vercel AI Gateway"
+description: "Connect Vercel AI Gateway as an AI Gateway provider"
+---
+
+A Vercel AI Gateway provider forwards Chat Completions and Responses requests to Vercel's AI Gateway. Use it as an aggregator when you want one key to reach models Vercel exposes through OpenAI-compatible APIs.
+
+See [AI Providers](/manage/ai/providers/overview) if you haven't created a provider before. Field options are in [Provider Configuration](/manage/ai/providers/configuration).
+
+## Defaults
+
+| Setting | Value |
+|---|---|
+| Upstream URL | `https://ai-gateway.vercel.sh/v1` |
+| Auth type | Bearer |
+| Capabilities | OpenAI Chat Completions, OpenAI Responses |
+
+## Configure
+
+1. Sidebar → **AI Gateway** → **Providers** → **Create**.
+2. Set **Provider Type** to **Vercel AI Gateway**. Name, capabilities, upstream URL, and auth type fill in from the defaults above.
+3. Paste your Vercel AI Gateway API key.
+4. Set **Allow** and **Block** lists. Use the model ids Vercel documents for the gateway.
+5. Save, then attach the provider to an [AI Gateway resource](/manage/ai/overview).
+
+## Models
+
+Vercel AI Gateway is an aggregator. See [Models](/manage/ai/providers/configuration#models) for how allow lists and `GET /v1/models` discovery work. Add exact model keys to the allow list.
+
+## Clients
+
+| Client | Guide |
+|---|---|
+| Codex | [Setup guide](/manage/ai/configure-ai-clients/codex) |
+| OpenCode | [Setup guide](/manage/ai/configure-ai-clients/opencode) |
+| Open WebUI | [Setup guide](/manage/ai/configure-ai-clients/open-webui) |
+| OpenClaw | [Setup guide](/manage/ai/configure-ai-clients/openclaw) |
--- a/manage/ai/providers/vertex-ai.mdx
+++ b/manage/ai/providers/vertex-ai.mdx
@@ -0,0 +1,35 @@
+---
+title: "Vertex AI"
+description: "Connect Google Vertex AI as an AI Gateway provider"
+---
+
+A Vertex AI provider forwards Vertex `generateContent` and `rawPredict` requests to your Google Cloud project. Use it when clients call Vertex AI publisher-model paths rather than the Gemini Developer API.
+
+See [AI Providers](/manage/ai/providers/overview) if you haven't created a provider before. Field options are in [Provider Configuration](/manage/ai/providers/configuration).
+
+For Google's Gemini Developer API, use [Google Gemini](/manage/ai/providers/google-gemini) instead.
+
+## Defaults
+
+| Setting | Value |
+|---|---|
+| Upstream URL | You enter the regional Vertex AI base URL |
+| Auth type | Bearer |
+| Capabilities | Vertex Generate Content, Vertex Raw Predict |
+
+Vertex Generate Content covers Gemini-format calls on Vertex. Vertex Raw Predict covers Anthropic models hosted on Vertex (`rawPredict` / `streamRawPredict`).
+
+## Configure
+
+1. Sidebar → **AI Gateway** → **Providers** → **Create**.
+2. Set **Provider Type** to **Vertex AI**. Capabilities and auth type fill in from the defaults above.
+3. Set **Upstream URL** to your regional Vertex host, for example `https://us-central1-aiplatform.googleapis.com`. The host includes the location.
+4. Paste a Bearer credential the Vertex endpoint accepts (typically a Google OAuth access token).
+5. Set **Allow** and **Block** lists. Use the model ids Vertex expects, including publisher-qualified keys when that is how the client sends them.
+6. Save, then attach the provider to an [AI Gateway resource](/manage/ai/overview).
+
+The gateway authenticates with `Authorization: Bearer <key>`. Add extra capabilities on the **General** tab only if this Vertex endpoint actually speaks those API formats.
+
+## Clients
+
+Clients that call Vertex `generateContent` or `rawPredict` paths work with the default capabilities. Gemini CLI talks the Gemini Developer API (`gemini_generate_content`), so it needs a [Google Gemini](/manage/ai/providers/google-gemini) provider rather than this one.