## Summary
Update documentation across 9 files to present the template builder as
the primary template creation method, replacing the old starter
templates flow as the default entry point.
The template builder is a guided wizard that lets admins select base
infrastructure, add registry modules, configure variables, and produce
validated Terraform without writing HCL.
## Changes
**Primary docs (significant rewrites):**
- `docs/admin/templates/creating-templates.md`: Added "Using the
template builder" as the first section with full 5-step wizard
documentation, screenshots, airgap/registry notes, and alternative
creation links. Moved CLI starter template flow to its own section.
Fixed "You can the" typo.
- `docs/get-started/index.md`: Rewrote Steps 4-6 to use the builder with
the Docker base template instead of the Coder Quickstart (which is not a
builder base template). Generalized workspace parameter instructions.
- `docs/start/first-template.md`: Rewrote to use the builder. Removed
old starter templates references, TODO notes, typo, and commented-out
sections.
**Secondary docs (targeted edits):**
- `docs/admin/templates/index.md`: Replaced starter templates section
with builder-first "Create a template" section.
- `docs/admin/templates/managing-templates/index.md`: Renamed "Starter
templates" to "Creating templates" pointing to the builder.
- `docs/install/airgap.md`: Added "Template builder" section documenting
`CODER_DISABLE_TEMPLATE_BUILDER` and
`CODER_TEMPLATE_BUILDER_REGISTRY_URL`.
- `docs/tutorials/template-from-scratch.md`: Added TIP callout
recommending the builder. Fixed `coder templates create` -> `coder
templates push` inconsistency.
- `docs/admin/integrations/devcontainers/envbuilder/add-envbuilder.md`:
Updated Dashboard tab to reference the builder and "Upload an existing
template" alternative.
- `docs/about/screenshots.md`: Updated caption and image reference for
template builder.
**Screenshots added:**
- `templatebuilder_01_bases.png` (base selection step)
- `templatebuilder_02_modules.png` (module selection step)
- `templatebuilder_03_module_customization.png` (module settings step)
- `templatebuilder_04_customizations.png` (template customizations step)
<details>
<summary>Implementation plan</summary>
# Plan: Update docs/ for Template Builder Launch
## Summary
The Template Builder is a new guided wizard at `/templates/new/builder`
that lets admins create templates by selecting a base infrastructure
template, composing it with registry modules, configuring variables, and
producing a validated Terraform bundle without writing HCL. The docs
need to be updated to present this as the primary/recommended template
creation path, while preserving the existing paths (upload, CLI,
duplicate) as alternatives.
## Key behavioral facts from the code
- **Route**: `/templates/new/builder` (new), `/templates/new` (old,
still exists)
- **Entry point**: The "New Template" button on the Templates page links
to `/templates/new/builder` when the builder is enabled; otherwise falls
back to `/starter-templates`
- **5-step wizard**:
1. **Select base infrastructure** (e.g., Docker, AWS EC2, Kubernetes)
2. **Base template parameters** (optional, skipped if base has none)
3. **Select modules** (IDE, AI Agent, Source Control, etc.;
multi-select, grouped by category)
4. **Module settings** (optional, skipped if no configurable variables)
5. **Template customizations** (name, display name, description, icon,
organization)
- **Alternative creation links** are shown on step 1: "Start from
scratch", "Upload an existing template", "Browse community templates",
"Use template agent skill"
- **Disabled via**: `CODER_DISABLE_TEMPLATE_BUILDER` env var /
`--disable-template-builder` flag. When disabled, redirects to old
`/templates/new` flow
- **Registry URL override**: `CODER_TEMPLATE_BUILDER_REGISTRY_URL`
(default: `registry.coder.com`)
- **Requires outbound access** to `registry.coder.com` for `terraform
init` at compose time
- **Modules are bundled** with the Coder release binary; the builder
does not fetch metadata from the registry at runtime
- **Sensitive variables** (secrets) are not collected by the builder;
they are deferred to workspace creation time
- **Module conflicts** show a warning but do not block creation
- **One-way**: No re-entry into the builder for existing templates; edit
HCL directly after creation
## Files to update
### Tier 1: Primary creation flow docs (significant rewrites)
#### 1. `docs/admin/templates/creating-templates.md`
**Current state**: Documents three creation paths: "From a starter
template" (primary), "From an existing template", "From scratch
(advanced)".
**Changes**:
- Add a new section **"Using the template builder"** as the first and
primary section (before "From a starter template").
- Describe the 5-step wizard flow: select base infrastructure, configure
base parameters, select modules, configure module settings, set template
customizations.
- Mention that the builder is enabled by default and requires outbound
access to `registry.coder.com`.
- Note that sensitive variables are collected from developers at
workspace creation, not during template building.
- Add a callout about disabling the builder for airgapped deployments
(`CODER_DISABLE_TEMPLATE_BUILDER`).
- Note the `CODER_TEMPLATE_BUILDER_REGISTRY_URL` option for self-hosted
registry mirrors.
- Keep existing "From a starter template", "From an existing template",
and "From scratch" sections largely intact, but reframe them as
alternative paths.
- Update the "From a starter template" Web UI instructions to note the
new entry point routing (the "New Template" button now goes to the
builder when enabled).
- Fix existing typo: "You can the [Coder CLI]" should be "You can use
the [Coder CLI]".
#### 2. `docs/start/first-template.md`
**Current state**: Beginner tutorial walking through creating a template
from the Docker starter template via the old flow. Has a typo (`s` at
end of line 32), commented-out workspace creation section, and TODO
notes.
**Changes**:
- Rewrite steps 2 and 3 to use the Template Builder as the primary path.
- Step 2: Navigate to **Templates**, select **New Template**, which
opens the Template Builder.
- Step 3: Walk through the builder wizard steps (select Docker base,
optionally select modules like code-server, configure template
name/description, create).
- Remove the typo on line 32 (`s`).
- Keep the "Modify your template" section (step 6) intact since it
covers post-creation editing which is unchanged.
- Remove or update the reference to "Starter Templates" as a separate
page since the builder subsumes that entry point.
#### 3. `docs/get-started/index.md`
**Current state**: Quickstart guide. Step 4 says "Select **Templates** →
**New Template**" then pick "Coder Quickstart" from starter templates.
**Changes**:
- Update Step 4 to describe using the Template Builder.
- The flow becomes: Select **Templates** → **New Template** → builder
opens → select **Coder Quickstart** as the base template → optionally
add modules → set name/description → **Create Template**.
- Update the "What just happened?" explanation to mention the builder
composed and validated the Terraform.
- Screenshot reference `create-quickstart-template.png` will need a new
screenshot (note this in the PR; screenshots are out of scope for this
change but should be flagged).
### Tier 2: Secondary references (targeted edits)
#### 4. `docs/admin/templates/index.md`
**Current state**: Overview page mentioning starter templates as the
primary creation path.
**Changes**:
- Update the "Starter templates" section to mention the Template Builder
as the recommended way to create templates, with starter templates
serving as base templates within the builder.
- Update the link to point to the builder section: `[Create a template
with the template
builder](./creating-templates.md#using-the-template-builder)`.
- Update the screenshot reference and caption. The "Starter Templates"
page screenshot may no longer be the first thing admins see.
#### 5. `docs/admin/templates/managing-templates/index.md`
**Current state**: Documents starter templates, editing, updating,
deleting.
**Changes**:
- Update the "Starter templates" section to mention the Template Builder
as the primary creation path, with starter templates available as base
templates within it.
- Update the image reference from `starter-templates.png` if it shows
the old flow.
#### 6. `docs/tutorials/template-from-scratch.md`
**Current state**: Detailed tutorial for writing a template from scratch
with Terraform.
**Changes**:
- Add a brief note at the top recommending the Template Builder for
users who want to create templates without writing Terraform, with a
link to
`docs/admin/templates/creating-templates.md#using-the-template-builder`.
- In section "7. Create the template in Coder" → "Dashboard" tab, update
the UI steps. The "Upload template" option is now accessed via the old
creation flow at `/templates/new` (or through the "Upload an existing
template" link in the builder's alternatives).
- Fix the inconsistency where text says `coder templates create` but the
code block uses `coder templates push`.
#### 7.
`docs/admin/integrations/devcontainers/envbuilder/add-envbuilder.md`
**Current state**: Documents creating envbuilder templates via
Dashboard, CLI, and Registry tabs.
**Changes**:
- In the Dashboard tab, update the instructions. The "Create Template"
button now opens the builder by default. Users need to use the "Upload
an existing template" alternative link or navigate to `/templates/new`
directly.
- Update "From scratch" reference since that option is now an
alternative link in the builder.
- The CLI and Registry tabs remain unchanged.
#### 8. `docs/install/airgap.md`
**Current state**: Documents air-gapped installations. No mention of
Template Builder.
**Changes**:
- Add a note in the relevant section about the Template Builder
requiring outbound access to `registry.coder.com`.
- Document `CODER_DISABLE_TEMPLATE_BUILDER` for fully air-gapped
deployments.
- Document `CODER_TEMPLATE_BUILDER_REGISTRY_URL` for deployments using a
self-hosted registry mirror.
#### 9. `docs/about/screenshots.md`
**Current state**: Contains a caption "Template administrators can
either create a new Template from scratch or choose a Starter Template".
**Changes**:
- Update the caption to mention the Template Builder as the primary
creation method.
- Screenshot reference may need updating (flag for new screenshot).
### Tier 3: Minor/link-only updates
#### 10. `docs/admin/users/organizations.md`
- If it references the old "Create Template" screen with an org picker,
add a note that the Template Builder also includes organization
selection in its final step.
#### 11. `docs/ai-coder/tasks.md`
- If it mentions creating templates, add a passing reference to the
Template Builder as an option.
## Files NOT to update
- `docs/reference/api/templatebuilder.md`: Auto-generated API reference.
Already correct.
- `docs/reference/api/schemas.md`: Auto-generated. Already correct.
- `docs/reference/cli/server.md`: Auto-generated. Already has
`--disable-template-builder` and `--template-builder-registry-url`.
- `docs/reference/cli/templates_create.md`: Already deprecated.
- `docs/reference/cli/templates.md`: No changes needed.
## Implementation order
1. `docs/admin/templates/creating-templates.md` (primary creation docs,
most content)
2. `docs/get-started/index.md` (quickstart)
3. `docs/start/first-template.md` (beginner tutorial)
4. `docs/admin/templates/index.md` (overview)
5. `docs/admin/templates/managing-templates/index.md` (managing
overview)
6. `docs/install/airgap.md` (airgap note)
7. `docs/tutorials/template-from-scratch.md` (from-scratch tutorial)
8. `docs/admin/integrations/devcontainers/envbuilder/add-envbuilder.md`
(envbuilder)
9. `docs/about/screenshots.md` (screenshot captions)
10. Minor link/reference updates in tier 3 files
## Style notes
- Follow the Diataxis framework; keep tutorials as tutorials, reference
as reference.
- Use present tense, active voice, second person.
- Bold for UI elements: **Templates**, **New Template**, **Create
Template**.
- No emdash/endash.
- Do not add screenshots; flag where new screenshots are needed as
comments/TODOs.
- Run `make fmt/markdown` and `make lint/markdown` after all changes.
- Verify all pages are already in `docs/manifest.json` (no new pages
being added, only existing pages being updated).
</details>
> 🤖 Generated by Coder Agents
## What
Adds a **Customize your template** series under the top-level **Get
started** section, at `docs/get-started/customize-your-template/`.
These guides extend the single-page Quickstart (added in #26821) with
hands-on template customization:
- **Add a programming language** — expose a language through a
parameter, install it at startup, and offer it as a preset.
- **Install your own command-line tools** — install personal tools with
Homebrew and mise, and make them persist.
- **Clone private repositories** — authenticate workspaces to GitHub
with an external-auth data source.
## Changes from the earlier draft
This branch was rebased onto the consolidated `/docs/get-started`
structure:
- Re-homed the series from `tutorials/quickstart/` to
`get-started/customize-your-template/`, nested under the new Get started
section.
- Dropped the Part 1 launch page and the old landing page; the merged
Quickstart (`get-started/index.md`, #26821) already covers them.
- Archived the dotfiles guide out of the series (tracked as a follow-up
to document the dotfiles module as a standalone tutorial) and removed
its inbound links.
- Renamed the section to **Customize your template**.
- Added a Ruby **preset** alongside the Ruby parameter so the parameter
and preset choices stay in sync.
- Fixed the parameter-change steps to route through **Workspace settings
> Parameters**.
- Gave each page a **What's next?** step so the series reads as a
sequence.
## Still open / follow-ups
- Screenshots for the UI steps (handled separately).
- The launch step will be revised after the template-builder change
ships in the next mainline release.
<details>
<summary>Decision log</summary>
- **Why re-home, not keep `tutorials/quickstart/`:** the Quickstart now
lives at `/docs/get-started`, so the series belongs under the same
top-level section for a single, coherent entry point.
- **Why drop Part 1 here:** the launch content already merged as
`get-started/index.md` in #26821; keeping a second copy would duplicate
and drift.
- **Why archive dotfiles:** it works better as a standalone module
tutorial than as a Quickstart step; removed from the series for now and
tracked for later.
- **Final code fixtures** stay scoped per guide (base template plus that
page's edit), so only the language guide's fixture gains the Ruby option
and preset.
</details>
---
Generated by Coder Agents on behalf of @nickvigilante.
Add a top-level "Get started" docs section to the nav and move the Quickstart to /docs/get-started, with inbound link updates and the install page TIP pointing to the Quickstart.
Filed via Coder Agents on Nick's behalf.
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.
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.
#11918 took away advanced settings during template creation however it
did not clean up the documentation of a reference to customising the
template permissions during template creation -
https://coder.com/docs/admin/templates/template-permissions
> By default the Everyone group is assigned to each template meaning any
Coder user can use the template to create a workspace. To prevent this,
disable the Allow everyone to use the template setting when creating a
template.
This setting is no longer present in Coder, so removing it from the
docs.
Adds Coder Agents messaging to the README and about page
(docs/README.md), and updates the hero screenshots.
**README.md**: Adds agents to the tagline, intro paragraph, feature
bullets, and documentation links. Reorders docs section (Workspaces,
Templates, Agents, Administration, Premium, IDEs). Refreshes
integrations: Registry first, renames Dev Container Builder to Dev
Containers, Setup Coder to GitHub Actions, adds community
templates/modules/Discord links. Removes "we" language and vague link
text per docs style feedback.
**docs/README.md**: Adds dedicated Coder Workspaces and Coder Agents
sections with inline links to their respective doc pages. Rewrites "Why
remote development" as prose instead of a flat bullet list. Adds agents
benefits to "Why Coder" (MCP servers, skills, system prompts). Fixes
heading punctuation, replaces "Up next" with "Learn more", corrects
ARM/OS positioning. Removes stale Coder v1 section.
**Screenshots**: Replaces hero-image.png with an updated screenshot
showing templates and a running workspace with IDE apps. Adds
agents-hero-image.png showing the agents chat UI with the git diff
sidebar.
> Generated with [Coder Agents](https://coder.com/agents)
## 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.
Added new AWS install documentation and screenshots to support
deployment of AWS Marketplace Coder Community Edition, as the
primary/recommended method on AWS for POCs and experimenting with Coder.
Adds a new child page under **Coder Agents**
(`/docs/ai-coder/agents-architecture`) that explains how the agent in
the control plane communicates with workspaces.
## Core message
The Coder Agent interacts with workspaces using the exact same
connection path as a developer's IDE, web terminal, or SSH session — no
special protocol, no sidecar, no new ports.
## Changes
- Removed the Coder Agents entry from the middle of the children array
in `docs/manifest.json`.
- Added the Coder Agents entry back at the end of the children array to
improve the organization of the documentation structure.
<img width="368" height="688" alt="image"
src="https://github.com/user-attachments/assets/3117acfd-8c8a-4522-84e7-a748a7596cc6"
/>
<!--
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.
-->
Adds a new documentation page at `docs/ai-coder/agents.md` describing
Coder Agents — the built-in chat interface, API, and lightweight AI
coding agent that runs in the Coder control plane.
## What's included
- Overview of what Coder Agents is and who it's for (regulated
industries, platform teams, existing Coder deployments)
- How the architecture works (agent loop in coderd, outbound to LLM
providers, connects to workspaces via existing daemon connection)
- Key features: automatic template/workspace selection, sub-agents, chat
persistence, message queuing
- Security benefits of the control plane architecture (no API keys in
workspaces, simpler network boundaries, centralized enforced control,
user identity attached)
- LLM provider support table (verified against
`coderd/chatd/chatprovider/chatprovider.go`)
- Built-in tools reference
- Comparison to Coder Tasks
- Product status (internal preview, early access next)
### Summary
Workspace created via mode=auto links now require explicit user
confirmation before provisioning. A warning dialog shows all prefilled
param.* values from the URL and blocks creation until the user clicks
`Confirm and Create`. Clicking `Cancel` falls back to the standard form
view.
<img width="820" height="475" alt="auto-create-consent-dialog"
src="https://github.com/user-attachments/assets/8339e3bd-434f-4a04-9385-436bf95f49d7"
/>
### Breaking behavior change
Links using `mode=auto` (e.g., "Open in Coder" buttons) will no longer
silently create workspaces. Users will now see a consent dialog and must
explicitly confirm before the workspace is provisioned. Any existing
integrations or automation relying on `mode=auto` for seamless workspace
creation will now require manual user interaction.
---------
Co-authored-by: Jake Howell <jacob@coder.com>
- remove beta labels
- clarify how AWB is measured
- reassurance of no downtimes when limit is reached
---------
Co-authored-by: Atif Ali <atif@coder.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Matt Vollmer <matthewjvollmer@outlook.com>
Add screenshots to the dev containers user guide:
- Running dev containers with sub-agents (index.md, working-with-dev-containers.md)
- Discovered dev containers with Start button (index.md)
- Outdated status with rebuild option (working-with-dev-containers.md)
- Display apps disabled (customizing-dev-containers.md)
Also deletes the outdated devcontainer-agent-ports.png.
Refs #21157
---------
Co-authored-by: blink-so[bot] <211532188+blink-so[bot]@users.noreply.github.com>
Co-authored-by: Ben Potter <ben@coder.com>
Co-authored-by: Atif Ali <atif@coder.com>
Fixes#18767
This PR restores the missing `landing.png` and `duplicate.png` images
that were accidentally deleted in commit
b26c9e2432.
## Problem
The images were deleted during a documentation restructure, but external
links and cached website content are still referencing these image URLs,
causing 404 errors:
-
`https://raw.githubusercontent.com/coder/coder/main/docs/images/guides/ai-agents/landing.png`
-
`https://raw.githubusercontent.com/coder/coder/main/docs/images/guides/ai-agents/duplicate.png`
## Solution
Restore the original images from the git history to maintain backward
compatibility for external references while preserving the current
documentation structure.
## Testing
✅ Verified images are restored to correct location
✅ Confirmed file sizes match original images
✅ No conflicts with current documentation structure
Co-authored-by: blink-so[bot] <211532188+blink-so[bot]@users.noreply.github.com>
Co-authored-by: kylecarbs <7122116+kylecarbs@users.noreply.github.com>
closes#18071
- [x] move `## Accessing web apps in a secure browser context` to the
troubleshooting section
- [x] use a compacted view for troubleshooting topics to prevent them
from occupying a significant space on page
- [x] remove `Issues updating Coder Desktop`
- [x] Update screenshots
---------
Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Jeremy Ruppel
