Dev containers define your development environmentas code using adevcontainer.json file. Coder's Dev Containers integrationuses the@devcontainers/cli andDocker to seamlessly build and run these containers,with management in your dashboard.

This guide covers the Dev Containers integration. For workspaces without Docker,administrators can configureEnvbuilder instead,which builds the workspace image itself from your dev container configuration.

Prerequisites

• Coder version 2.24.0 or later
• Docker available inside your workspace
• The@devcontainers/cli installed in your workspace

Dev Containers integration is enabled by default. Your workspace needs Docker(via Docker-in-Docker or a mounted socket) and the devcontainers CLI. Mosttemplates with Dev Containers support include both. SeeConfigure a template for dev containersfor setup details.

Features

• Automatic dev container detection from repositories
• Seamless container startup during workspace initialization
• Change detection with outdated status indicator
• On-demand container rebuild via dashboard button
• Integrated IDE experience with VS Code
• Direct SSH access to containers
• Automatic port detection

Getting started

Add a devcontainer.json

Add adevcontainer.json file to your repository. This file defines yourdevelopment environment. You can place it in:

• .devcontainer/devcontainer.json (recommended)
• .devcontainer.json (root of repository)
• .devcontainer/<folder>/devcontainer.json (for multiple configurations)

The third option allows monorepos to define multiple dev containerconfigurations in separate sub-folders. See theDev Container specificationfor details.

Here's a minimal example:

For more configuration options, see theDev Container specification.

Start your dev container

Coder automatically discovers dev container configurations in your repositoriesand displays them in your workspace dashboard. From there, you can start a devcontainer with a single click.

If your template administrator has configured automatic startup (via thecoder_devcontainer Terraform resource or autostart settings), your devcontainer will build and start automatically when the workspace starts.

Connect to your dev container

Once running, your dev container appears as a sub-agent in your workspacedashboard. You can connect via:

• Web terminal in the Coder dashboard
• SSH usingcoder ssh <workspace>.<agent>
• VS Code using the "Open in VS Code Desktop" button

SeeWorking with dev containers for detailedconnection instructions.

How it works

The Dev Containers integration uses thedevcontainer command from@devcontainers/cli to managecontainers within your Coder workspace.

When a workspace with Dev Containers integration starts:

1. The workspace initializes the Docker environment.
2. The integration detects repositories with dev container configurations.
3. Detected dev containers appear in the Coder dashboard.
4. If auto-start is configured (viacoder_devcontainer or autostart settings),the integration builds and starts the dev container automatically.
5. Coder creates a sub-agent for the running container, enabling direct access.

Without auto-start, users can manually start discovered dev containers from thedashboard.

Agent naming

Each dev container gets its own agent name, derived from the workspace folderpath. For example, a dev container with workspace folder/home/coder/my-appwill have an agent namedmy-app.

Agent names are sanitized to contain only lowercase alphanumeric characters andhyphens. You can also set acustom agent namein yourdevcontainer.json.

Limitations

• Linux only: Dev Containers are currently not supported in Windows ormacOS workspaces
• Changes todevcontainer.json require manual rebuild using the dashboardbutton
• TheforwardPorts property indevcontainer.json withhost:port syntax(e.g.,"db:5432") for Docker Compose sidecar containers is not yetsupported. For single-container dev containers, usecoder port-forward toaccess ports directly on the sub-agent.
• Some advanced dev container features may have limited support

Next steps