Files
coder/docs/workspaces/devcontainers/customizing-dev-containers.md
coder[bot]andNick Vigilante a988af518c docs: rename the user-guides folder to workspaces (#31650)
> [!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>
2026-11-04 17:41:22 -05:00

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 autoStart option only takes effect when your template administrator has enabled CODER_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:

Dev container with all display apps disabledDisable 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