Skip to content

Commit 350f810

Browse files
mafredrimafredri
committed
docs: add dev container customization guide
Documents Coder-specific `devcontainer.json` customizations including custom agent naming, display apps configuration, custom apps with health checks, and variable interpolation using `${localEnv:...}`, Coder variables, and `$SESSION_TOKEN`.
1 parent fa740a2 commit 350f810

File tree

4 files changed

+271
-1
lines changed

4 files changed

+271
-1
lines changed

‎docs/admin/templates/extending-templates/devcontainers.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -204,6 +204,13 @@ When `autoStart` is set to `false` or omitted:
204204
- The Dev Container is discovered and shown in the UI
205205
- Users must manually start it via the UI
206206

207+
### Additional customizations
208+
209+
Developers can further customize their dev containers with custom agent names,
210+
display apps, custom applications, and more. See
211+
[Customizing dev containers](../../../user-guides/devcontainers/customizing-dev-containers.md)
212+
for the full reference.
213+
207214
## Complete Template Example
208215

209216
Here's a simplified template example that uses Dev Containers with manual
@@ -276,5 +283,6 @@ With this configuration:
276283
## Next Steps
277284

278285
- [Dev Containers Integration](../../../user-guides/devcontainers/index.md)
286+
- [Customizing Dev Containers](../../../user-guides/devcontainers/customizing-dev-containers.md)
279287
- [Working with Dev Containers](../../../user-guides/devcontainers/working-with-dev-containers.md)
280288
- [Troubleshooting Dev Containers](../../../user-guides/devcontainers/troubleshooting-dev-containers.md)

‎docs/manifest.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -326,6 +326,11 @@
326326
"description": "Access dev containers via SSH, your IDE, or web terminal.",
327327
"path": "./user-guides/devcontainers/working-with-dev-containers.md"
328328
},
329+
{
330+
"title": "Customizing dev containers",
331+
"description": "Configure custom agent names, apps, and display options in devcontainer.json.",
332+
"path": "./user-guides/devcontainers/customizing-dev-containers.md"
333+
},
329334
{
330335
"title": "Troubleshooting dev containers",
331336
"description": "Diagnose and resolve common issues with dev containers in your Coder workspace.",

‎docs/user-guides/devcontainers/customizing-dev-containers.md‎

Lines changed: 253 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,253 @@
1+
# Customizing dev containers
2+
3+
Coder supports custom configuration in your `devcontainer.json` file through the
4+
`customizations.coder` block. These options let you control how Coder interacts
5+
with your dev container without requiring template changes.
6+
7+
## Custom agent name
8+
9+
Each dev container gets an agent name derived from the workspace folder path by
10+
default. You can set a custom name using the `name` option:
11+
12+
```json
13+
{
14+
"name": "My Dev Container",
15+
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
16+
"customizations": {
17+
"coder": {
18+
"name": "my-custom-agent"
19+
}
20+
}
21+
}
22+
```
23+
24+
The name must contain only lowercase letters, numbers, and hyphens. This name
25+
appears in `coder ssh` commands and the dashboard (e.g.,
26+
`coder ssh my-workspace.my-custom-agent`).
27+
28+
## Display apps
29+
30+
Control which built-in Coder apps appear for your dev container using
31+
`displayApps`:
32+
33+
```json
34+
{
35+
"name": "My Dev Container",
36+
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
37+
"customizations": {
38+
"coder": {
39+
"displayApps": {
40+
"web_terminal": true,
41+
"ssh_helper": true,
42+
"port_forwarding_helper": true,
43+
"vscode": true,
44+
"vscode_insiders": false
45+
}
46+
}
47+
}
48+
}
49+
```
50+
51+
Available display apps:
52+
53+
| App | Description | Default |
54+
|--------------------------|------------------------------|---------|
55+
| `web_terminal` | Web-based terminal access | `true` |
56+
| `ssh_helper` | SSH connection helper | `true` |
57+
| `port_forwarding_helper` | Port forwarding interface | `true` |
58+
| `vscode` | VS Code Desktop integration | `true` |
59+
| `vscode_insiders` | VS Code Insiders integration | `false` |
60+
61+
## Custom apps
62+
63+
Define custom applications for your dev container using the `apps` array:
64+
65+
```json
66+
{
67+
"name": "My Dev Container",
68+
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
69+
"customizations": {
70+
"coder": {
71+
"apps": [
72+
{
73+
"slug": "my-web-app",
74+
"displayName": "My Web App",
75+
"url": "http://localhost:3000",
76+
"openIn": "tab",
77+
"share": "owner",
78+
"icon": "/icon/web.svg",
79+
"order": 1
80+
}
81+
]
82+
}
83+
}
84+
}
85+
```
86+
87+
Each app supports the following properties:
88+
89+
| Property | Type | Description |
90+
|---------------|---------|---------------------------------------------------------------|
91+
| `slug` | string | Unique identifier for the app (required) |
92+
| `displayName` | string | Human-readable name shown in the UI |
93+
| `url` | string | URL to open (supports variable interpolation) |
94+
| `command` | string | Command to run instead of opening a URL |
95+
| `icon` | string | Path to an icon (e.g., `/icon/code.svg`) |
96+
| `openIn` | string | `"tab"` or `"slim-window"` (default: `"slim-window"`) |
97+
| `share` | string | `"owner"`, `"authenticated"`, `"organization"`, or `"public"` |
98+
| `external` | boolean | Open as external URL (e.g., for desktop apps) |
99+
| `group` | string | Group name for organizing apps in the UI |
100+
| `order` | number | Sort order for display |
101+
| `hidden` | boolean | Hide the app from the UI |
102+
| `subdomain` | boolean | Use subdomain-based access |
103+
| `healthCheck` | object | Health check configuration (see below) |
104+
105+
### Health checks
106+
107+
Configure health checks to monitor app availability:
108+
109+
```json
110+
{
111+
"customizations": {
112+
"coder": {
113+
"apps": [
114+
{
115+
"slug": "web-server",
116+
"displayName": "Web Server",
117+
"url": "http://localhost:8080",
118+
"healthCheck": {
119+
"url": "http://localhost:8080/healthz",
120+
"interval": 5,
121+
"threshold": 2
122+
}
123+
}
124+
]
125+
}
126+
}
127+
}
128+
```
129+
130+
Health check properties:
131+
132+
| Property | Type | Description |
133+
|-------------|--------|--------------------------------------------------|
134+
| `url` | string | URL to check for health status |
135+
| `interval` | number | Seconds between health checks |
136+
| `threshold` | number | Number of failures before marking app unhealthy |
137+
138+
## Variable interpolation
139+
140+
App URLs and other string values support variable interpolation for dynamic
141+
configuration.
142+
143+
### Environment variables
144+
145+
Use `${localEnv:VAR_NAME}` to reference environment variables, with optional
146+
default values:
147+
148+
```json
149+
{
150+
"customizations": {
151+
"coder": {
152+
"apps": [
153+
{
154+
"slug": "my-app",
155+
"url": "http://${localEnv:HOST:127.0.0.1}:${localEnv:PORT:8080}"
156+
}
157+
]
158+
}
159+
}
160+
}
161+
```
162+
163+
### Coder-provided variables
164+
165+
Coder provides these environment variables automatically:
166+
167+
| Variable | Description |
168+
|-------------------------------------|------------------------------------|
169+
| `CODER_WORKSPACE_NAME` | Name of the workspace |
170+
| `CODER_WORKSPACE_OWNER_NAME` | Username of the workspace owner |
171+
| `CODER_WORKSPACE_AGENT_NAME` | Name of the dev container agent |
172+
| `CODER_WORKSPACE_PARENT_AGENT_NAME` | Name of the parent workspace agent |
173+
| `CODER_URL` | URL of the Coder deployment |
174+
| `CONTAINER_ID` | Docker container ID |
175+
176+
### Dev container variables
177+
178+
Standard dev container variables are also available:
179+
180+
| Variable | Description |
181+
|-------------------------------|--------------------------------------------|
182+
| `${containerWorkspaceFolder}` | Workspace folder path inside the container |
183+
| `${localWorkspaceFolder}` | Workspace folder path on the host |
184+
185+
### Session token
186+
187+
Use `$SESSION_TOKEN` in external app URLs to include the user's session token:
188+
189+
```json
190+
{
191+
"customizations": {
192+
"coder": {
193+
"apps": [
194+
{
195+
"slug": "custom-ide",
196+
"displayName": "Custom IDE",
197+
"url": "custom-ide://open?token=$SESSION_TOKEN&folder=${containerWorkspaceFolder}",
198+
"external": true
199+
}
200+
]
201+
}
202+
}
203+
}
204+
```
205+
206+
## Feature options as environment variables
207+
208+
When your dev container uses features, Coder exposes feature options as
209+
environment variables. The format is `FEATURE_<FEATURE_NAME>_OPTION_<OPTION_NAME>`.
210+
211+
For example, with this feature configuration:
212+
213+
```json
214+
{
215+
"features": {
216+
"ghcr.io/coder/devcontainer-features/code-server:1": {
217+
"port": 9090
218+
}
219+
}
220+
}
221+
```
222+
223+
Coder creates `FEATURE_CODE_SERVER_OPTION_PORT=9090`, which you can reference in
224+
your apps:
225+
226+
```json
227+
{
228+
"features": {
229+
"ghcr.io/coder/devcontainer-features/code-server:1": {
230+
"port": 9090
231+
}
232+
},
233+
"customizations": {
234+
"coder": {
235+
"apps": [
236+
{
237+
"slug": "code-server",
238+
"displayName": "Code Server",
239+
"url": "http://localhost:${localEnv:FEATURE_CODE_SERVER_OPTION_PORT:8080}",
240+
"icon": "/icon/code.svg"
241+
}
242+
]
243+
}
244+
}
245+
}
246+
```
247+
248+
## Next steps
249+
250+
- [Working with dev containers](./working-with-dev-containers.md) — SSH, IDE
251+
integration, and port forwarding
252+
- [Troubleshooting dev containers](./troubleshooting-dev-containers.md) —
253+
Diagnose common issues

‎docs/user-guides/devcontainers/index.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -92,7 +92,9 @@ path. For example, a dev container with workspace folder `/home/coder/my-app`
9292
will have an agent named `my-app`.
9393

9494
Agent names are sanitized to contain only lowercase alphanumeric characters and
95-
hyphens.
95+
hyphens. You can also set a
96+
[custom agent name](./customizing-dev-containers.md#custom-agent-name)
97+
in your `devcontainer.json`.
9698

9799
## Limitations
98100

@@ -114,6 +116,8 @@ hyphens.
114116

115117
- [Working with dev containers](./working-with-dev-containers.md) — SSH, IDE
116118
integration, and port forwarding
119+
- [Customizing dev containers](./customizing-dev-containers.md) — Custom agent
120+
names, apps, and display options
117121
- [Troubleshooting dev containers](./troubleshooting-dev-containers.md) —
118122
Diagnose common issues
119123
- [Dev Container specification](https://containers.dev/) — Advanced

0 commit comments

Comments
 (0)