> [!NOTE]
> Generated by Coder Agents. The branch and this description were
written by an AI agent and need human review.
## Summary
Fourth stacked PR for the docs IA overhaul. PR C renamed the User guides
sidebar section to **Workspaces**. This PR renames its folder to match,
so the folder tree and the sidebar agree (DOCS-1154). The section's
title, position, and contents don't change.
- `docs/user-guides/**` moves to `docs/workspaces/**` with `git mv`: 33
files. That includes pages that are not in the sidebar and the three
pages PR C moved in (`persistent-shared-workspaces.md`,
`cloning-git-repositories.md`, `speed-up-templates.md`).
- `docs/manifest/user-guides.yml` and `docs/manifest/user-guides/` (4
files) move to `docs/manifest/workspaces.yml` and
`docs/manifest/workspaces/`, and `index.yml` lists `workspaces.yml` in
the same position.
- Every relative link and image path is fixed, in moved pages and in
pages that link to them. This was done in one scripted pass from a clean
tree. `docs/images/` stays where it is, so images under
`docs/images/user-guides/` keep their names; only the relative paths
that point at them change.
- Commit 2, `chore: point in-product docs links at the new docs paths`,
updates docs URLs outside `docs/`, then regenerates the files built from
them with `make gen`. You can drop that commit; the redirects cover the
old URLs.
- Updated sources: `site/` `docs()` links and hardcoded docs URLs,
`cli/sharing.go` help text, `README.md`, `examples/templates/` READMEs
and `docker/main.tf`, templatebuilder base READMEs, and the doc-check
skill's audience persona.
- Regenerated files: the `coder sharing add/remove` CLI golden files,
`docs/reference/cli/sharing/{add,remove}.md`, and
`examples/examples.gen.json`.
- Commit 3, `fix: keep docs links healthy before the release`, keeps
links working on the live site until a release that includes this stack
becomes the default docs version:
- In hand-written pages, the docs commit's rewrite left 4 absolute
`https://coder.com/docs/workspaces/...` URLs. They are now relative
links, anchors kept: `admin/networking/wildcard-access-url.md`,
`install/operate/upgrade/esr-2.24-2.29-upgrade.md` (2 links), and
`workspaces/workspace-access/jetbrains/gateway.md`.
- Every hardcoded, unversioned `https://coder.com/docs/workspaces/...`
URL that commit 2 introduced outside `docs/` goes back to
`https://coder.com/docs/user-guides/...`. That covers 32 URLs in
`README.md`, `cli/sharing.go`, the examples and templatebuilder READMEs,
`examples/templates/docker/main.tf`, the `UserDropdownContent.tsx`
constant and its story assertion, and a JSDoc link in
`site/src/api/queries/workspaces.ts`. `make gen` then regenerated the
CLI golden files, `docs/reference/cli/sharing/{add,remove}.md`, and
`examples/examples.gen.json`. See "Post-release follow-up".
- The `site/` `docs()` changes stay, because those URLs are versioned
(`/docs/@vX.Y.Z/...`) and resolve once the release ships.
Stack: `docs/ia-ai-sections` (#31645, with Templates squash-merged in
#31646) → `docs/ia-tutorials-nav` (#31647) → **this PR**.
Refs: Linear DOCS-1154, DOCS-1179.
## Move map
| Old | New |
| --- | --- |
| `docs/user-guides/**` (33 files) | `docs/workspaces/**` |
| `docs/manifest/user-guides.yml` | `docs/manifest/workspaces.yml` |
| `docs/manifest/user-guides/**` (4 files) |
`docs/manifest/workspaces/**` |
## Redirects added
| Source | Destination |
| --- | --- |
| `/docs/user-guides` | `/docs/workspaces` |
| `/docs/user-guides/:path*` | `/docs/workspaces/:path*` |
Updated existing rules so none of them chain through the new wildcard:
| Source | Old destination | New destination |
| --- | --- | --- |
| `/docs/ai-coder/ide-agents` | `/docs/user-guides/workspace-access` |
`/docs/workspaces/workspace-access` |
| `/docs/tutorials/best-practices/speed-up-templates` |
`/docs/user-guides/speed-up-templates` |
`/docs/workspaces/speed-up-templates` |
| `/docs/tutorials/cloning-git-repositories` |
`/docs/user-guides/cloning-git-repositories` |
`/docs/workspaces/cloning-git-repositories` |
| `/docs/tutorials/persistent-shared-workspaces` |
`/docs/user-guides/persistent-shared-workspaces` |
`/docs/workspaces/persistent-shared-workspaces` |
**coder.com and router static redirects:** a chain simulation of
coder.com's and the router's static rules together with this branch's
`docs/redirects.json` finds one problem from this PR. The static
`/docs/workspaces` → `/docs/user-guides/workspace-management` rule in
both repos would hide the new `docs/workspaces/index.md` behind a
redirect to `/docs/workspaces/workspace-management`.
coder/coder.com#1201 and coder/docs-engine#304 remove it, together with
the Templates loops from #31645, once a release with this layout is the
docs mainline. If this PR ships in a later release than #31645, drop the
`/docs/workspaces` part of those PRs until then. The other static
`/docs/user-guides/...` destinations there still work; each now takes
two redirects.
## Deviations from the proposal
- **Not in Proposal 1.** The proposal only renamed the sidebar title.
This folder rename was requested afterward so the folder-driven renderer
shows the same name.
- **Generated files belong to commit 2.** Commit 1 doesn't edit
generated docs. They change only through their sources and `make gen`.
- **Left unchanged on purpose:**
- `docs/images/user-guides/` keeps its name, as requested.
- `.github/workflows/test-docs-preview-mapper.sh` uses
`docs/user-guides/...` as synthetic fixture paths.
- `docs/templates/extending-templates/jetbrains-airgapped.md` has a
"file a GitHub issue" link whose URL-encoded body names
`coder.com/docs/user-guides/workspace-access/jetbrains/jetbrains-airgapped`.
That URL was already wrong before this PR (the page lives under
`templates/`), and it only pre-fills an issue body, so I left it.
- Database migrations and notification golden files: none of them
contain `user-guides` links.
## Open questions for Nick
1. Should `docs/images/user-guides/` be renamed to
`docs/images/workspaces/` in a follow-up, or stay as is?
2. Frontend review nits on existing code that this PR only touched; I
didn't change them:
- `UserDropdownContent.tsx` defines `CODER_DESKTOP_DOCS_URL` as a
hardcoded `https://coder.com/docs/...` URL instead of
`docs("/workspaces/desktop")`, which `SSHButton.tsx` uses for the same
page.
- The `UserDropdown` and `SecretsPageView` stories' `play` functions
only assert link attributes.
## Post-release follow-up
After a release that includes this stack becomes the default docs
version on coder.com, point these hardcoded URLs at the new paths. They
work today and redirect after the release. Anchors are unchanged. Rerun
`make gen` afterward to update the CLI golden files,
`docs/reference/cli/sharing/{add,remove}.md`, and
`examples/examples.gen.json`.
| Current (old) URL | Post-release URL | Files |
| --- | --- | --- |
| `https://coder.com/docs/user-guides/desktop` |
`https://coder.com/docs/workspaces/desktop` |
`site/src/modules/dashboard/Navbar/UserDropdown/UserDropdownContent.tsx`,
`UserDropdown.stories.tsx` |
| `https://coder.com/docs/user-guides/devcontainers` |
`https://coder.com/docs/workspaces/devcontainers` | `README.md` |
| `https://coder.com/docs/user-guides/shared-workspaces` |
`https://coder.com/docs/workspaces/shared-workspaces` | `cli/sharing.go`
(CLI help, 2 places) |
| `https://coder.com/docs/user-guides/workspace-access` |
`https://coder.com/docs/workspaces/workspace-access` | `README.md` |
|
`https://coder.com/docs/user-guides/workspace-access/jetbrains/toolbox`
| `https://coder.com/docs/workspaces/workspace-access/jetbrains/toolbox`
| `examples/templates/docker/main.tf` |
| `https://coder.com/docs/user-guides/workspace-dotfiles` |
`https://coder.com/docs/workspaces/workspace-dotfiles` |
`coderd/templatebuilder/bases/{azure-linux,docker,kubernetes}/README.md`,
`examples/templates/{azure-linux,docker,kubernetes}/README.md` |
| `https://coder.com/docs/user-guides/workspace-management` |
`https://coder.com/docs/workspaces/workspace-management` | `README.md`,
`coderd/templatebuilder/bases/{aws-linux,aws-windows,azure-linux,digitalocean-linux,docker,kubernetes}/README.md`,
`examples/templates/{aws-linux,aws-windows,azure-linux,azure-windows,digitalocean-linux,docker-devcontainer,docker-envbuilder,docker,kubernetes-devcontainer,kubernetes,nomad-docker}/README.md`,
`site/src/api/queries/workspaces.ts` (JSDoc) |
## Validation run
- `make gen/docs-manifest`: clean diff afterward.
- `make lint/docs-manifest`, `lint/docs-redirects` (`-base
docs/ia-tutorials-nav`: 36 rules OK), `lint/docs-html`, `lint/emdash`:
pass.
- `pnpm check-docs` (markdownlint + table formatter): pass.
- Vale over `docs/`: identical to `docs/ia-tutorials-nav` (12 warnings,
1 error, 645 suggestions, all pre-existing).
- Local relative-link check over `docs/**/*.md`: 0 unresolved (3410
links and images in 498 files).
- `grep -rn user-guides docs/` finds only `docs/redirects.json`, image
paths under `docs/images/user-guides/`, and the issue link above.
- Pre-commit hook: `make pre-commit-light` on the docs commit, and the
full `make pre-commit` (gen, fmt, lint/go, lint/ts, build, and others)
on the chore commit. `make gen` left a clean tree.
- Targeted tests:
- Go: `go test ./cli -run TestCommandHelp`, `./examples/...`,
`./coderd/templatebuilder/...`.
- Site: Vitest for the touched directories (22 files, 409 tests), and
the `UserDropdown` and `SecretsPageView` story tests (2 files, 59
tests).
- Every `docs()` path and `coder.com/docs` URL in the chore diff
resolves to a page and heading in this branch.
- Frontend deep review (all 8 roles) on the `site/` diff: no blocking or
should-fix findings; the nits are in question 2.
- Restacked on the rebased `docs/ia-tutorials-nav` (on `main` at
`ccf5ec74ae`). After the restack, `make gen/docs-manifest` (clean),
`lint/docs-manifest`, `lint/docs-redirects` (36 rules OK),
`lint/docs-html`, `lint/emdash`, `pnpm check-docs`, and the
relative-link and anchor check over the changed pages pass.
- Page counts: `docs/**/*.md` (excluding `.style`) 485 → 485;
`manifest.json` routes 482 → 482 (moves only).
- **Link health (commit 3):**
- linkspector 0.5.6 with `.github/.linkspector.yml` over all of `docs/`,
like the weekly docs job, run locally.
- `origin/main`: 0 errors. Before the fix (`7382a41faa`): 11 errors. 10
were `https://coder.com/docs/<new path>` 404s: the 6 from #31645 plus 4
`workspaces/...` URLs. The 11th was a transient Red Hat URL failure in
`install/server/openshift.md`, which is unchanged from `main` and passed
on reruns. After the fix (`c1f287fc1b`): 0 errors. Nothing is new
compared with `main`.
- After the fix: `make gen/docs-manifest` (clean), `lint/docs-manifest`,
`lint/docs-redirects` (36 rules OK against `docs/ia-tutorials-nav`),
`lint/docs-html`, `lint/emdash`, `pnpm check-docs`, and the
relative-link check (0 unresolved in 3419 links) pass. The full `make
pre-commit`, including `make gen`, passed on the commit.
- Outside `docs/`, no line in this stack adds an unversioned
`coder.com/docs` URL compared with `main`.
- Tests after the fix:
- Go: `go test ./cli -run 'TestCommandHelp|TestServerYAMLConfig'`,
`./examples/...`, `./coderd/templatebuilder/...`, `./cli/cliui`.
- Site: Vitest for the touched directories (21 files, 404 tests), and
the `UserDropdown` story tests (28 tests).
- **Skipped:** the docs-engine sync check, which was not available in
this environment.
<details>
<summary>Implementation notes</summary>
- Same one-shot move script as PRs A to C, with a single rule,
`docs/user-guides/` → `docs/workspaces/`. It resolves each relative link
against the page's old directory, maps the target through the move,
recomputes it from the new directory, and also rewrites
`coder.com/docs/...` and
`github.com/coder/coder/(blob|edit|tree)/main/docs/...` URLs. It skips
fenced code blocks and inline code, and refuses to run on a dirty
`docs/` tree.
- After #31645 and #31647 got their link-health fixes, a plain rebase of
this branch conflicted in `esr-2.24-2.29-upgrade.md`, where both changed
the same table rows. Instead of resolving by hand, I rebuilt the docs
and chore commits from the fixed `docs/ia-tutorials-nav` with the same
scripts. The resulting docs commit differs from the earlier one only by
#31645's fix, and the chore commit touches the same 36 files.
- No hand edits were needed in the docs commit. The sidebar sources were
renamed with `git mv` and their `path`/`include` prefixes rewritten.
- The redirect script repointed every existing destination under
`/docs/user-guides` before appending the two new rules.
- Restacked on 2026-11-03 onto `docs/ia-tutorials-nav` at `76aed1a618`.
The chore commit conflicted with #31603 in
`site/src/pages/WorkspacesPage/WorkspaceHelpPopover.tsx`; both links
keep `main`'s `target="_blank" rel="noreferrer"` with only the path
changed, and the `WorkspacesPage` Vitest suite (24 tests) passes. Folded
into the docs commit: the `../user-guides/` links in
`docs/coder-agents/bring-your-own-mcp-servers.md`, a page `main` added,
now point at `../workspaces/`.
</details>
---------
Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com>
Co-authored-by: Nick Vigilante <nick.vigilante@coder.com>
9.7 KiB
title
| title |
|---|
| Customizing dev containers |
Coder supports custom configuration in your devcontainer.json file through the customizations.coder block.
These options let you control how Coder interacts with your dev container without requiring template changes.
Tip
Alternatively, template administrators can also define apps, scripts, and environment variables for dev containers directly in Terraform. See Attach resources to dev containers for details.
Ignore a dev container
Use the ignore option to hide a dev container from Coder completely:
{
"name": "My Dev Container",
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
"customizations": {
"coder": {
"ignore": true
}
}
}
When ignore is set to true:
- The dev container won't appear in the Coder UI
- Coder won't manage or monitor the container
This is useful for dev containers in your repository that you don't want Coder to manage.
Auto-start
Control whether your dev container should auto-start using the autoStart option:
{
"name": "My Dev Container",
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
"customizations": {
"coder": {
"autoStart": true
}
}
}
When autoStart is set to true, the dev container automatically builds and starts during workspace initialization.
When autoStart is set to false or omitted, the dev container is discovered and shown in the UI, but users must manually start it.
Note
The
autoStartoption only takes effect when your template administrator has enabledCODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE. If this setting is disabled at the template level, containers won't auto-start regardless of this option.
Custom agent name
Each dev container gets an agent name derived from the workspace folder path by default.
You can set a custom name using the name option:
{
"name": "My Dev Container",
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
"customizations": {
"coder": {
"name": "my-custom-agent"
}
}
}
The name must contain only lowercase letters, numbers, and hyphens.
This name appears in coder ssh commands and the dashboard (for example, coder ssh my-workspace.my-custom-agent).
Display apps
Control which built-in Coder apps appear for your dev container using displayApps:
Disable built-in apps to reduce clutter or guide developers toward preferred tools
{
"name": "My Dev Container",
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
"customizations": {
"coder": {
"displayApps": {
"web_terminal": true,
"ssh_helper": true,
"port_forwarding_helper": true,
"vscode": true,
"vscode_insiders": false
}
}
}
}
Available display apps:
| App | Description | Default |
|---|---|---|
web_terminal |
Web-based terminal access | true |
ssh_helper |
SSH connection helper | true |
port_forwarding_helper |
Port forwarding interface | true |
vscode |
VS Code Desktop integration | true |
vscode_insiders |
VS Code Insiders integration | false |
Custom apps
Define custom applications for your dev container using the apps array:
{
"name": "My Dev Container",
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
"customizations": {
"coder": {
"apps": [
{
"slug": "zed",
"displayName": "Zed Editor",
"url": "zed://ssh/${localEnv:CODER_WORKSPACE_AGENT_NAME}.${localEnv:CODER_WORKSPACE_NAME}.${localEnv:CODER_WORKSPACE_OWNER_NAME}.coder${containerWorkspaceFolder}",
"external": true,
"icon": "/icon/zed.svg",
"order": 1
}
]
}
}
}
This example adds a Zed Editor button that opens the dev container directly in the Zed desktop app via its SSH remote feature.
Each app supports the following properties:
| Property | Type | Description |
|---|---|---|
slug |
string | Unique identifier for the app (required) |
displayName |
string | Human-readable name shown in the UI |
url |
string | URL to open (supports variable interpolation) |
command |
string | Command to run instead of opening a URL |
icon |
string | Path to an icon (e.g., /icon/code.svg) |
openIn |
string | "tab" or "slim-window" (default: "slim-window") |
share |
string | "owner", "authenticated", "organization", or "public" |
external |
boolean | Open as external URL (e.g., for desktop apps) |
group |
string | Group name for organizing apps in the UI |
order |
number | Sort order for display |
hidden |
boolean | Hide the app from the UI |
subdomain |
boolean | Use subdomain-based access |
healthCheck |
object | Health check configuration (see below) |
An external app's url must include a scheme and a host, such as zed://ssh/... or https://....
Coder rejects javascript, vbscript, data, blob, file, and filesystem URLs, and URLs that contain control characters.
If an external app's url is invalid, Coder skips that app and still starts the dev container.
The reason is logged in the workspace agent log, /tmp/coder-agent.log.
Dev container apps don't support the $SESSION_TOKEN placeholder that template apps use.
Coder removes the placeholder from the url and keeps the rest of the URL, so a link such as token=$SESSION_TOKEN becomes token=.
Health checks
Configure health checks to monitor app availability:
{
"customizations": {
"coder": {
"apps": [
{
"slug": "web-server",
"displayName": "Web Server",
"url": "http://localhost:8080",
"healthCheck": {
"url": "http://localhost:8080/healthz",
"interval": 5,
"threshold": 2
}
}
]
}
}
}
Health check properties:
| Property | Type | Description |
|---|---|---|
url |
string | URL to check for health status |
interval |
number | Seconds between health checks |
threshold |
number | Number of failures before marking app unhealthy |
Variable interpolation
App URLs and other string values support variable interpolation for dynamic configuration.
Environment variables
Use ${localEnv:VAR_NAME} to reference environment variables, with optional default values:
{
"customizations": {
"coder": {
"apps": [
{
"slug": "my-app",
"url": "http://${localEnv:HOST:127.0.0.1}:${localEnv:PORT:8080}"
}
]
}
}
}
Coder-provided variables
Coder provides these environment variables automatically:
| Variable | Description |
|---|---|
CODER_WORKSPACE_NAME |
Name of the workspace |
CODER_WORKSPACE_OWNER_NAME |
Username of the workspace owner |
CODER_WORKSPACE_AGENT_NAME |
Name of the dev container agent |
CODER_WORKSPACE_PARENT_AGENT_NAME |
Name of the parent workspace agent |
CODER_URL |
URL of the Coder deployment |
CONTAINER_ID |
Docker container ID |
Dev container variables
Standard dev container variables are also available:
| Variable | Description |
|---|---|
${containerWorkspaceFolder} |
Workspace folder path inside the container |
${localWorkspaceFolder} |
Workspace folder path on the host |
Feature options as environment variables
When your dev container uses features, Coder exposes feature options as environment variables.
The format is FEATURE_<FEATURE_NAME>_OPTION_<OPTION_NAME>.
For example, with this feature configuration:
{
"features": {
"ghcr.io/coder/devcontainer-features/code-server:1": {
"port": 9090
}
}
}
Coder creates FEATURE_CODE_SERVER_OPTION_PORT=9090, which you can reference in your apps:
{
"features": {
"ghcr.io/coder/devcontainer-features/code-server:1": {
"port": 9090
}
},
"customizations": {
"coder": {
"apps": [
{
"slug": "code-server",
"displayName": "Code Server",
"url": "http://localhost:${localEnv:FEATURE_CODE_SERVER_OPTION_PORT:8080}",
"icon": "/icon/code.svg"
}
]
}
}
}
Next steps
- Working with dev containers: SSH, IDE integration, and port forwarding
- Troubleshooting dev containers: Diagnose common issues