docs: document dev container customization options

mafredri · mafredri · commit e805ebb69fe1 · 2025-12-03T16:04:10.000Z
Add documentation for Coder-specific devcontainer.json customizations:

- Custom agent name via `name` option
- Display apps configuration (`displayApps`)
- Custom apps with full property reference
- Health check configuration
- Variable interpolation (${localEnv:...}, Coder variables, $SESSION_TOKEN)
- Feature options as environment variables (FEATURE_*_OPTION_*)
diff --git a/docs/admin/templates/extending-templates/devcontainers.md b/docs/admin/templates/extending-templates/devcontainers.md
@@ -204,6 +204,217 @@ When `autoStart` is set to `false` or omitted:
 - The Dev Container is discovered and shown in the UI
 - Users must manually start it via the UI
 
+### Custom agent name
+
+Set a custom name for the dev container's agent 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. If omitted,
+Coder derives the agent name from the workspace folder path (e.g.,
+`/home/coder/my-project` becomes `my-project`).
+
+### Display apps
+
+Control which built-in Coder apps appear for the dev container using
+`displayApps`:
+
+```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                  |
+|--------------------------|------------------------------|
+| `web_terminal`           | Web-based terminal access    |
+| `ssh_helper`             | SSH connection helper        |
+| `port_forwarding_helper` | Port forwarding interface    |
+| `vscode`                 | VS Code Desktop integration  |
+| `vscode_insiders`        | VS Code Insiders integration |
+
+By default, `web_terminal`, `ssh_helper`, `port_forwarding_helper`, and `vscode`
+are enabled.
+
+### Custom apps
+
+Define custom applications for the dev container using the `apps` array:
+
+```json
+{
+  "name": "My Dev Container",
+  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
+  "customizations": {
+    "coder": {
+      "apps": [
+        {
+          "slug": "my-web-app",
+          "displayName": "My Web App",
+          "url": "http://localhost:3000",
+          "openIn": "tab",
+          "share": "owner",
+          "icon": "/icon/web.svg",
+          "order": 1
+        }
+      ]
+    }
+  }
+}
+```
+
+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
+{
+  "apps": [
+    {
+      "slug": "web-server",
+      "displayName": "Web Server",
+      "url": "http://localhost:8080",
+      "healthCheck": {
+        "url": "http://localhost:8080/healthz",
+        "interval": 5,
+        "threshold": 2
+      }
+    }
+  ]
+}
+```
+
+### 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
+{
+  "url": "http://${localEnv:HOST:127.0.0.1}:${localEnv:PORT:8080}"
+}
+```
+
+#### Coder-provided variables
+
+Coder provides these environment variables during configuration:
+
+| 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          |
+
+#### Session token
+
+Use `$SESSION_TOKEN` in external app URLs to include the user's session token:
+
+```json
+{
+  "apps": [
+    {
+      "slug": "custom-ide",
+      "displayName": "Custom IDE",
+      "url": "custom-ide://open?token=$SESSION_TOKEN&folder=${containerWorkspaceFolder}",
+      "external": true
+    }
+  ]
+}
+```
+
+### Feature options as environment variables
+
+When your dev container uses features, Coder exposes feature options as
+environment variables for use in customizations. 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:
+
+```json
+{
+  "customizations": {
+    "coder": {
+      "apps": [
+        {
+          "slug": "code-server",
+          "url": "http://localhost:${localEnv:FEATURE_CODE_SERVER_OPTION_PORT:8080}"
+        }
+      ]
+    }
+  }
+}
+```
+
 ## Complete Template Example
 
 Here's a simplified template example that uses Dev Containers with manual
