HomeAdministrationIntegrationsDev ContainersDev Containers Integration

Dev Containers Integration

This guide covers the Dev Containers Integration, which uses Docker. Forenvironments without Docker, seeEnvbuilder as analternative.

To enable Dev Containers in workspaces, configure your template with the Dev Containersmodules and configurations outlined in this doc.

Dev Containers are currently not supported in Windows or macOS workspaces.

Configuration Modes

There are two approaches to configuring Dev Containers in Coder:

Manual Configuration

Use thecoder_devcontainer Terraform resource to explicitly define which DevContainers should be started in your workspace. This approach provides:

Predictable behavior and explicit control
Clear template configuration
Easier troubleshooting
Better for production environments

This is the recommended approach for most use cases.

Project Discovery

Alternatively, enable automatic discovery of Dev Containers in Git repositories.The agent scans fordevcontainer.json files and surfaces them in the Coder UI.SeeEnvironment Variables for configuration options.

This approach is useful when developers frequently switch between repositoriesor work with many projects, as it reduces template maintenance overhead.

Install the Dev Containers CLI

Use thedevcontainers-cli moduleto ensure the@devcontainers/cli is installed in your workspace:

module "devcontainers-cli" {  count    = data.coder_workspace.me.start_count  source   = "registry.coder.com/coder/devcontainers-cli/coder"  agent_id = coder_agent.dev.id}

Alternatively, install the devcontainer CLI manually in your base image.

Configure Automatic Dev Container Startup

Thecoder_devcontainerresource automatically starts a Dev Container in your workspace, ensuring it'sready when you access the workspace:

resource "coder_devcontainer" "my-repository" {  count            = data.coder_workspace.me.start_count  agent_id         = coder_agent.dev.id  workspace_folder = "/home/coder/my-repository"}

Theworkspace_folder attribute must point to a valid project folder containingadevcontainer.json file. Consider using thegit-clone module to ensureyour repository is cloned and ready for automatic startup.

For multi-repo workspaces, define multiplecoder_devcontainer resources, eachpointing to a different repository. Each one runs as a separate sub-agent withits own terminal and apps in the dashboard.

Enable Dev Containers Integration

Dev Containers integration isenabled by default in Coder 2.24.0 and later.You don't need to set any environment variables unless you want to change thedefault behavior.

If you need to explicitly disable Dev Containers, set theCODER_AGENT_DEVCONTAINERS_ENABLE environment variable tofalse:

resource "docker_container" "workspace" {  count = data.coder_workspace.me.start_count  image = "codercom/oss-dogfood:latest"  env = [    "CODER_AGENT_DEVCONTAINERS_ENABLE=false",  # Explicitly disable    # ... Other environment variables.  ]  # ... Other container configuration.}

See theEnvironment Variables section below for moredetails on available configuration options.

Environment Variables

The following environment variables control Dev Container behavior in yourworkspace. BothCODER_AGENT_DEVCONTAINERS_ENABLE andCODER_AGENT_DEVCONTAINERS_PROJECT_DISCOVERY_ENABLE areenabled by default,so you typically don't need to set them unless you want to explicitly disablethe feature.

CODER_AGENT_DEVCONTAINERS_ENABLE

Default:true •Added in: v2.24.0

Enables the Dev Containers integration in the Coder agent.

The Dev Containers feature is enabled by default. You can explicitly disable itby setting this tofalse.

CODER_AGENT_DEVCONTAINERS_PROJECT_DISCOVERY_ENABLE

Default:true •Added in: v2.25.0

Enables automatic discovery of Dev Containers in Git repositories.

When enabled, the agent scans the configured working directory (set via thedirectory attribute incoder_agent, typically the user's home directory) forGit repositories. If the directory itself is a Git repository, it searches thatproject. Otherwise, it searches immediate subdirectories for Git repositories.

For each repository found, the agent looks fordevcontainer.json files in thestandard locationsand surfaces discovered Dev Containers in the Coder UI. Discovery respects.gitignore patterns.

Set tofalse if you prefer explicit configuration viacoder_devcontainer.

CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE

Default:false •Added in: v2.25.0

Automatically starts Dev Containers discovered via project discovery.

When enabled, discovered Dev Containers will be automatically built and startedduring workspace initialization. This only applies to Dev Containers found viaproject discovery. Dev Containers defined with thecoder_devcontainer resourcealways auto-start regardless of this setting.

Per-Container Customizations

Note

Dev container sub-agents are created dynamically after workspace provisioning,so Terraform resources likecoder_scriptandcoder_appcannot currently be attached to them. Modules from theCoder registry that depend on these resourcesare also not currently supported for sub-agents.

To add tools to dev containers, usedev container features.For Coder-specific apps, use theapps customization.

Developers can customize individual dev containers using thecustomizations.coderblock in theirdevcontainer.json file. Available options include:

ignore — Hide a dev container from Coder completely
autoStart — Control whether the container starts automatically (requiresCODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE to be enabled)
name — Set a custom agent name
displayApps — Control which built-in apps appear
apps — Define custom applications

For the full reference, seeCustomizing dev containers.

Complete Template Example

Here's a simplified template example that uses Dev Containers with manualconfiguration:

terraform {  required_providers {    coder  = { source = "coder/coder" }    docker = { source = "kreuzwerker/docker" }  }}provider "coder" {}data "coder_workspace" "me" {}data "coder_workspace_owner" "me" {}resource "coder_agent" "dev" {  arch                    = "amd64"  os                      = "linux"  startup_script_behavior = "blocking"  startup_script          = "sudo service docker start"  shutdown_script         = "sudo service docker stop"  # ...}module "devcontainers-cli" {  count    = data.coder_workspace.me.start_count  source   = "registry.coder.com/coder/devcontainers-cli/coder"  agent_id = coder_agent.dev.id}resource "coder_devcontainer" "my-repository" {  count            = data.coder_workspace.me.start_count  agent_id         = coder_agent.dev.id  workspace_folder = "/home/coder/my-repository"}

Alternative: Project Discovery with Autostart

By default, discovered containers appear in the dashboard but developers mustmanually start them. To have them start automatically, enable autostart:

resource "docker_container" "workspace" {  count = data.coder_workspace.me.start_count  image = "codercom/oss-dogfood:latest"  env = [    # Project discovery is enabled by default, but autostart is not.    # Enable autostart to automatically build and start discovered containers:    "CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE=true",    # ... Other environment variables.  ]  # ... Other container configuration.}

With autostart enabled:

Discovered containers automatically build and start during workspaceinitialization
Thecoder_devcontainer resource is not required
Developers can work with multiple projects seamlessly

Note

When using project discovery, you still need to install the devcontainers CLIusing the module or in your base image.

Example Template

TheDocker (Dev Containers)starter template demonstrates Dev Containers integration using Docker-in-Docker.It includes thedevcontainers-cli module,git-clone module, and thecoder_devcontainer resource.