2026-08-27 12:34:13 -04:00
---
title : Customizing dev containers
---
2025-12-05 19:42:16 +02:00
2026-10-14 14:04:33 -04:00
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.
2025-12-05 19:42:16 +02:00
2026-02-19 11:45:04 +00:00
> [!TIP]
>
2026-10-14 14:04:33 -04:00
> 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.
2026-02-19 11:45:04 +00:00
2025-12-05 19:42:16 +02:00
## 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
2026-10-14 14:04:33 -04:00
This is useful for dev containers in your repository that you don't want Coder to manage.
2025-12-05 19:42:16 +02:00
## Auto-start
2026-10-14 14:04:33 -04:00
Control whether your dev container should auto-start using the `autoStart` option:
2025-12-05 19:42:16 +02:00
```json
{
"name" : "My Dev Container" ,
"image" : "mcr.microsoft.com/devcontainers/base:ubuntu" ,
"customizations" : {
"coder" : {
"autoStart" : true
}
}
}
```
2026-10-14 14:04:33 -04:00
When `autoStart` is set to `true` , the dev container automatically builds and starts during workspace initialization.
2025-12-05 19:42:16 +02:00
2026-10-14 14:04:33 -04:00
When `autoStart` is set to `false` or omitted, the dev container is discovered and shown in the UI, but users must manually start it.
2025-12-05 19:42:16 +02:00
> [!NOTE]
>
2026-10-14 14:04:33 -04:00
> 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.
2025-12-05 19:42:16 +02:00
## Custom agent name
2026-10-14 14:04:33 -04:00
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:
2025-12-05 19:42:16 +02:00
```json
{
"name" : "My Dev Container" ,
"image" : "mcr.microsoft.com/devcontainers/base:ubuntu" ,
"customizations" : {
"coder" : {
"name" : "my-custom-agent"
}
}
}
```
2026-10-14 14:04:33 -04:00
The name must contain only lowercase letters, numbers, and hyphens.
2026-10-23 22:27:18 -07:00
This name appears in `coder ssh` commands and the dashboard (for example, `coder ssh my-workspace.my-custom-agent` ).
2025-12-05 19:42:16 +02:00
## Display apps
2026-10-14 14:04:33 -04:00
Control which built-in Coder apps appear for your dev container using `displayApps` :
2025-12-05 19:42:16 +02:00
2025-12-09 20:08:58 +02:00
_Disable built-in apps to reduce clutter or guide developers toward preferred tools_
2025-12-05 19:42:16 +02:00
```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
}
]
}
}
}
```
2026-10-14 14:04:33 -04:00
This example adds a Zed Editor button that opens the dev container directly in the Zed desktop app via its SSH remote feature.
2025-12-05 19:42:16 +02:00
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) |
2026-10-27 14:44:25 +03:00
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=` .
2025-12-05 19:42:16 +02:00
### 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
2026-10-14 14:04:33 -04:00
App URLs and other string values support variable interpolation for dynamic configuration.
2025-12-05 19:42:16 +02:00
### Environment variables
2026-10-14 14:04:33 -04:00
Use `${localEnv:VAR_NAME}` to reference environment variables, with optional default values:
2025-12-05 19:42:16 +02:00
```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
2026-10-14 14:04:33 -04:00
When your dev container uses features, Coder exposes feature options as environment variables.
The format is `FEATURE_<FEATURE_NAME>_OPTION_<OPTION_NAME>` .
2025-12-05 19:42:16 +02:00
For example, with this feature configuration:
```json
{
"features" : {
"ghcr.io/coder/devcontainer-features/code-server:1" : {
"port" : 9090
}
}
}
```
2026-10-14 14:04:33 -04:00
Coder creates `FEATURE_CODE_SERVER_OPTION_PORT=9090` , which you can reference in your apps:
2025-12-05 19:42:16 +02:00
```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
2026-10-14 14:04:33 -04:00
- [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