Files
coder/docs/user-guides/devcontainers/customizing-dev-containers.md
T
Nick Vigilante bc77c40296 docs: add front-matter titles to mechanical and no-H1 pages (Phase 3) (#28030)
## 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).
2026-08-27 12:34:13 -04:00

300 lines
9.1 KiB
Markdown

---
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](../../admin/integrations/devcontainers/integration.md#attach-resources-to-dev-containers)
> for details.
## Ignore a dev container
Use the `ignore` option to hide a dev container from Coder completely:
```json
{
"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:
```json
{
"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`](../../admin/integrations/devcontainers/integration.md#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:
```json
{
"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 (e.g.,
`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 disabled](../../images/user-guides/devcontainers/devcontainer-apps-bar.png)_Disable built-in apps to reduce clutter or guide developers toward preferred tools_
```json
{
"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:
```json
{
"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) |
### Health checks
Configure health checks to monitor app availability:
```json
{
"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:
```json
{
"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:
```json
{
"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:
```json
{
"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](./working-with-dev-containers.md) — SSH, IDE
integration, and port forwarding
- [Troubleshooting dev containers](./troubleshooting-dev-containers.md) —
Diagnose common issues