1- # Configure a template for dev containers
1+ # Configure a template for Dev Containers
22
3- To enable dev containers in workspaces, configure your template with the dev containers
3+ To enable Dev Containers in workspaces, configure your template with the Dev Containers
44modules and configurations outlined in this doc.
55
6+ > [ !NOTE]
7+ >
8+ > Dev Containers require a ** Linux or macOS workspace** . Windows is not supported.
9+
10+ ## Configuration Modes
11+
12+ There are two approaches to configuring Dev Containers in Coder:
13+
14+ ### Manual Configuration
15+
16+ Use the [ ` coder_devcontainer ` ] ( https://registry.terraform.io/providers/coder/coder/latest/docs/resources/devcontainer ) Terraform resource to explicitly define which Dev
17+ Containers should be started in your workspace. This approach provides:
18+
19+ - Predictable behavior and explicit control
20+ - Clear template configuration
21+ - Easier troubleshooting
22+ - Better for production environments
23+
24+ This is the recommended approach for most use cases.
25+
26+ ### Project Discovery
27+
28+ Enable automatic discovery of Dev Containers in Git repositories. Project discovery automatically scans Git repositories for ` .devcontainer/devcontainer.json ` or ` .devcontainer.json ` files and surfaces them in the Coder UI. See the [ Environment Variables] ( #environment-variables ) section for detailed configuration options.
29+
630## Install the Dev Containers CLI
731
832Use the
@@ -23,7 +47,7 @@ Alternatively, install the devcontainer CLI manually in your base image.
2347
2448The
2549[ ` coder_devcontainer ` ] ( https://registry.terraform.io/providers/coder/coder/latest/docs/resources/devcontainer )
26- resource automatically starts a dev container in your workspace, ensuring it's
50+ resource automatically starts a Dev Container in your workspace, ensuring it's
2751ready when you access the workspace:
2852
2953``` terraform
@@ -50,30 +74,140 @@ resource "coder_devcontainer" "my-repository" {
5074
5175## Enable Dev Containers Integration
5276
53- To enable the dev containers integration in your workspace, you must set the
54- ` CODER_AGENT_DEVCONTAINERS_ENABLE ` environment variable to ` true ` in your
55- workspace container:
77+ Dev Containers integration is ** enabled by default** in Coder 2.24.0 and later.
78+ You don't need to set any environment variables unless you want to change the
79+ default behavior.
80+
81+ If you need to explicitly disable Dev Containers, set the
82+ ` CODER_AGENT_DEVCONTAINERS_ENABLE ` environment variable to ` false ` :
5683
5784``` terraform
5885resource "docker_container" "workspace" {
5986 count = data.coder_workspace.me.start_count
6087 image = "codercom/oss-dogfood:latest"
6188 env = [
62- "CODER_AGENT_DEVCONTAINERS_ENABLE=true",
89+ "CODER_AGENT_DEVCONTAINERS_ENABLE=false", # Explicitly disable
6390 # ... Other environment variables.
6491 ]
6592 # ... Other container configuration.
6693}
6794```
6895
69- This environment variable is required for the Coder agent to detect and manage
70- dev containers. Without it, the agent will not attempt to start or connect to
71- dev containers even if the ` coder_devcontainer ` resource is defined.
96+ See the [ Environment Variables] ( #environment-variables ) section below for more
97+ details on available configuration options.
98+
99+ ## Environment Variables
100+
101+ The following environment variables control Dev Container behavior in your
102+ workspace. Both ` CODER_AGENT_DEVCONTAINERS_ENABLE ` and
103+ ` CODER_AGENT_DEVCONTAINERS_PROJECT_DISCOVERY_ENABLE ` are ** enabled by default** ,
104+ so you typically don't need to set them unless you want to explicitly disable
105+ the feature.
106+
107+ ### CODER_AGENT_DEVCONTAINERS_ENABLE
108+
109+ ** Default: ` true ` ** • ** Added in: v2.24.0**
110+
111+ Enables the Dev Containers integration in the Coder agent.
112+
113+ The Dev Containers feature is enabled by default. You can explicitly disable it
114+ by setting this to ` false ` .
115+
116+ ### CODER_AGENT_DEVCONTAINERS_PROJECT_DISCOVERY_ENABLE
117+
118+ ** Default: ` true ` ** • ** Added in: v2.25.0**
119+
120+ Enables automatic discovery of Dev Containers in Git repositories.
121+
122+ When enabled, the agent will:
123+
124+ - Scan the agent directory for Git repositories
125+ - Look for ` .devcontainer/devcontainer.json ` or ` .devcontainer.json ` files
126+ - Surface discovered Dev Containers automatically in the Coder UI
127+ - Respect ` .gitignore ` patterns during discovery
128+
129+ You can disable automatic discovery by setting this to ` false ` if you prefer to
130+ use only the ` coder_devcontainer ` resource for explicit configuration.
131+
132+ ### CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE
133+
134+ ** Default: ` false ` ** • ** Added in: v2.25.0**
135+
136+ Automatically starts Dev Containers discovered via project discovery.
137+
138+ When enabled, discovered Dev Containers will be automatically built and started
139+ during workspace initialization. This only applies to Dev Containers found via
140+ project discovery. Dev Containers defined with the ` coder_devcontainer ` resource
141+ always auto-start regardless of this setting.
142+
143+ ## Per-Container Customizations
144+
145+ Individual Dev Containers can be customized using the ` customizations.coder ` block
146+ in your ` devcontainer.json ` file. These customizations allow you to control
147+ container-specific behavior without modifying your template.
148+
149+ ### Ignore Specific Containers
150+
151+ Use the ` ignore ` option to hide a Dev Container from Coder completely:
152+
153+ ``` json
154+ {
155+ "name" : " My Dev Container"
156+ "image" : " mcr.microsoft.com/devcontainers/base:ubuntu"
157+ "customizations" : {
158+ "coder" : {
159+ "ignore" : true
160+ }
161+ }
162+ }
163+ ```
164+
165+ When ` ignore ` is set to ` true ` :
166+
167+ - The Dev Container won't appear in the Coder UI
168+ - Coder won't manage or monitor the container
169+
170+ This is useful when you have Dev Containers in your repository that you don't
171+ want Coder to manage.
172+
173+ ### Per-Container Auto-Start
174+
175+ Control whether individual Dev Containers should auto-start using the
176+ ` autoStart ` option:
177+
178+ ``` json
179+ {
180+ "name" : " My Dev Container"
181+ "image" : " mcr.microsoft.com/devcontainers/base:ubuntu"
182+ "customizations" : {
183+ "coder" : {
184+ "autoStart" : true
185+ }
186+ }
187+ }
188+ ```
189+
190+ ** Important** : The ` autoStart ` option only applies when global auto-start is
191+ enabled via ` CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE=true ` . If
192+ the global setting is disabled, containers won't auto-start regardless of this
193+ setting.
194+
195+ When ` autoStart ` is set to ` true ` :
196+
197+ - The Dev Container automatically builds and starts during workspace
198+ initialization
199+ - Works on a per-container basis (you can enable it for some containers but not
200+ others)
201+
202+ When ` autoStart ` is set to ` false ` or omitted:
203+
204+ - The Dev Container is discovered and shown in the UI
205+ - Users must manually start it via the UI
72206
73207## Complete Template Example
74208
75- Here's a simplified template example that enables the dev containers
76- integration :
209+ Here's a simplified template example that uses Dev Containers with manual
210+ configuration :
77211
78212``` terraform
79213terraform {
@@ -107,18 +241,38 @@ resource "coder_devcontainer" "my-repository" {
107241 agent_id = coder_agent.dev.id
108242 workspace_folder = "/home/coder/my-repository"
109243}
244+ ```
245+
246+ ### Alternative: Project Discovery Mode
110247
248+ You can enable automatic starting of discovered Dev Containers:
249+
250+ ``` terraform
111251resource "docker_container" "workspace" {
112252 count = data.coder_workspace.me.start_count
113253 image = "codercom/oss-dogfood:latest"
114254 env = [
115- "CODER_AGENT_DEVCONTAINERS_ENABLE=true",
255+ # Project discovery is enabled by default, but autostart is not.
256+ # Enable autostart to automatically build and start discovered containers:
257+ "CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE=true",
116258 # ... Other environment variables.
117259 ]
118260 # ... Other container configuration.
119261}
120262```
121263
264+ With this configuration:
265+
266+ - Project discovery is enabled (default behavior)
267+ - Discovered containers are automatically started (via the env var)
268+ - The ` coder_devcontainer ` resource is ** not** required
269+ - Developers can work with multiple projects seamlessly
270+
271+ > [ !NOTE]
272+ >
273+ > When using project discovery, you still need to install the devcontainers CLI
274+ > using the module or in your base image.
275+
122276## Next Steps
123277
124278- [ Dev Containers Integration] ( ../../../user-guides/devcontainers/index.md )
0 commit comments