## Summary **Batch A of Phase 3** of the H1 → front-matter migration (`DOCS-484`; parent `DOCS-477`). Adds a front-matter `title` to every navigable docs page whose title can be migrated **mechanically**, with no editorial judgment. This is the content step that Phase 1 (renderers prefer front-matter title, `DOCS-482`) and Phase 2 (tooling + generators front-matter-aware, `DOCS-483`) unblocked. Both are merged; coder.com #964/#974 are merged and live. **Rendered no-op.** The renderers already resolve the page title from the manifest and hide the leading body H1 (Phase 1), so no page changes visually. This just moves the title into front matter where Fumadocs and the migrated tooling can read it. ## What's in this batch Dry-run on `main` (464 navigable pages) splits into: | category | count | this PR | |----------|-------|---------| | already has front-matter title (Reference, from Phase 2 generators) | 196 | skipped (idempotent) | | **mechanical** — leading body H1 equals the manifest label | 138 | ✅ add front-matter `title`, drop the duplicate H1 | | **no body H1** — renders under the manifest label only | 4 | ✅ add front-matter `title` only | | **mismatch** — body H1 differs from the manifest label | 126 | ⏭️ deferred (needs an editorial decision, see below) | 142 files changed, all under `docs/`. ## Deliberately out of scope: the 126 mismatches Pages where the body H1 is richer than the short sidebar label (e.g. label **Modules** / H1 *Contributing modules*, label **Install** / H1 *Installing Coder*) need a canonical-title decision, not a script. A few even look like the body H1 is the redundant one (`install/cli.md` and `install/index.md` both carry the H1 *Installing Coder*). These will land in follow-up batches **by nav section** once the policy is set, so each gets real review. ## Verification AI was the primary author of this PR (see disclosure below); per the [AI Contribution Guidelines](https://coder.com/docs/about/contributing/AI_CONTRIBUTING) here is the manual verification. - Every added front-matter block parses as YAML and its `title` round-trips to the manifest label (checked programmatically across all 142 files). - Every removed line is a leading `# H1` that equalled the manifest title; no body prose was reflowed. Front matter is correctly hoisted above pre-existing `<!-- markdownlint-disable -->` comments on the two pages that had them. - `pnpm check-docs` (markdownlint-cli2 + table formatter) passes on the changed set: `Summary: 0 error(s)`. `MD041` stays off (re-enabled in Phase 4); `MD025` is not tripped because the duplicate body H1s are removed. ``` $ pnpm exec markdownlint-cli2 $(git diff --name-only origin/main) Linting: 142 file(s) Summary: 0 error(s) ``` Linear: DOCS-484 > This PR was created with AI assistance (Coder Agents).
5.3 KiB
title
| title |
|---|
| Reference |
Note
AI Gateway is part of AI Governance, which is included with a Premium license.
Deployment topologies
AI Gateway can run inside coderd or as a standalone data-plane service.
Both topologies run the same gateway request handling and keep coderd as the source of truth for Coder API key validation, provider configuration, and AI session records.
They differ in how requests are routed to the gateway.
Embedded gateway
By default, coder server runs an in-memory gateway instance in the coderd process.
AI clients send requests to <Coder access URL>/api/v2/ai-gateway/<provider-name>/.
The embedded gateway uses the same control RPC as a standalone deployment, over an in-process transport rather than a network connection.
It does not use a gateway key and does not negotiate an AI Gateway API version.
The following diagram shows the embedded topology:
Standalone gateway
A standalone deployment runs the AI traffic data plane outside the coderd process.
Each replica accepts client traffic, sends AI requests directly to upstream providers, and maintains a control connection to coderd by using a gateway key.
The control connection carries the following:
- Coder API key validation, which resolves each request to an active Coder user.
- AI budget checks, which reject requests from users over their spend limit.
- Provider configuration, plus a change signal when the provider set changes.
- AI session records.
- Deprecated: the configuration and access tokens used by injected MCP.
Standalone replicas have no authoritative database state. They keep ephemeral provider snapshots, request caches, provider key pools, and metrics in memory, and emit their own logs and traces. When API dumps are enabled, each replica writes its own API dumps to its own local disk.
coderd remains required for standalone operation.
A replica becomes unready when its control connection is unavailable, even if its HTTP listener remains healthy.
AI Gateway Proxy remains part of coder server and can forward its intercepted traffic to either the embedded gateway or a standalone endpoint.
Version compatibility
The control connection between a standalone replica and coderd uses a versioned AI Gateway API.
The current AI Gateway API version is defined in coderd/aibridged/proto/version.go.
coderd validates the AI Gateway API version that a standalone replica advertises before it accepts the control connection.
AI Gateway API compatibility follows these rules:
- The gateway and
coderdAI Gateway API major versions must match. - The gateway's AI Gateway API minor version must be less than or equal to the
coderdinstance's AI Gateway API minor version. coderdrejects a standalone gateway that advertises a newer AI Gateway API minor version.
A rejected replica receives an HTTP 400 response that reports the client_api_version and server_api_version values.
Coder build versions are not the compatibility criterion.
For upgrade and rollback ordering, refer to Version compatibility in the standalone deployment guide.
Supported APIs
API support is divided into two categories:
- Intercepted: Requests are intercepted, audited, and augmented.
- Passthrough: Requests are proxied directly to the upstream provider without auditing or augmentation.
Where relevant, both streaming and non-streaming requests are supported.
Paths are relative to the provider's base URL, such as https://ai-gateway.example.com/openai/v1 or https://ai-gateway.example.com/anthropic.
OpenAI
The OpenAI provider also serves the Azure OpenAI, Google, OpenRouter, Vercel, and OpenAI-compatible provider types.
Intercepted
Passthrough
The legacy /v1/completions API is deprecated and is not passed through.
Anthropic
The Anthropic provider also serves the AWS Bedrock provider type.
Intercepted
Passthrough
/v1/messages/count_tokens/v1/models(/*)/api/event_logging/*
GitHub Copilot
Intercepted
/chat/completions/responses/v1/messages
Passthrough
/models(/*)/agents/*/mcp/*/.well-known/*
Any route that is not listed above returns 404.
Troubleshooting
To report a bug, file a feature request, or review known issues, visit the Coder GitHub repository. For help with AI Gateway, visit the Coder Discord.
