coder · mafredri · Dec 9, 2025 · Dec 8, 2025 · Dec 9, 2025
diff --git a/docs/admin/index.md b/docs/admin/index.md
@@ -52,7 +52,7 @@ For any information not strictly contained in these sections, check out our
 ### Development containers (dev containers)
 
 - A
-  [Development Container](./templates/extending-templates/devcontainers.md)
+  [Development Container](./integrations/devcontainers/index.md)
   is an open-source specification for defining development environments (called
   dev containers). It is generally stored in VCS alongside associated source
   code. It can reference an existing base image, or a custom Dockerfile that

diff --git a/...ng-templates/envbuilder/add-envbuilder.md → ...evcontainers/envbuilder/add-envbuilder.md b/...ng-templates/envbuilder/add-envbuilder.md → ...evcontainers/envbuilder/add-envbuilder.md
@@ -2,7 +2,7 @@
 
 A Coder administrator adds an Envbuilder-compatible template to Coder. This
 allows the template to prompt the developer for their dev container repository's
-URL as a [parameter](../../extending-templates/parameters.md) when they create
+URL as a [parameter](../../../templates/extending-templates/parameters.md) when they create
 their workspace. Envbuilder clones the repo and builds a container from the
 `devcontainer.json` specified in the repo.
 
@@ -127,7 +127,7 @@ their development environments:
 | [AWS EC2 dev container](https://github.com/coder/coder/tree/main/examples/templates/aws-devcontainer)               | Runs a development container inside a single EC2 instance. It also mounts the Docker socket from the VM inside the container to enable Docker inside the workspace. |
 
 Your template can prompt the user for a repo URL with
-[parameters](../../extending-templates/parameters.md):
+[parameters](../../../templates/extending-templates/parameters.md):
 
 ![Dev container parameter screen](../../../../images/templates/devcontainers.png)
 

diff --git a/...ilder/envbuilder-releases-known-issues.md → ...ilder/envbuilder-releases-known-issues.md b/...ilder/envbuilder-releases-known-issues.md → ...ilder/envbuilder-releases-known-issues.md
diff --git a/...envbuilder/envbuilder-security-caching.md → ...envbuilder/envbuilder-security-caching.md b/...envbuilder/envbuilder-security-caching.md → ...envbuilder/envbuilder-security-caching.md
diff --git a/docs/admin/integrations/devcontainers/envbuilder/index.md b/docs/admin/integrations/devcontainers/envbuilder/index.md
@@ -0,0 +1,53 @@
+# Envbuilder
+
+Envbuilder is an open-source tool that builds development environments from
+[dev container](https://containers.dev/implementors/spec/) configuration files.
+Unlike the [Dev Containers integration](../integration.md),
+Envbuilder transforms the workspace image itself rather than running containers
+inside the workspace.
+
+> [!NOTE]
+>
+> For most use cases, we recommend the
+> [Dev Containers integration](../integration.md),
+> which uses the standard `@devcontainers/cli` and Docker. Envbuilder is an
+> alternative for environments where Docker is not available or for
+> administrator-controlled dev container workflows.
+
+Dev containers provide developers with increased autonomy and control over their
+Coder cloud development environments.
+
+By using dev containers, developers can customize their workspaces with tools
+pre-approved by platform teams in registries like
+[JFrog Artifactory](../../jfrog-artifactory.md). This simplifies
+workflows, reduces the need for tickets and approvals, and promotes greater
+independence for developers.
+
+## Prerequisites
+
+An administrator should construct or choose a base image and create a template
+that includes a `devcontainer_builder` image before a developer team configures
+dev containers.
+
+## Devcontainer Features
+
+[Dev container Features](https://containers.dev/implementors/features/) allow
+owners of a project to specify self-contained units of code and runtime
+configuration that can be composed together on top of an existing base image.
+This is a good place to install project-specific tools, such as
+language-specific runtimes and compilers.
+
+## Coder Envbuilder
+
+[Envbuilder](https://github.com/coder/envbuilder/) is an open-source project
+maintained by Coder that runs dev containers via Coder templates and your
+underlying infrastructure. Envbuilder can run on Docker or Kubernetes.
+
+It is independently packaged and versioned from the centralized Coder
+open-source project. This means that Envbuilder can be used with Coder, but it
+is not required. It also means that dev container builds can scale independently
+of the Coder control plane and even run within a CI/CD pipeline.
+
+## Next steps
+
+- [Add an Envbuilder template](./add-envbuilder.md)
diff --git a/docs/admin/integrations/devcontainers/index.md b/docs/admin/integrations/devcontainers/index.md
@@ -0,0 +1,49 @@
+# Dev Containers
+
+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:
+
+- **Standardize environments**: Eliminate "works on my machine" issues while
+  still allowing developers to customize their tools within approved boundaries.
+- **Scale efficiently**: Let developers maintain their own environment
+  definitions, reducing the burden on platform teams.
+- **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.
+
+## Dev Containers Integration
+
+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.
+
+**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
+
+[Configure Dev Containers Integration](./integration.md)
+
+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.
+
+**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
+
+[Configure Envbuilder](./envbuilder/index.md)
diff --git a/docs/admin/integrations/devcontainers/integration.md b/docs/admin/integrations/devcontainers/integration.md
@@ -0,0 +1,266 @@
+# Configure a template for Dev Containers
+
+> [!NOTE]
+> 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.
+
+> [!NOTE]
+>
+> Dev Containers require a **Linux or macOS workspace**. Windows is not supported.
+
+## Configuration Modes
+
+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:
+
+- 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 for `devcontainer.json` files and surfaces them in the Coder UI.
+See [Environment Variables](#environment-variables) for configuration options.
+
+## Install the Dev Containers CLI
+
+Use the
+[devcontainers-cli](https://registry.coder.com/modules/devcontainers-cli) module
+to ensure the `@devcontainers/cli` is installed in your workspace:
+
+```terraform
+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
+
+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
+ready when you access the workspace:
+
+```terraform
+resource "coder_devcontainer" "my-repository" {
+  count            = data.coder_workspace.me.start_count
+  agent_id         = coder_agent.dev.id
+  workspace_folder = "/home/coder/my-repository"
+}
+```
+
+> [!NOTE]
+>
+> The `workspace_folder` attribute must specify the location of the dev
+> container's workspace and should point to a valid project folder containing a
+> `devcontainer.json` file.
+
+<!-- nolint:MD028/no-blanks-blockquote -->
+
+> [!TIP]
+>
+> Consider using the [`git-clone`](https://registry.coder.com/modules/git-clone)
+> module to ensure your repository is cloned into the workspace folder and ready
+> for automatic startup.
+
+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
+
+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`:
+
+```terraform
+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 the [Environment Variables](#environment-variables) section below for more
+details on available configuration options.
+
+## Environment Variables
+
+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.
+
+### 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 it
+by setting this to `false`.
+
+### 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 the
+`directory` attribute in `coder_agent`, typically the user's home directory) for
+Git repositories. If the directory itself is a Git repository, it searches that
+project. Otherwise, it searches immediate subdirectories for Git repositories.
+
+For each repository found, the agent looks for `devcontainer.json` files in the
+[standard locations](../../../user-guides/devcontainers/index.md#add-a-devcontainerjson)
+and surfaces discovered Dev Containers in the Coder UI. Discovery respects
+`.gitignore` patterns.
+
+Set to `false` if you prefer explicit configuration via `coder_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 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.
+
+## Per-Container Customizations
+
+> [!NOTE]
+>
+> Dev container sub-agents are created dynamically after workspace provisioning,
+> so Terraform resources like
+> [`coder_script`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/script)
+> and [`coder_app`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app)
+> cannot currently be attached to them. Modules from the
+> [Coder registry](https://registry.coder.com) that depend on these resources
+> are also not currently supported for sub-agents.
+>
+> To add tools to dev containers, use
+> [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).
+
+Developers can customize individual dev containers using the `customizations.coder`
+block in their `devcontainer.json` file. Available options include:
+
+- `ignore` — Hide a dev container from Coder completely
+- `autoStart` — Control whether the container starts automatically (requires
+  `CODER_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, see
+[Customizing dev containers](../../../user-guides/devcontainers/customizing-dev-containers.md).
+
+## Complete Template Example
+
+Here's a simplified template example that uses Dev Containers with manual
+configuration:
+
+```terraform
+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 must
+manually start them. To have them start automatically, enable autostart:
+
+```terraform
+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 workspace
+  initialization
+- The `coder_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
+> 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.
+
+## Next Steps
+
+- [Dev Containers Integration](../../../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)