## Summary
Adds an operator-facing migration guide for the AI Bridge to AI Gateway
rebrand, as a new docs page under **AI Coder > AI Gateway** (last child
in the section).
The guide documents:
- **Config aliases** (env vars, CLI flags, YAML group keys): old
`aibridge` names still work as hidden, deprecated aliases; new
`ai_gateway` names are canonical. Includes full env-var mapping tables
and the mechanical substitution rules.
- **HTTP API**: canonical path is now `/api/v2/ai-gateway`; legacy
`/api/v2/aibridge` routes retained.
- **Metrics**: prefixes renamed `coder_aibridged_*` ->
`coder_ai_gateway_*` and `coder_aibridgeproxyd_*` ->
`coder_ai_gateway_proxy_*`. Both old and new names are emitted today, so
dashboards keep working; guidance to migrate before the old names are
removed, plus an optional `metric_relabel_configs` drop snippet.
- **No database changes** and no required config changes to upgrade.
Implements the docs/release-notes portion of
[AIGOV-240](https://linear.app/codercom/issue/AIGOV-240) (parent:
[AIGOV-207](https://linear.app/codercom/issue/AIGOV-207)).
## Notes
- Content reflects what actually shipped in the codebase (metrics are
*aliased*, not hard-renamed), which differs from the original RFC that
assumed a hard rename.
- Registered in `docs/manifest.json` with `state: ["ai governance
add-on"]` to match sibling pages.
---
*This PR was produced by opencode (agent) using the
`anthropic/claude-opus-4-8` model, under human direction and review.*
---------
Signed-off-by: Danny Kopping <danny@coder.com>
## Description
Updates documentation to use the new `/api/v2/ai-gateway/` URLs and
`/ai-gateway/` UI paths, following the backend rename in #26475 and
frontend route rename in #26569.
## Changes
- Update URL references across documentation files from
`/api/v2/aibridge/` to `/api/v2/ai-gateway/`
- Update UI path reference from `/aibridge/sessions` to
`/ai-gateway/sessions`
- Update route path references in client setup guides
- Covers client setup guides, authentication, monitoring, proxy setup,
and provider configuration
Addresses
https://github.com/coder/coder/pull/26475#issuecomment-4768351217
Refs https://linear.app/codercom/issue/AIGOV-226
> Generated with the assistance of Coder Agents (@ssncferreira)
Document the optional Role ARN field on Bedrock providers, which has the
gateway assume an IAM role via STS before calling Bedrock. Covers the
permissions the assumed role requires and the trust policy.
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Move the providers routes into a dedicated providers sub-tree: `/ai/settings/providers`, `/ai/settings/providers/add`, and `/ai/settings/providers/:providerId`.
The old `/ai/settings/:providerId` and `/ai/settings/add` URLs are
removed without backward-compatibility redirects. Bookmarked or shared
links to these paths now return a 404. Creating a provider with id `models` (although unlikely) made it impossible to edit it due to a conflict with the static models route.
## Description
Registers `/api/v2/ai-gateway/*` as the new API path for AI Gateway, replacing `/api/v2/aibridge/*`. Both prefixes share the same route builder (`aiBridgeRoutes`) backed by a single in-memory handler, so existing `/aibridge` endpoints continue to work. New endpoints must be registered on the enterprise API handler under `/api/v2/ai-gateway` only.
Swagger annotations now point to `/api/v2/ai-gateway` paths with a backward-compatibility note referencing `/aibridge`. The legacy `/aibridge` routes are skipped in the swagger documentation test.
## Changes
- Store one raw handler (`aiGatewayHandler`) instead of two prefix-stripped handlers
- Register `/ai-gateway` and `/ai-gateway/proxy` route aliases alongside legacy `/aibridge` routes
- Move `/aibridge/keys` to `/ai-gateway/keys`
- Update in-process transport to use `/api/v2/ai-gateway` prefix
- Update SDK client URLs and proxy forwarding URL
- Swap `@Router` and `@Tags` annotations from `aibridge`/`AI Bridge` to `ai-gateway`/`AI Gateway`
- Rename user-facing error messages from "AI Bridge" to "AI Gateway"
- Define consts for route prefixes (`AIGatewayRootPath`, `AIBridgeRootPath`)
- Update tests and comments to use new paths
Note: the following will be addressed in follow-up PRs:
- Frontend API URLs
- Frontend routes and redirects
- Dogfood main.tf updates
- Hand-written documentation URL updates
- aibridge internal comments and nits
- Scale tests path updates
Refs https://linear.app/coder/issue/AIGOV-230
> Generated with the assistance of Coder Agents (@ssncferreira)
## Summary
Restores the step-by-step "Obtaining static Bedrock credentials"
walkthrough that was present on the v2.32.6 `ai-bridge/setup` page but
missing from the current `ai-gateway/providers` page.
The current page mentions static credentials in a single line but no
longer explains how to create the IAM user and access key in the AWS
console. This PR brings back that walkthrough, adapted to the current
database/dashboard-managed provider flow.
## Changes
- Add an `#### Obtaining static Bedrock credentials` subsection under
the Amazon Bedrock provider section in
`docs/ai-coder/ai-gateway/providers.md`.
- Keep the AWS console steps (choose region, generate API keys, create
access key) from v2.32.6.
- Replace the deprecated `CODER_AIBRIDGE_BEDROCK_*` environment-variable
configuration step with guidance to enter the credentials when
adding/editing the provider via the dashboard or AI Providers API,
matching the post-v2.34 database-managed model.
<details>
<summary>Context and decisions</summary>
- Source: [`docs/ai-coder/ai-bridge/setup.md` at
v2.32.6](https://coder.com/docs/@v2.32.6/ai-coder/ai-bridge/setup)
"Obtaining Bedrock credentials" section.
- The old flow set provider config via environment variables, which are
deprecated since v2.34 (providers are now stored in the database and
managed via dashboard/API). The restored content keeps the AWS-side
credential-creation steps but routes the final configuration step
through the current provider management flow rather than env vars.
- Open questions from
[AIGOV-432](https://linear.app/codercom/issue/AIGOV-432/restore-bedrock-static-credentials-docs-from-v2326)
(whether other pages also need this, and whether the content needs
further accuracy updates) are left for review.
</details>
Closes
[AIGOV-432](https://linear.app/codercom/issue/AIGOV-432/restore-bedrock-static-credentials-docs-from-v2326).
> [!NOTE]
> This PR was generated by Coder Agents on behalf of @dannykopping.
---------
Co-authored-by: Nick Vigilante <nickvigilante@users.noreply.github.com>
Closes [DOCS-351](https://linear.app/codercom/issue/DOCS-351).
> [!WARNING]
> **DO NOT MERGE** until
[DOCS-349](https://linear.app/codercom/issue/DOCS-349)
([coder.com#877](https://github.com/coder/coder.com/pull/877)) has
shipped to production and baked for at least one Vercel cycle.
>
> Without DOCS-349, the relative links in this PR resolve to broken
docs-route URLs (`/docs/helm/coder/values.yaml` -> 404) instead of
GitHub URLs tagged with the displayed docs version. DOCS-349 fixes the
rewriter to classify these as GitHub blob/tree URLs with the page's
resolved ref.
## TL;DR
Converts 121 absolute
`https://github.com/coder/coder/(blob|tree)/main/<path>` links across 39
docs markdown files to relative paths. After this lands AND DOCS-349
deploys, every one of these links will follow the displayed docs version
(mainline tag on bare URLs, explicit tag on `/@vX.Y.Z/`, `main` on
`/@main/`) instead of always pointing to `main`.
## Why
Today a reader on `/docs/@v2.30.0/install/docker` follows a
`compose.yaml` link and arrives at `main`'s `compose.yaml`, which
doesn't necessarily match what the docs page describes. Helm values,
Terraform templates, and source-code references in particular drift
across versions. The fix is to let the coder.com rewriter substitute the
page's resolved ref into the URL; that only works on relative links.
## Example payoff (post-DOCS-349)
| URL | Today (absolute, always `main`) | After (relative + rewriter) |
|---|---|---|
| `/docs/install/docker` |
`https://github.com/coder/coder/blob/main/compose.yaml` |
`https://github.com/coder/coder/blob/v2.34.1/compose.yaml` (today's
mainline) |
| `/docs/@v2.30.0/install/docker` | same as above |
`https://github.com/coder/coder/blob/v2.30.0/compose.yaml` |
| `/docs/@main/install/docker` | same as above |
`https://github.com/coder/coder/blob/main/compose.yaml` |
## Scope
- **121 conversions** across **39 files**.
- Verb breakdown: `tree/main` (directories) and `blob/main` (files),
both flipped to relative paths.
- Line anchors (`#L23-L24`) and query strings preserved verbatim.
- Conversion is mechanical: relative path computed from the doc file's
directory to the target via `os.path.relpath`. Any path starting at the
same directory or below gets a `./` prefix; otherwise `../` chains.
## Rebased on main
The branch was rebased onto `main` after the DOCS-350 hotfix
([#26339](https://github.com/coder/coder/pull/26339)) merged. The hotfix
repointed 3 `docs-backend-contrib-guide` refs in `backend.md` to `main`,
which then needed the same `main` -> relative conversion this PR is
doing for the other 121 links. The conflict was resolved by reapplying
the mechanical conversion to `backend.md` after taking the hotfix's
content. Net result: those 3 links land here as relative, same as
everything else. New HEAD `3f501cb622`.
## Inline fix folded in: dead `nix` link
- `docs/about/contributing/CONTRIBUTING.md:7` -> `../../../nix`
The original absolute URL `https://github.com/coder/coder/tree/main/nix`
already returned 404 today. Repointed to `flake.nix` (modern Nix
entrypoint, what the prose "Nix environment" semantically refers to).
Closes [DOCS-357](https://linear.app/codercom/issue/DOCS-357) here since
the `check-docs` Linkspector job surfaced it during rebase; cheaper to
fix inline than in a separate single-line PR.
## Out of scope (filed separately)
- [DOCS-350](https://linear.app/codercom/issue/DOCS-350): 3 dead
`docs-backend-contrib-guide` branch refs in `backend.md`
([#26339](https://github.com/coder/coder/pull/26339), merged).
- [DOCS-352](https://linear.app/codercom/issue/DOCS-352): 10 SHA-pinned
`(blob|tree)/<sha>` links pending intent review.
- [DOCS-355](https://linear.app/codercom/issue/DOCS-355): code-server
analog (4 absolute `(blob|tree)/main` links in `coder/code-server`).
- [DOCS-356](https://linear.app/codercom/issue/DOCS-356): 2 upstream
content bugs in `coder/code-server/docs/CONTRIBUTING.md` (independent of
this PR).
## Not triggering `/coder-agents-review`
Docs-only edit; per `AGENTS.md` the bot review is reserved for
product/CI changes.
## Pre-mortem
| Concern | Mitigation |
|---|---|
| Merging before DOCS-349 deploys regresses ~120 currently-working links
into 404s on coder.com | Clear DO-NOT-MERGE banner; tracked as blocker
in Linear. |
| Relative path computed incorrectly (off-by-one `..`) | Verified all
114 newly-relative non-md/non-image paths resolve to existing files in
the repo (only exception is the pre-existing dead `nix` link above). |
| Line anchors stripped during conversion | Preserved by the
substitution regex; verified `#L<n>-L<m>` cases in `airgap.md` and
`speed-up-templates.md`. |
| Future code reorgs change file locations | Relative links will start
pointing to nothing. Same failure mode as absolute links pointing to
renamed files; can be caught with a future link-checker job. |
## Validation
```
$ grep -rE 'github\.com/coder/coder/(blob|tree)/main' docs --include="*.md" | wc -l
0
$ git diff --stat origin/main | tail -1
39 files changed, 118 insertions(+), 118 deletions(-)
```
114 newly-relative paths verified to resolve to existing repo files
(Python `os.path.exists` check on each computed target).
<details>
<summary>Decision log + planning context</summary>
**Why relative over `(blob|tree)/{{currentDocsVersion}}/...`
templating**: relative paths require zero markdown-system support and
zero upstream churn beyond this one PR. Templating would require a
preprocessor on `coder.com` side AND a convention upstream authors have
to remember; relative paths just work in a plain editor and
`github.com`'s own renderer too.
**Why `./` prefix on same-directory targets**: makes the conversion
grep-able later (`grep -E '\((\.\./|\./)'`).
**Why preserve `#L<n>-L<m>` anchors verbatim**: the anchor is meaningful
to the linked file's content, not to the URL form; keeping it as-is
preserves authorial intent. If the file later changes such that the line
range drifts, that's a different problem the SHA-pin audit
([DOCS-352](https://linear.app/codercom/issue/DOCS-352)) will surface.
</details>
---
*Generated by Coder Agents on @nickvigilante's behalf.*
## Drive-by external link fix folded in
`docs/about/contributing/CONTRIBUTING.md:296` cited
`https://reflectoring.io/meaningful-commit-messages/` which is returning
HTTP 503 (the host appears to be down site-wide right now). `check-docs`
Linkspector flagged it after the rebase. Replaced with
`https://cbea.ms/git-commit/` (Chris Beams' canonical "If applied, this
commit will..." article, confirmed 200), which is the original source of
the rule the prose recites anyway.
## Summary
Adds a Troubleshooting section to the Codex CLI AI Gateway client docs
covering the WebSocket-to-HTTPS transport fallback.
Recent Codex CLI versions default to the WebSocket runtime for the
Responses API. AI Gateway does not support WebSocket transport, so each
request attempts a WebSocket connection, fails, and falls back to HTTPS,
surfacing:
```text
Falling back from WebSockets to HTTPS transport.
```
The doc explains the cause and the fix: set `supports_websockets =
false` in the `[model_providers.ai_gateway]` block in
`~/.codex/config.toml` to force HTTPS directly and remove the fallback
delay.
Closes
[AIGOV-453](https://linear.app/codercom/issue/AIGOV-453/document-codex-cli-websocket-fallback-workaround).
<details>
<summary>Note on the config value</summary>
The original request and the Linear issue referenced enabling websocket
support / `support_websockets = false`. The authoritative Codex CLI
[config reference](https://developers.openai.com/codex/config-reference)
confirms:
- The key is `supports_websockets` (trailing "s").
- It declares whether a provider supports the Responses API WebSocket
transport.
- Setting it to `false` is the documented workaround to force HTTPS and
stop the fallback attempts.
Since AI Gateway does not support WebSockets, `supports_websockets =
false` is the correct value. `= true` would assert support that does not
exist and keep the fallback happening.
</details>
---
This PR was generated by Coder Agents on behalf of @dannykopping.
Adds
diagram showing how AI Bridge Proxy works in tunnel and MITM modes.
diagram showing how AI Bridge Proxy integrates with upstream proxies.
Extends Troubleshooting section.
Adds a registry link for the AI Bridge Proxy module for Coder
workspaces.
> AI Tools where used in this request.
Registers `coder_aibridged_*` and `coder_aibridgeproxyd_*` metrics under
new prefixes: `coder_ai_gateway_*` and `coder_ai_gateway_proxy_*`.
Old prefix is still exported. Will be removed in later release.
Also updated the `metricsdocgen` static fixture. Added 4
previously-undocumented metrics `key_pool_state`,
`key_pool_state_transitions_total`, `key_pool_exhaustions_total`,
`key_pool_failover_attempts` added the `client` label to the existing
interception, prompt, and token counter samples.
Updated AI Gateway documentation.
Following the BYOK (ChatGPT Subscription) instructions in `codex.md` on
a deployment without a ChatGPT provider fails with `404 route not
supported: POST /chatgpt/v1/responses`. The
`/api/v2/aibridge/chatgpt/v1` route only exists when an admin has
created a provider named `chatgpt`, and that requirement wasn't
documented anywhere.
## Changes
- `providers.md`: new **ChatGPT** subsection alongside the other
per-provider sections: type `openai`, name must be exactly `chatgpt`,
base URL `https://chatgpt.com/backend-api/codex`, no API keys (auth
comes from each user's ChatGPT OAuth token via BYOK)
- `codex.md`:
- prerequisite admonition in the ChatGPT Subscription section linking to
the provider setup, with the 404 symptom for troubleshooting
- template recipe for the ChatGPT subscription flow (`base_config_toml`
+ `coder_env` injecting `CODER_API_TOKEN`), since the existing recipe
only covers the centralized API key flow
- bump the codex module pin from `~> 4.1` to `~> 5.0` (latest is 5.1)
## Verification
- All three gaps were hit and the documented configuration verified
end-to-end on a live deployment: provider created via the AI Providers
API, Codex CLI 0.139.0 authenticated with ChatGPT login, sessions
visible in the AI Sessions UI
- `pnpm run format-docs` and `pnpm run lint-docs` clean (0 errors),
`pre-commit-light` hooks passed
Linear: [DOCS-354](https://linear.app/codercom/issue/DOCS-354)
🤖 Generated with Coder Agents on behalf of @bpmct
## Summary
Removes the deprecated `/api/v2/aibridge/interceptions` endpoint and the
Request Logs frontend page, both replaced by the session-based view.
Closes https://linear.app/codercom/issue/AIGOV-266
Closes https://linear.app/codercom/issue/AIGOV-324
## Changes
### Backend
- Remove `GET /api/v2/aibridge/interceptions` HTTP handler and route
- Remove SDK types and client method (`AIBridgeInterception`,
`AIBridgeTokenUsage`, `AIBridgeUserPrompt`, `AIBridgeToolUsage`,
`AIBridgeListInterceptionsResponse`, `AIBridgeListInterceptionsFilter`)
- Remove SQL queries `CountAIBridgeInterceptions` and
`ListAIBridgeInterceptions`
- Remove `searchquery.AIBridgeInterceptions` parser
- Remove dbauthz wrappers, in-memory implementations, metrics, and mocks
for the interceptions list queries
- Remove the `coder aibridge interceptions list` CLI command and golden
files
- Regenerate API docs, swagger, mocks, and metrics
The `/models`, `/clients`, and `/sessions` endpoints stay; the sessions
list page still consumes all three.
### Frontend
- Delete the entire `RequestLogsPage/` directory (page, view, row,
filter, stories, tests)
- Remove the `/aibridge/request-logs` route and its lazy import
- Remove the `getAIBridgeInterceptions` API method,
`paginatedInterceptions` query, and mock interception entities
- `git mv` the shared filter and icon components used by the sessions
pages:
- `RequestLogsPage/RequestLogsFilter/{Client,Model,Provider}Filter.tsx`
→ `AIBridgePage/filters/`
- `RequestLogsPage/icons/AIBridge{Client,Model,Provider}Icon.tsx` →
`AIBridgePage/icons/`
- Drop the `getProviderIconName` hack and the duplicate `anthropic-neue`
icon case now that the FIXME no longer applies
## Commits
1. `refactor: remove interceptions API and request logs view` — the bulk
removal, with explicit renames for the shared filter/icon files.
2. `refactor(site/src/pages/AIBridgePage): drop getProviderIconName
hack` — cleanup of the FIXME that depended on RequestLogsPage existing.
> [!NOTE]
> Generated by Coder Agents on behalf of @dannykopping
Updates hand-written documentation to use "AI Gateway" instead of "AI
Bridge" as a follow-up to the UI rename in
https://github.com/coder/coder/pull/26161#issuecomment-4660014072.
Changed files:
- `docs/ai-coder/ai-gateway/clients/codex.md` — display name and config
key (`aibridge` to `ai_gateway`) in TOML config examples
- `docs/ai-coder/ai-gateway/clients/factory.md` — display names in JSON
config examples and prose
- `docs/ai-coder/ai-gateway/monitoring.md` — structured logging
description
- `docs/ai-coder/ai-gateway/ai-gateway-proxy/setup.md` — CA cert example
filenames (`coder-aibridge-proxy-ca.pem` to
`coder-ai-gateway-proxy-ca.pem`)
- `docs/ai-coder/ai-gateway/clients/copilot.md` — CA cert example
filenames
- `docs/ai-coder/ai-gateway/clients/index.md` — CA cert example filename
Generated reference docs (`docs/reference/cli/`, `docs/reference/api/`)
and `docs/manifest.json` are generated from Go code and will update
automatically via `make gen` in the context of AIGOV-230 (API swagger
tags) and AIGOV-231 (CLI help).
Refs https://linear.app/codercom/issue/AIGOV-233
> Generated by Coder Agents on behalf of @ssncferreira
## Problem
aibridgeproxyd's HTTP transport (`proxy.Tr`) was configured with secure
TLS defaults only when an upstream proxy was set. Without one, it fell
back to [goproxy's default
transport](https://github.com/elazarl/goproxy/blob/v1.8.0/proxy.go#L152),
which has `InsecureSkipVerify: true`, leaving the connection between the
proxy and aibridge vulnerable to MITM on HTTPS deployments.
This PR moves the secure transport assignment outside the upstream proxy
branch so it applies unconditionally.
## Changes
* Apply secure TLS defaults to `proxy.Tr` unconditionally (verified
`RootCAs`, `MinVersion: TLS 1.2`).
* Add `TestProxy_AIBridgeTLSVerification` to cover the verification path
between the proxy and aibridge.
## Notes
* **Behavior change for `HTTPS_PROXY` env var**: previously, when
`UpstreamProxy` was unset, `proxy.Tr` honored `HTTP_PROXY` and
`HTTPS_PROXY` env vars. After this PR it does not, since MITM'd requests
now always go directly to aibridge. This matches the behavior when
`UpstreamProxy` is configured, which already ignored env vars.
* **HTTPS deployments with a private CA**: when `CoderAccessURL` is
HTTPS and its TLS certificate (or the load balancer's certificate
fronting it) is signed by a CA not in the system trust store, the proxy
will now fail with `x509: certificate signed by unknown authority`.
Closes
https://linear.app/codercom/issue/AIGOV-386/ai-bridge-proxy-uses-goproxy-default-with-tls-verification-disabled
> [!NOTE]
> Initially generated by Claude Opus 4.7, modified and reviewed by
@ssncferreira
Updates the VS Code AI Gateway client docs to reflect the Custom
Endpoint provider introduced in VS Code 1.121 (Insiders) and promoted to
Stable in 1.122.
## Changes
**`docs/ai-coder/ai-gateway/clients/vscode.md`**
- Replace the deprecated `customoai` vendor with `customendpoint`
- Add the required `apiType` field (`responses` for OpenAI, `messages`
for Anthropic)
- Add Anthropic provider setup (Messages API type, base URL
`…/aibridge/anthropic`)
- Note GitHub sign-in is no longer required — works in
air-gapped/restricted environments
- Add limitation callout: inline suggestions and NES still require
GitHub Copilot
- Reflect the UI-first API key entry flow (VS Code stores the token
securely; do not paste into JSON directly)
- Drop the Centralized/BYOK split — VS Code has no template injection
path, so both scenarios follow the same user-driven UI flow
**`docs/ai-coder/ai-gateway/clients/index.md`**
- VS Code compatibility row: Anthropic `❌ → ✅`
- Updated Notes column
<details>
<summary>Research notes</summary>
- VS Code 1.121 shipped the Custom Endpoint provider (Insiders),
replacing the legacy OpenAI Compatible (`customoai`) provider which is
now deprecated.
- VS Code 1.122 promoted Custom Endpoint to Stable and removed the
GitHub sign-in requirement for BYOK.
- Anthropic support confirmed working: `apiType: "messages"` + base URL
`…/api/v2/aibridge/anthropic` (Coder's gateway accepts the Coder session
token as `x-api-key`).
- OpenAI uses `apiType: "responses"` + base URL
`…/api/v2/aibridge/openai`.
- API keys must be entered via the Manage Language Models UI — VS Code
stores them securely and references them as
`${input:chat.lm.secret.XXXXX}` in the JSON.
</details>
> This PR was drafted by Coder Agents on behalf of @matifali.
Adds OpenCode to AI Bridge client detection so requests with user agents
like `opencode/1.16.0 ai-sdk/provider-utils/4.0.23 runtime/bun/1.3.14`
show up as a first-class client instead of `Unknown`.
This also wires the existing OpenCode frontend asset into the AIBridge
UI, adds a Storybook story for the client icon, and updates the
monitoring docs list of supported client values.
<details>
<summary>Coder Agents generated</summary>
This pull request was generated by Coder Agents.
</details>
> Mux updated this PR on behalf of Mike.
Clarifies that Coder Agents route through AI Gateway automatically,
while admins configure Agents providers with upstream provider or proxy
endpoint/base URLs.
Moves Agents-specific setup and credential guidance into the Agents
models page, removes the obsolete AI Gateway Coder Agents client page,
removes Coder Agents from the AI Gateway external client list, and links
BYOK credential selection to the global AI Gateway BYOK setting.
Document the automatic key failover feature for AI Gateway, which allows
configuring multiple centralized API keys per provider instance (OpenAI
and Anthropic only).
## Changes
- **`docs/ai-coder/ai-gateway/providers.md`**: Add "Key failover"
section covering supported providers, configuration via the API (max 5
keys), and failover behavior (auth errors permanently disable a key
until restart/reload, exhausted pool returns `429` or `502`).
- **`docs/ai-coder/ai-gateway/auth.md`**: Add note in BYOK section
clarifying that key failover is skipped when a user-supplied credential
is present.
> [!NOTE]
> Generated by Coder Agents (by @ssncferreira)
Adds a new **Provider Configuration** reference page (`providers.md`) covering:
- The migration from environment-variable-based provider config to database-backed management introduced in v2.34, including the one-time seeding behavior and deprecation of `CODER_AI_GATEWAY_PROVIDER_<N>_*` and related flags
- All supported provider types (`openai`, `anthropic`, `bedrock`, `copilot`, `azure`, `google`, `openrouter`, `vercel`, `openai-compat`) with setup notes for each
- Provider lifecycle statuses (`enabled`, `disabled`, `error`) and their effect on request handling
- Reload behavior and how configuration changes apply without restarting `coderd`
- Bring Your Own Key (BYOK) and failure mode reference table
Updates **Setup** (`setup.md`) to replace the environment-variable-based provider configuration instructions with dashboard-driven steps (Add provider form, provider list, edit/disable flow), referencing the new `providers.md` page for deeper detail. Screenshots of the provider list, add, and edit forms are included.
Adds a **Provider metrics** section to **Monitoring** (`monitoring.md`) documenting the `coder_aibridged_*` and `coder_aibridgeproxyd_*` Prometheus metrics for provider status and reload timestamps, along with two suggested PromQL alert queries.
Replace the env-based `BuildProviders` with a DB-backed loader. The database is now the single source of truth for runtime provider configuration; env config arrives via `SeedAIProvidersFromEnv` (run at boot) and `BuildProviders` reads it back as `aibridge.Provider` instances. `cli/server.go` and `enterprise/cli/server.go` both call the same path, so aibridged and aibridgeproxyd see the same provider set.
Per-provider `DumpDir` is replaced by a top-level `CODER_AI_GATEWAY_DUMP_DIR` base; each provider's effective dump path is `<base>/<provider name>`.
Adds options matching new AI Gateway naming.
New options are added as alias for old options. Old options are still
working.
Old options have deprecated message.
No conflict detection was added.
Updated documentation so it mentions only new options. Added note about
old options still working.
> Various AI tools where used to create this PR
The Authentication and BYOK docs are now part of their own section above
the Clients subsection. The original PR, coder/coder#25459, was based on
a ticket I generated to calculate the drift, but the contents of the
Linear ticket were geared more toward documenting _everything_ in the
code, which had too much scope and was confusing.
Fixes DOCS-148
<!--
If you have used AI to produce some or all of this PR, please ensure you
have read our [AI Contribution
guidelines](https://coder.com/docs/about/contributing/AI_CONTRIBUTING)
before submitting.
-->
The Claude Code and Codex CLI registry modules expose the variable as
`enable_ai_gateway`, not `enable_aibridge`. Templates using the docs as
written fail Terraform init with `An argument named "enable_aibridge" is
not expected here.`
Verified in
[`registry/coder/modules/claude-code/main.tf`](https://github.com/coder/registry/blob/main/registry/coder/modules/claude-code/main.tf)
and
[`registry/coder-labs/modules/codex/main.tf`](https://github.com/coder/registry/blob/main/registry/coder-labs/modules/codex/main.tf),
where the variable is declared as `enable_ai_gateway` and gates the
`ANTHROPIC_BASE_URL` / `ANTHROPIC_AUTH_TOKEN` injection.
_Generated with the help of Coder Agents._
## Summary
Replace the "Premium" label with "AI Governance Add-On" and add a
disclaimer that the AI Governance Add-On is required for AI Gateway and
Agent Firewall as of Coder v2.32, across all AI Governance doc pages and
their children.
## Changes
**Label and requirement updates (7 files):**
- `docs/ai-coder/ai-governance.md`: Removed "(Premium)" from title;
updated GA section to state add-on required as of v2.32.
- `docs/ai-coder/ai-gateway/setup.md`: "Premium license" → "AI
Governance Add-On license".
- `docs/ai-coder/ai-gateway/ai-gateway-proxy/setup.md`: "Premium
license" → "AI Governance Add-On".
- `docs/ai-coder/ai-gateway/clients/claude-code.md`: "(Premium feature)"
→ "(AI Governance Add-On)".
- `docs/manifest.json`: `"state": ["premium"]` → `"state": ["ai
governance add-on"]` for 4 nav entries.
**Disclaimer added to all child pages (26 files):**
AI Gateway pages (18):
`index.md`, `setup.md`, `audit.md`, `monitoring.md`, `mcp.md`,
`reference.md`, `ai-gateway-proxy/index.md`,
`ai-gateway-proxy/setup.md`, `clients/index.md`,
`clients/claude-code.md`, `clients/codex.md`, `clients/mux.md`,
`clients/opencode.md`, `clients/factory.md`, `clients/cline.md`,
`clients/kilo-code.md`, `clients/roo-code.md`, `clients/vscode.md`,
`clients/jetbrains.md`, `clients/zed.md`, `clients/copilot.md`
Agent Firewall pages (8):
`index.md`, `version.md`, `landjail.md`, `rules-engine.md`,
`nsjail/index.md`, `nsjail/docker.md`, `nsjail/k8s.md`, `nsjail/ecs.md`
Other: `security.md`
> [!NOTE]
> The `"ai governance add-on"` state value in `manifest.json` is new.
The docs site renderer may need to be updated to support this state
value.
> Generated by Coder Agents
> AI tools where used when creating this PR
This PR removes environment variable parsing from `/aibridge` directory.
Added env variables/flags for dump dir as coder options.
Only added to new indexed provider options
(`CODER_AIBRIDGE_PROVIDER_<N>_*`) not to deprecated legacy env variables
(`CODER_AIBRIDGE_ANTHROPIC_*` and `CODER_AIBRIDGE_OPENAI_KEY_*`).
Reverted adding `MaxRetries` option as it will be removed soon due to
key failover work:
https://github.com/coder/coder/pull/24783#discussion_r3155544808
> AI tools where used when creating this PR
This PR:
* removes references to aibridge repository from coder docs
* updates aibdrige/README.md
* makes it clear aibridge (keeping old name) is a handler not a separate
process
* updates outdated sections about: metrics, recorded interface and
supported paths.
---------
Co-authored-by: Susana Ferreira <susana@coder.com>
The deprecation notice on the [MCP Tools
Injection](https://coder.com/docs/ai-coder/ai-gateway/mcp) page
currently states the feature "will be removed in a future release,"
which may cause concern for users relying on it today.
This updates the warning to clarify that the feature will remain
functional and will not be removed until its replacement, MCP Gateway,
is released.
> [!NOTE]
> Generated by Coder Agents
---------
Co-authored-by: david-fraley <67079030+david-fraley@users.noreply.github.com>
> This PR was authored by Mux on behalf of Mike.
Adds AWS Bedrock ambient credential support to the Agents provider path.
Bedrock providers can now be saved without a stored API key and
authenticated via the standard AWS SDK credential chain on the Coder
server (IAM roles, `AWS_ACCESS_KEY_ID`, etc.). Also fixes missing `Base
URL` forwarding for Bedrock.
## Changes
**Backend runtime** (`coderd/x/chatd/chatprovider/chatprovider.go`):
- New `ProviderAllowsAmbientCredentials(provider)` helper. Currently
returns true only for Bedrock.
- `ModelFromConfig` no longer errors on an empty API key when the
provider is in the ambient-allowed set AND was explicitly resolved via
`ByProvider`. This preserves the policy gate: unresolvable providers
(disabled central key, user-key-required without a user key) still
error.
- `setResolvedProviderAPIKey` internalizes the ambient-credentials
contract via `ProviderAllowsAmbientCredentials`, so a
resolved-but-keyless Bedrock provider is represented as an empty
`ByProvider` entry rather than a post-hoc sentinel patch in the caller.
- `WithAPIKey` is only appended when a token is present.
- `WithBaseURL(baseURL)` is now forwarded for Bedrock (was previously
missing).
**Backend admin API** (`coderd/exp_chats.go`):
- `validateChatProviderCentralAPIKey` exempts Bedrock from requiring a
stored API key when central credentials are enabled.
- AI Gateway separation (`ChatProviderAPIKeysFromDeploymentValues`) is
unchanged. No silent reuse of `CODER_AIBRIDGE_BEDROCK_*` flags.
**Frontend**
(`site/src/pages/AgentsPage/components/ChatModelAdminPanel/*`):
- API Key field is optional for Bedrock when central credentials are
enabled.
- Bedrock-specific descriptions on API Key and Base URL fields
(bearer-token vs ambient modes, `AWS_REGION` guidance).
- Right-aligned "Clear stored token" action switches an existing Bedrock
provider back to ambient mode.
- `hasEffectiveAPIKey` treats Bedrock with central credentials enabled
as configured, so the provider list shows the correct status icon.
- Three new stories: `ProviderFormBedrockAmbientCredentials`,
`ProviderFormBedrockBearerToken`, `ProviderFormBedrockClearBearerToken`.
**Docs** (`docs/ai-coder/agents/models.md`,
`docs/ai-coder/ai-gateway/setup.md`):
- New "Configuring AWS Bedrock" section covering both credential modes,
region resolution, and the Base URL override.
- Explicit note that the `us-east-1` region fallback only applies to
bearer-token mode; ambient credentials require a region from the
standard AWS SDK chain.
- Cross-reference in AI Gateway docs clarifying that
`CODER_AIBRIDGE_BEDROCK_*` flags are a separate configuration path from
Agents.
## Not in scope
- Reusing AI Gateway Bedrock flags as an implicit Agents fallback.
- Per-provider AWS access key, secret, or region fields (would need a
migration and audit-table review).
- IMDS or network-backed credential probes in admin/listing request
paths.
## Related
Dogfood deployment integration:
https://github.com/coder/dogfood/pull/324
## Description
Makes AWS Bedrock credentials optional. When `AccessKey` and
`AccessKeySecret` are not set, AI Bridge falls back to the AWS SDK
default credential chain, which supports IAM Roles (instance profiles,
IRSA, ECS task roles), SSO, shared credentials files, and environment
variables.
This allows AI Bridge to authenticate with AWS Bedrock using:
- Permanent credentials (access key + secret) as before
- IAM Roles, shared config files, environment variables, SSO, etc, via
the SDK default credential chain
Depends on: https://github.com/coder/aibridge/pull/265
Related to: https://github.com/coder/aibridge/issues/144
Related to: https://linear.app/codercom/issue/AIGOV-67
_Disclaimer: initially produced by Claude Opus 4.6, modified and
reviewed by @ssncferreira ._
## Summary
Adds `--ai-gateway-allow-byok` deployment option to control whether
users can use Bring Your Own Key (BYOK) mode with AI Gateway.
When disabled (`--ai-gateway-allow-byok=false`), BYOK requests are
rejected with a 403 and a message directing the admin to enable the
flag. Centralized key authentication works regardless of this setting.
Defaults to `true` (BYOK allowed).
---------
Co-authored-by: Danny Kopping <danny@coder.com>
## Summary
Follows up on https://github.com/coder/coder/pull/24032
Adds a BYOK compatibility table to the AI Gateway client configuration
page, showing which clients support personal API keys and provider
subscriptions through AI Gateway.
We can simplify by merging related columns:
- Personal API Key (OpenAI) and Personal API Key (Anthropic) → Personal
API Key
- ChatGPT Subscription and Claude Subscription → Subscription (Claude
Pro/Max, ChatGPT Plus/Pro)
`NOTE`: This is displayed immediately after the existing Compatibility
table.
<img width="864" height="474" alt="image"
src="https://github.com/user-attachments/assets/644c5a7c-a9fe-454c-9112-3e3db268afc8"
/>
_Disclaimer: produced mostly by Claude Opus 4.6 following detailed
planning._
## Summary
- Support multiple instances of the same AI Bridge provider type via
indexed env vars (`CODER_AIBRIDGE_PROVIDER_<N>_<KEY>`), following the
`CODER_EXTERNAL_AUTH_<N>_<KEY>` pattern
- Existing single-provider env vars (`CODER_AIBRIDGE_OPENAI_KEY`, etc.)
continue to work unchanged
- Setting both a legacy env var and an indexed provider with the same
name errors at startup to prevent silent misconfiguration
- Mark legacy provider fields (`OpenAI`, `Anthropic`, `Bedrock`) as
deprecated in `AIBridgeConfig` in favor of `Providers`
## Example
```sh
CODER_AIBRIDGE_PROVIDER_0_TYPE=anthropic
CODER_AIBRIDGE_PROVIDER_0_NAME=anthropic-corp
CODER_AIBRIDGE_PROVIDER_0_KEY=sk-ant-corp-xxx
CODER_AIBRIDGE_PROVIDER_0_BASE_URL=https://llm-proxy.internal.example.com/anthropic
CODER_AIBRIDGE_PROVIDER_1_TYPE=anthropic
CODER_AIBRIDGE_PROVIDER_1_NAME=anthropic-direct
CODER_AIBRIDGE_PROVIDER_1_KEY=sk-ant-direct-yyy
```
Each instance is routed by name:
- /api/v2/aibridge/**anthropic-corp**/v1/messages
- /api/v2/aibridge/**anthropic-direct**/v1/messages
Closes
[AIGOV-157](https://linear.app/codercom/issue/AIGOV-157/spike-to-understand-if-there-is-a-simple-way-to-handle-multi-api-key)
---------
Signed-off-by: Danny Kopping <danny@coder.com>
## Summary
Follows up on https://github.com/coder/coder/pull/24032
Renames "Coder session token" to "Coder API token" in AI Gateway client
documentation pages.
Also renames the `CODER_SESSION_TOKEN` env var to `CODER_API_TOKEN` in
Codex CLI examples and Copilot proxy configuration.
Note: "Coder session token" is still used in some parts of the
documentation where it make sense.
---------
Co-authored-by: Susana Ferreira <susana@coder.com>
## Summary
Adds BYOK (Personal API Key) documentation for OpenCode.
## BYOK support
| Client | Personal API Key | ChatGPT Subscription | Claude Subscription
|
|--------------|------------------|----------------------|---------------------|
| Codex CLI | ✅ | ✅ | - |
| Claude Code | ✅ | - | ✅ |
| Mux | ? | ? | ? |
| OpenCode | ✅ | ❌ | ❌ |
| Factory | ✅ | ❌ | ❌ |
| Cline | ✅ Only OpenAI API | ❌ | ❌ |
| KiloCode | ❌ (client-side bug) | ❌ | ❌ |
| RooCode | ✅ Only OpenAI API | ❌ | ❌ |
| VSCode | ❌ | ❌ | ❌ |
| JetBrains | ❌ | ❌ | ❌ |
| Zed | ❌ | ❌ | ❌ |
| Copilot CLI | ? | ? | ? |
<details>
<summary>Why OpenCode doesn't support subscriptions through AI
Bridge</summary>
**ChatGPT subscription**: OpenCode's codex plugin [hardcodes the
upstream
URL](https://github.com/anomalyco/opencode/blob/3a0e00dd7f9192730f6d0eeee37ae0a5fb023927/packages/opencode/src/plugin/codex.ts#L458-L460)
to `https://chatgpt.com/backend-api/codex/responses` inside a custom
`fetch`, bypassing any configured `baseURL`.
**Claude subscription**: Anthropic [no longer
supports](https://www.reddit.com/r/ClaudeAI/comments/1r9hqdk/claude_subscriptions_will_no_longer_be_usable_in/)
using subscriptions in third-party clients.
</details>
## Notes
- Anthropic forbids Claude subscription in all 3rd-party clients
- OpenCode supports ChatGPT subscription, but there is no way to
customize BaseURL
- Does it make sense to investigate Mux?
- Factory doesn't support ChatGPT subscription
- Cline supports ChatGPT subscription, but there is no way to customize
BaseURL
- KiloCode supports CustomHeaders, but I wasn't able to make it work
neither for centralized key nor for BYOK. Seems support for custom
providers has bugs. I got different errors for different models, this
one is common:
`Unsupported parameter: 'max_tokens' is not supported with this model.
Use 'max_completion_tokens' instead.` Seems should be fixed on KiloCode
side.
- RooCode and Cline support only OpenAI. They have special
OpenAI-Compatible provider which allows adding custom headers.
- VSCode (NativeChat) uses github copilot under the hood. I wasn't able
to make it work, neither in VSCode nor in VSCode-Insiders on my MacOS. I
used VSCode-Insiders Version: 1.116.0-insider (Universal). I got
different errors. When I used Github Copilot Chat (stable release - it
ignored my AI Gateway configuration), when I tried to install Github
Copilot Chat pre-release it failed with
`~/.vscode-insiders/extensions/github.copilot-chat-0.43.2026040705`
- JetBrains (embedded AI assistant). OpenAI Compatible provider doesn't
support custom headers. Also I got some errors even for centralized key
setup.
- Zed doesn't support custom headers
- Copilot CLI is special, because it's only supported via gateway proxy.
But it also means that we don't need support of custom headers, because
`X-AI-Gov-Token` is set by proxy itself. So if BYOK is supported in
CopilotCLI - it should be supported for CopilotCLI via Bridge and
BridgeProxy.
## Questions
- Do we want to explicitly state that Claude Max/Pro or ChatGPT Plus/Pro
subscriptions aren’t supported by OpenCode via AIBridge? I initially
avoided mentioning it since this could change over time, and keeping
that information up to date across clients might be difficult.
Documents the private/reserved IP range restrictions added to AI Gateway
Proxy:
- **Restricting proxy access**: Updated to reflect that private/reserved
IP ranges are now blocked by default, with atomic IP validation to
prevent DNS rebinding. Documents the Coder access URL exemption and the
`CODER_AIBRIDGE_PROXY_ALLOWED_PRIVATE_CIDRS` option.
- **Upstream proxy**: Added a note on the DNS rebinding limitation when
an upstream proxy is configured, and that upstream proxies should
enforce their own restrictions.
> [!NOTE]
> Initially generated by Coder Agents, modified and reviewed by
@ssncferreira
Follow-up: #23109
Yevhenii Shcherbina