To enabledev containers in workspaces, configure your template with thedev containers

To enableDev Containers in workspaces, configure your template with theDev Containers

modules and configurations outlined in this doc.

There are two approaches to configuring Dev Containers in Coder:

Use the[`coder_devcontainer`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/devcontainer) Terraform resource to explicitly define which Dev

Containers 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.

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.

Use the

The

resource automatically starts adev container in your workspace, ensuring it's

resource automatically starts aDev Container in your workspace, ensuring it's

ready when you access the workspace:

To enable the dev containers integration in your workspace, you must set the

`CODER_AGENT_DEVCONTAINERS_ENABLE` environment variable to`true` in your

workspace container:

Dev Containers integration is**enabled by default** in Coder 2.24.0 and later.

You don't need to set any environment variables unless you want to change the

default behavior.

If you need to explicitly disable Dev Containers, set the

`CODER_AGENT_DEVCONTAINERS_ENABLE` environment variable to`false`:

This environment variable is required for the Coder agent to detect and manage

dev containers. Without it, the agent will not attempt to start or connect to

dev containers even if the`coder_devcontainer` resource is defined.

See the[Environment Variables](#environment-variables) section below for more

details on available configuration options.

The following environment variables control Dev Container behavior in your

workspace. Both`CODER_AGENT_DEVCONTAINERS_ENABLE` and

`CODER_AGENT_DEVCONTAINERS_PROJECT_DISCOVERY_ENABLE` are**enabled by default**,

so you typically don't need to set them unless you want to explicitly disable

the feature.

**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 it

by setting this to`false`.

**Default:`true`** •**Added in: v2.25.0**

Enables automatic discovery of Dev Containers in Git repositories.

When enabled, the agent will:

- Scan the agent directory for Git repositories

- Look for`.devcontainer/devcontainer.json` or`.devcontainer.json` files

- Surface discovered Dev Containers automatically in the Coder UI

- Respect`.gitignore` patterns during discovery

You can disable automatic discovery by setting this to`false` if you prefer to

use only the`coder_devcontainer` resource for explicit configuration.

**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 started

during workspace initialization. This only applies to Dev Containers found via

project discovery. Dev Containers defined with the`coder_devcontainer` resource

always auto-start regardless of this setting.

Individual Dev Containers can be customized using the`customizations.coder` block

in your`devcontainer.json` file. These customizations allow you to control

container-specific behavior without modifying your template.

Use the`ignore` option to hide a Dev Container from Coder completely:

{

"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

This is useful when you have Dev Containers in your repository that you don't

want Coder to manage.

Control whether individual Dev Containers should auto-start using the

`autoStart` option:

{

"name":"My Dev Container",

"image":"mcr.microsoft.com/devcontainers/base:ubuntu",

"customizations": {

"coder": {

"autoStart":true

}

}

}

**Important**: The`autoStart` option only applies when global auto-start is

enabled via`CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE=true`. If

the global setting is disabled, containers won't auto-start regardless of this

setting.

When`autoStart` is set to`true`:

- The Dev Container automatically builds and starts during workspace

initialization

- Works on a per-container basis (you can enable it for some containers but not

others)

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

Here's a simplified template example thatenables the dev containers

integration:

Here's a simplified template example thatuses Dev Containers with manual

configuration:

You can enable automatic starting of discovered Dev Containers:

With this configuration:

- Project discovery is enabled (default behavior)

- Discovered containers are automatically started (via the env var)

- The`coder_devcontainer` resource is**not** required

- Developers can work with multiple projects seamlessly

-[Dev Containers Integration](../../../user-guides/devcontainers/index.md)

The dev containers integration is an early access feature that enables seamless

creation and management of dev containers in Coder workspaces. This feature

leverages the[`@devcontainers/cli`](https://github.com/devcontainers/cli) and

The Dev Containers integration enables seamless creation and management of Dev

Containers in Coder workspaces. This feature leverages the

[`@devcontainers/cli`](https://github.com/devcontainers/cli) and

[Docker](https://www.docker.com) to provide a streamlined development

experience.

This implementation is different from the existing

[Envbuilder-baseddev containers](../../admin/templates/managing-templates/devcontainers/index.md)

[Envbuilder-basedDev Containers](../../admin/templates/managing-templates/devcontainers/index.md)

offering.

- Coder version 2.22.0 or later

- Coder CLI version 2.22.0 or later

- Coder version 2.24.0 or later

- Coder CLI version 2.24.0 or later

-**Linux or macOS workspace**, Dev Containers are not supported on Windows

- A template with:

- Devcontainers integration enabled

- DevContainers integration enabled

- A Docker-compatible workspace image

- Appropriate permissions to execute Docker commands inside your workspace

Thedev containers integration utilizes the`devcontainer` command from

[`@devcontainers/cli`](https://github.com/devcontainers/cli) to managedev

containers within your Coder workspace.

This command provides comprehensive functionality for creating, starting, and managingdev containers.

TheDev Containers integration utilizes the`devcontainer` command from

[`@devcontainers/cli`](https://github.com/devcontainers/cli) to manageDev

Containers within your Coder workspace.

This command provides comprehensive functionality for creating, starting, and managingDev Containers.

Dev environments are configured through a standard`devcontainer.json` file,

which allows for extensive customization of your development setup.

When a workspace with thedev containers integration starts:

When a workspace with theDev Containers integration starts:

1. The workspace initializes the Docker environment.

1. The integration detects repositories with a`.devcontainer` directory or a

`devcontainer.json` file.

1. The integration builds and starts thedev container based on the

1. The integration builds and starts theDev Container based on the

configuration.

1. Your workspace automatically detects the runningdev container.

1. Your workspace automatically detects the runningDev Container.

- Automatic dev container detection from repositories

- Seamless dev container startup during workspace initialization

- Integrated IDE experience in dev containers with VS Code

- Direct service access in dev containers

- Limited SSH access to dev containers

- Automatic Dev Container detection from repositories

- Seamless Dev Container startup during workspace initialization

- Dev Container change detection and dirty state indicators

- On-demand Dev Container recreation via rebuild button

- Integrated IDE experience in Dev Containers with VS Code

- Direct service access in Dev Containers

- SSH access to Dev Containers

- Automatic port detection for container ports

- Dev container change detection

- On-demand dev container recreation

- Support for automatic port forwarding inside the container

- Full native SSH support to dev containers

During the early access phase, the dev containers integration has the following

limitations:

The Dev Containers integration has the following limitations:

-**Not supported on Windows**

- Changes to the`devcontainer.json` file require manual container recreation

- Automatic port forwarding only works for ports specified in`appPort`

- SSH access requires using the`--container` flag

- Some devcontainer features may not work as expected

These limitations will be addressed in future updates as the feature matures.

using the rebuild button

- Some Dev Container features may not work as expected

| Feature| Dev Containers(Early Access)| Envbuilder Dev Containers|

| Feature| Dev ContainersIntegration| Envbuilder Dev Containers|

|----------------|----------------------------------------|----------------------------------------------|

| Implementation| Direct`@devcontainers/cli` and Docker| Coder's Envbuilder|

| Target users| Individual developers| Platform teams and administrators|

| Requirements| Docker access in workspace| Compatible with more restricted environments|

Choose the appropriate solution based on your team's needs and infrastructure

constraints. For additional details on Envbuilder'sdev container support, see

constraints. For additional details on Envbuilder'sDev Container support, see

the

[Envbuilderdevcontainer spec support documentation](https://github.com/coder/envbuilder/blob/main/docs/devcontainer-spec-support.md).

[EnvbuilderDev Container spec support documentation](https://github.com/coder/envbuilder/blob/main/docs/devcontainer-spec-support.md).

- Explore the[dev container specification](https://containers.dev/) to learn

- Explore the[Dev Container specification](https://containers.dev/) to learn

more about advanced configuration options

- Read about[dev container features](https://containers.dev/features) to

- Read about[Dev Container features](https://containers.dev/features) to

enhance your development environment

- Check the

[VS Code dev containers documentation](https://code.visualstudio.com/docs/devcontainers/containers)