## 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).
9.1 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 (e.g.,
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) |
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