Merge branch 'main' into phorcys/refactor-devcontainer-docs

chore: make fmt && `make lint
/markdown`
2026-02-18 00:30:50 +01:00 · 2026-02-17 23:24:31 +00:00 · 2026-02-17 23:23:04 +00:00 · 2026-02-17 23:09:29 +00:00 · 2026-02-17 22:35:28 +00:00 · 2026-02-17 22:22:03 +00:00
4 changed files with 169 additions and 72 deletions
--- a/docs/admin/integrations/devcontainers/index.md
+++ b/docs/admin/integrations/devcontainers/index.md
@@ -1,11 +1,11 @@
 # Dev Containers

-Dev containers allow developers to define their development environment
+Dev Containers allow developers to define their development environment
 as code using the [Dev Container specification](https://containers.dev/).
 Configuration lives in a `devcontainer.json` file alongside source code,
 enabling consistent, reproducible environments.

-By adopting dev containers, organizations can:
+By adopting Dev Containers, organizations can:

 - **Standardize environments**: Eliminate "works on my machine" issues while
  still allowing developers to customize their tools within approved boundaries.
@@ -14,36 +14,129 @@ By adopting dev containers, organizations can:
 - **Improve security**: Use hardened base images and controlled package
  registries to enforce security policies while enabling developer self-service.

-Coder supports two approaches for running dev containers. Choose based on your
-infrastructure and workflow requirements.
+Coder supports multiple approaches for running Dev Containers. Choose based on
+your infrastructure and workflow requirements.

-## Dev Containers Integration
+## Comparison

-The Dev Containers Integration uses the standard `@devcontainers/cli` and Docker
-to run containers inside your workspace. This is the recommended approach for
-most use cases.
+| Method                                    | Dev Container CLI                                      | Envbuilder                            | CI/CD Pre-built                                           |
+|-------------------------------------------|--------------------------------------------------------|---------------------------------------|-----------------------------------------------------------|
+| **Standard Dev Container implementation** | ✅ Yes                                                  | ❌ No                                  | ✅ Yes                                                     |
+| **Full Dev Container Spec Support**       | ✅ All options                                          | ❌ Limited options                     | \~ Most options                                           |
+| **Startup Time**                          | Build at runtime, faster with caching                  | Build at runtime, faster with caching | Fast (pre-built)                                          |
+| **Docker Required**                       | ❌ Yes                                                  | ✅ No                                  | ✅ No                                                      |
+| **Caching**                               | More difficult                                         | ✅ Yes                                 | ✅ Yes                                                     |
+| **Repo Discovery**                        | ✅ Yes                                                  | ❌ No                                  | ❌ No                                                      |
+| **Custom Apps in-spec**                   | ✅ Via spec args                                        | ❌ No                                  | ❌ No                                                      |
+| **Debugging**                             | Easy                                                   | Very difficult                        | Moderate                                                  |
+| **Versioning**                            | \~ Via spec, or template                               | \~ Via spec, or template              | ✅ Image tags                                              |
+| **Testing Pipeline**                      | \~ Via CLI in CI/CD                                    | \~ Via CLI in CI/CD                   | ✅ Yes, via the same pipeline                              |
+| **Feedback Loop**                         | ✅ Fast                                                 | ✅ Fast                                | Slow (build, and then test)                               |
+| **Maintenance Status**                    | ✅ Active                                               | ⚠️ Maintenance mode                   | ✅ Active                                                  |
+| **Best For**                              | Dev flexibility, rapid iteration, feature completeness | Restricted environments               | Controlled and centralized releases, less dev flexibility |
+
+## Dev Container CLI
+
+The Dev Container CLI integration uses the standard `@devcontainers/cli` and Docker to run
+Dev Containers inside your workspace. This is the recommended approach for most use
+cases and provides the most complete Dev Container experience.
+
+Uses the
+[devcontainers-cli module](https://registry.coder.com/modules/devcontainers-cli),
+the `coder_devcontainer` Terraform resource, and
+`CODER_AGENT_DEVCONTAINERS_ENABLE=true`.
+
+**Pros:**
+
+- Standard Dev Container implementation via Microsoft's official `@devcontainers/cli` package.
+- Supports all Dev Container configuration options.
+- Supports custom arguments in the Dev Container spec for defining custom apps
+  without needing template changes.
+- Supports discovery of repos with Dev Containers in them.
+- Easier to debug, since you have access to the outer container.
+
+**Cons / Requirements:**
+
+- Requires Docker in workspaces. This does not necessarily mean Docker-in-Docker
+  or a specific Kubernetes runtime — you could use Rootless Podman or a
+  privileged sidecar.
+- Caching is more difficult than with Envbuilder or CI/CD pre-built approaches.

 **Best for:**

- Workspaces with Docker available (Docker-in-Docker or mounted socket)
- Dev container management in the Coder dashboard (discovery, status, rebuild)
- Multiple dev containers per workspace
+- Dev flexibility, rapid iteration, and feature completeness.
+- Workspaces with Docker available (Docker-in-Docker or mounted socket).
+- Dev Container management in the Coder dashboard (discovery, status, rebuild).
+- Multiple Dev Containers per workspace.

-[Configure Dev Containers Integration](./integration.md)
+See the [Dev Containers Integration](./integration.md) page for instructions.

 For user documentation, see the
 [Dev Containers user guide](../../../user-guides/devcontainers/index.md).

 ## Envbuilder

-Envbuilder transforms the workspace image itself from a `devcontainer.json`,
-rather than running containers inside the workspace. It does not require
-a Docker daemon.
+Envbuilder transforms the workspace environment itself from a Dev Container spec (i.e `devcontainer.json`),
+rather than running containers inside the workspace. It does not require a Docker
+daemon.
+
+> [!NOTE]
+> Envbuilder is in **maintenance mode**. No new features are planned to be
+> implemented. For most use cases, the
+> [Dev Container CLI](#dev-container-cli) or [CI/CD Pre-built](#cicd-pre-built)
+> approaches are recommended.
+
+**Pros:**
+
+- Does not require Docker in workspaces.
+- Easier caching.
+
+**Cons:**
+
+- Very complicated to debug, since Envbuilder replaces the filesystem of the
+  container. You can't access that environment within Coder easily if it fails,
+  and you won't have many debug tools.
+- Does not support all of the Dev Container configuration options.
+- Does not support discovery of repos with Dev Containers in them.
+- Less flexible and more complex in general.

 **Best for:**

- Environments where Docker is unavailable or restricted
- Infrastructure-level control over image builds, caching, and security scanning
- Kubernetes-native deployments without privileged containers
+- Environments where Docker is unavailable or restricted.
+- Infrastructure-level control over image builds, caching, and security scanning.
+- Kubernetes-native deployments without privileged containers.

-[Configure Envbuilder](./envbuilder/index.md)
+See the [Envbuilder](./envbuilder/index.md) page for instructions.
+
+## CI/CD Pre-built
+
+Build the Dev Container image from CI/CD and pull it from within Terraform. This
+approach separates the image build step from the workspace startup, resulting in
+fast startup times and a generic template that doesn't have any
+Dev Container-specific configuration items.
+
+**Pros:**
+
+- Standard Dev Container implementation via Microsoft's official `@devcontainers/cli` package.
+- Faster startup time — no need for a specific caching setup.
+- The template is generic and doesn't have any Dev Container-specific
+  configuration items.
+- Versioned via image tags.
+- Testable pipeline.
+
+**Cons:**
+
+- Adds a build step.
+- Does not support all of the runtime options, but still supports more options
+  than Envbuilder.
+- Does not support discovery of repos with Dev Containers.
+- Slow feedback loop (build, then test).
+
+**Best for:**
+
+- Controlled and centralized releases with less dev flexibility.
+- Teams that already have CI/CD pipelines for building images.
+- Environments that need fast, predictable startup times.
+
+For an example workflow, see the
+[uwu/basic-env CI/CD workflow](https://github.com/uwu/basic-env/blob/main/.github/workflows/_build-and-push.yml).
--- a/docs/admin/integrations/devcontainers/integration.md
+++ b/docs/admin/integrations/devcontainers/integration.md
@@ -1,13 +1,14 @@
 # Configure a template for Dev Containers

-This guide covers the Dev Containers Integration, which uses Docker. For
+This guide covers the Dev Containers CLI Integration, which uses Docker. For
 environments without Docker, see [Envbuilder](./envbuilder/index.md) as an
 alternative.

-To enable Dev Containers in workspaces, configure your template with the Dev Containers
-modules and configurations outlined in this doc.
+To enable Dev Containers in workspaces, configure your template with the [`devcontainers-cli`](https://registry.coder.com/modules/coder/devcontainers-cli)
+module and configurations outlined in this doc.

-Dev Containers are currently not supported in Windows or macOS workspaces.
+> [!WARNING]
+> Dev Containers are currently not supported in Windows or macOS workspaces.

 ## Configuration Modes

@@ -16,7 +17,7 @@ There are two approaches to configuring Dev Containers in Coder:
 ### Manual Configuration

 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:
+Container(s) should be started in your workspace. This approach provides:

 - Predictable behavior and explicit control
 - Clear template configuration
@@ -38,7 +39,7 @@ or work with many projects, as it reduces template maintenance overhead.

 Use the
 [devcontainers-cli](https://registry.coder.com/modules/devcontainers-cli) module
-to ensure the `@devcontainers/cli` is installed in your workspace:
+to ensure that the `@devcontainers/cli` NPM package is installed in your workspace:

 ```terraform
 module "devcontainers-cli" {
@@ -54,7 +55,7 @@ Alternatively, install the devcontainer CLI manually in your base image.

 The
 [`coder_devcontainer`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/devcontainer)
-resource automatically starts a Dev Container in your workspace, ensuring it's
+resource automatically starts a specific Dev Container in your workspace, ensuring it's
 ready when you access the workspace:

 ```terraform
@@ -74,9 +75,9 @@ For multi-repo workspaces, define multiple `coder_devcontainer` resources, each
 pointing to a different repository. Each one runs as a separate sub-agent with
 its own terminal and apps in the dashboard.

-## Enable Dev Containers Integration
+## Enable Dev Containers CLI Integration

-Dev Containers integration is **enabled by default** in Coder 2.24.0 and later.
+The Dev Containers CLI 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.

@@ -110,7 +111,7 @@ the feature.

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

-Enables the Dev Containers integration in the Coder agent.
+Enables the Dev Containers CLI Integration in the Coder agent.

 The Dev Containers feature is enabled by default. You can explicitly disable it
 by setting this to `false`.
@@ -160,6 +161,8 @@ always auto-start regardless of this setting.
 > [dev container features](../../../user-guides/devcontainers/working-with-dev-containers.md#dev-container-features).
 > For Coder-specific apps, use the
 > [`apps` customization](../../../user-guides/devcontainers/customizing-dev-containers.md#custom-apps).
+>
+> If you really need modules, look into [other Dev Container options](./index.md#comparison)

 Developers can customize individual dev containers using the `customizations.coder`
 block in their `devcontainer.json` file. Available options include:
@@ -174,7 +177,7 @@ block in their `devcontainer.json` file. Available options include:
 For the full reference, see
 [Customizing dev containers](../../../user-guides/devcontainers/customizing-dev-containers.md).

-## Complete Template Example
+## Simplified Template Example

 Here's a simplified template example that uses Dev Containers with manual
 configuration:
@@ -216,7 +219,9 @@ resource "coder_devcontainer" "my-repository" {
 ### Alternative: Project Discovery with Autostart

 By default, discovered containers appear in the dashboard but developers must
-manually start them. To have them start automatically, enable autostart:
+manually start them. To have them start automatically, enable autostart by setting the `CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE` environment to `true` within the workspace.
+
+For example, with a Docker-based template:

 ```terraform
 resource "docker_container" "workspace" {
@@ -236,24 +241,24 @@ With autostart enabled:

 - Discovered containers automatically build and start during workspace
  initialization
- The `coder_devcontainer` resource is not required
+- The [`coder_devcontainer`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/devcontainer) resource is not required
 - Developers can work with multiple projects seamlessly

 > [!NOTE]
 >
-> When using project discovery, you still need to install the devcontainers CLI
+> When using project discovery, you still need to install the `devcontainer` CLI
 > using the module or in your base image.

 ## Example Template

 The [Docker (Dev Containers)](https://github.com/coder/coder/tree/main/examples/templates/docker-devcontainer)
-starter template demonstrates Dev Containers integration using Docker-in-Docker.
-It includes the `devcontainers-cli` module, `git-clone` module, and the
-`coder_devcontainer` resource.
+starter template demonstrates the Dev Containers CLI Integration using Docker-in-Docker.
+It includes the [`devcontainers-cli`](https://registry.coder.com/modules/coder/devcontainers-cli) module, [`git-clone`](https://registry.coder.com/modules/git-clone) module, and the
+[`coder_devcontainer`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/devcontainer) resource.

 ## Next Steps

- [Dev Containers Integration](../../../user-guides/devcontainers/index.md)
+- [Dev Containers CLI Integration user guide](../../../user-guides/devcontainers/index.md)
 - [Customizing Dev Containers](../../../user-guides/devcontainers/customizing-dev-containers.md)
 - [Working with Dev Containers](../../../user-guides/devcontainers/working-with-dev-containers.md)
 - [Troubleshooting Dev Containers](../../../user-guides/devcontainers/troubleshooting-dev-containers.md)
--- a/docs/admin/templates/extending-templates/devcontainers.md
+++ b/docs/admin/templates/extending-templates/devcontainers.md
@@ -4,11 +4,11 @@ Dev containers extend your template with containerized development environments,
 allowing developers to work in consistent, reproducible setups defined by
 `devcontainer.json` files.

-Coder's Dev Containers Integration uses the standard `@devcontainers/cli` and
+Coder's main Dev Containers Integration uses the standard `@devcontainers/cli` and
 Docker to run containers inside workspaces.

 For setup instructions, see
 [Dev Containers Integration](../../integrations/devcontainers/integration.md).

-For an alternative approach that doesn't require Docker, see
-[Envbuilder](../../integrations/devcontainers/envbuilder/index.md).
+For alternative approaches and comparisons between them, see the
+[Dev Containers](../../integrations/devcontainers/index.md) page.
--- a/docs/user-guides/devcontainers/index.md
+++ b/docs/user-guides/devcontainers/index.md
@@ -1,4 +1,4 @@
-# Dev Containers
+# Dev Containers (via `@devcontainers/cli` CLI)

 [Dev containers](https://containers.dev/) define your development environment
 as code using a `devcontainer.json` file. Coder's Dev Containers integration
@@ -6,28 +6,27 @@ uses the [`@devcontainers/cli`](https://github.com/devcontainers/cli) and
 [Docker](https://www.docker.com) 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 configure
-[Envbuilder](../../admin/integrations/devcontainers/envbuilder/index.md) instead,
-which builds the workspace image itself from your dev container configuration.
+This guide covers the Dev Containers CLI integration which requires Docker. For workspaces without Docker in them,
+administrators can look into
+[other options](../../admin/integrations/devcontainers/index.md#comparison) instead.

-![Two dev containers running as sub-agents in a Coder workspace](../../images/user-guides/devcontainers/devcontainer-running.png)_Dev containers appear as sub-agents with their own apps, SSH access, and port forwarding_
+![Two Dev Containers running as sub-agents in a Coder workspace](../../images/user-guides/devcontainers/devcontainer-running.png)_Dev containers appear as sub-agents with their own apps, SSH access, and port forwarding_

 ## Prerequisites

 - Coder version 2.24.0 or later
- Docker available inside your workspace
- The `@devcontainers/cli` installed in your workspace
+- Docker available inside your workspace (via Docker-in-Docker or a mounted socket, see [Docker in workspaces](../../admin/templates/extending-templates/docker-in-workspaces.md) for details on how to achieve this)
+- The `devcontainer` CLI (`@devcontainers/cli` NPM package) 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. Most
-templates with Dev Containers support include both. See
-[Configure a template for dev containers](../../admin/integrations/devcontainers/integration.md)
+The Dev Containers CLI integration is enabled by default in Coder.
+
+Most templates with Dev Containers support include all these prerequisites. See
+[Configure a template for Dev Containers](../../admin/integrations/devcontainers/integration.md)
 for setup details.

 ## Features

- Automatic dev container detection from repositories
+- 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
@@ -46,7 +45,7 @@ development environment. You can place it in:
 - `.devcontainer.json` (root of repository)
 - `.devcontainer/<folder>/devcontainer.json` (for multiple configurations)

-The third option allows monorepos to define multiple dev container
+The third option allows monorepos to define multiple Dev Container
 configurations in separate sub-folders. See the
 [Dev Container specification](https://containers.dev/implementors/spec/#devcontainerjson)
 for details.
@@ -63,52 +62,52 @@ Here's a minimal example:
 For more configuration options, see the
 [Dev Container specification](https://containers.dev/).

-### Start your dev container
+### Start your Dev Container

-Coder automatically discovers dev container configurations in your repositories
+Coder automatically discovers Dev Container configurations in your repositories
 and displays them in your workspace dashboard. From there, you can start a dev
 container with a single click.

-![Discovered dev containers with Start buttons](../../images/user-guides/devcontainers/devcontainer-discovery.png)_Coder detects dev container configurations and displays them with a Start button_
+![Discovered Dev Containers with Start buttons](../../images/user-guides/devcontainers/devcontainer-discovery.png)_Coder detects Dev Container configurations and displays them with a Start button_

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

-### Connect to your dev container
+### Connect to your Dev Container

-Once running, your dev container appears as a sub-agent in your workspace
+Once running, your Dev Container appears as a sub-agent in your workspace
 dashboard. You can connect via:

 - **Web terminal** in the Coder dashboard
 - **SSH** using `coder ssh <workspace>.<agent>`
 - **VS Code** using the "Open in VS Code Desktop" button

-See [Working with dev containers](./working-with-dev-containers.md) for detailed
+See [Working with Dev Containers](./working-with-dev-containers.md) for detailed
 connection instructions.

 ## How it works

-The Dev Containers integration uses the `devcontainer` command from
+The Dev Containers CLI integration uses the `devcontainer` command from
 [`@devcontainers/cli`](https://github.com/devcontainers/cli) to manage
 containers within your Coder workspace.

 When a workspace with Dev Containers integration starts:

 1. The workspace initializes the Docker environment.
-1. The integration detects repositories with dev container configurations.
-1. Detected dev containers appear in the Coder dashboard.
+1. The integration detects repositories with Dev Container configurations.
+1. Detected Dev Containers appear in the Coder dashboard.
 1. If auto-start is configured (via `coder_devcontainer` or autostart settings),
-   the integration builds and starts the dev container automatically.
+   the integration builds and starts the Dev Container automatically.
 1. Coder creates a sub-agent for the running container, enabling direct access.

-Without auto-start, users can manually start discovered dev containers from the
+Without auto-start, users can manually start discovered Dev Containers from the
 dashboard.

 ### Agent naming

-Each dev container gets its own agent name, derived from the workspace folder
-path. For example, a dev container with workspace folder `/home/coder/my-app`
+Each Dev Container gets its own agent name, derived from the workspace folder
+path. For example, a Dev Container with workspace folder `/home/coder/my-app`
 will have an agent named `my-app`.

 Agent names are sanitized to contain only lowercase alphanumeric characters and
@@ -124,17 +123,17 @@ in your `devcontainer.json`.
  button
 - The `forwardPorts` property in `devcontainer.json` with `host:port` syntax
  (e.g., `"db:5432"`) for Docker Compose sidecar containers is not yet
-  supported. For single-container dev containers, use `coder port-forward` to
+  supported. For single-container Dev Containers, use `coder port-forward` to
  access ports directly on the sub-agent.
- Some advanced dev container features may have limited support
+- Some advanced Dev Container features may have limited support

 ## Next steps

- [Working with dev containers](./working-with-dev-containers.md) — SSH, IDE
+- [Working with Dev Containers](./working-with-dev-containers.md) — SSH, IDE
  integration, and port forwarding
- [Customizing dev containers](./customizing-dev-containers.md) — Custom agent
+- [Customizing Dev Containers](./customizing-dev-containers.md) — Custom agent
  names, apps, and display options
- [Troubleshooting dev containers](./troubleshooting-dev-containers.md) —
+- [Troubleshooting Dev Containers](./troubleshooting-dev-containers.md) —
  Diagnose common issues
 - [Dev Container specification](https://containers.dev/) — Advanced
  configuration options
Author	SHA1	Message	Date
Phorcys	885201bc1b	Merge branch 'main' into phorcys/refactor-devcontainer-docs	2026-02-18 00:30:50 +01:00
Phorcys	089a1d6b25	chore: `make fmt` && `make lint /markdown`	2026-02-17 23:24:31 +00:00
Phorcys	455e711e4d	fix(docs/admin/integrations): fix link to comparison section	2026-02-17 23:23:04 +00:00
Phorcys	65e83992fe	wip	2026-02-17 23:09:29 +00:00
Phorcys	50e672e480	chore: correct wording	2026-02-17 22:35:28 +00:00
Phorcys	26205e5850	docs: add dev container approach comparison table and CI/CD Pre-built section Update the devcontainers index page to cover three approaches instead of two: Dev Container CLI, Envbuilder, and CI/CD Pre-built. - Change intro from 'two approaches' to 'multiple approaches' - Add comparison table with feature-by-feature breakdown - Expand Dev Container CLI section with detailed pros/cons - Add maintenance mode notice to Envbuilder section - Add new CI/CD Pre-built section with pros/cons and example link	2026-02-17 22:22:03 +00:00