coder · EdwardAngert · Jun 23, 2025 · Jun 24, 2025 · Jun 25, 2025 · Jun 25, 2025
diff --git a/docs/admin/templates/extending-templates/advanced-dev-containers.md b/docs/admin/templates/extending-templates/advanced-dev-containers.md
@@ -0,0 +1,110 @@
+# Advanced Dev Container Configuration
+
+This page extends the [devcontainers documentation](./devcontainers.md) with patterns for multiple dev containers,
+user-controlled startup, repository selection, and infrastructure tuning.
+
+## Run Multiple Dev Containers
+
+Run independent dev containers in the same workspace so each component appears as its own agent.
+
+In this example, there are two: `frontend` and `backend`:
+
+```terraform
+# Clone each repo
+module "git-clone-frontend" {
+  count    = data.coder_workspace.me.start_count
+  source   = "dev.registry.coder.com/modules/git-clone/coder"
+
+  agent_id = coder_agent.main.id
+  url      = "https://github.com/your-org/frontend.git"
+  base_dir = "/home/coder/frontend"
+}
+
+module "git-clone-backend" {
+  count    = data.coder_workspace.me.start_count
+  source   = "dev.registry.coder.com/modules/git-clone/coder"
+
+  agent_id = coder_agent.main.id
+  url      = "https://github.com/your-org/backend.git"
+  base_dir = "/home/coder/backend"
+}
+
+# Dev container resources
+resource "coder_devcontainer" "frontend" {
+  count            = data.coder_workspace.me.start_count
+  agent_id         = coder_agent.main.id
+  workspace_folder = "/home/coder/frontend/${module.git-clone-frontend[0].folder_name}"
+}
+
+resource "coder_devcontainer" "backend" {
+  count            = data.coder_workspace.me.start_count
+  agent_id         = coder_agent.main.id
+  workspace_folder = "/home/coder/backend/${module.git-clone-backend[0].folder_name}"
-  workspace_folder = "/home/coder/backend/${module.git-clone-backend[0].folder_name}"
+  workspace_folder = module.git-clone-backend[0].repo_dir
-  workspace_folder = "/home/coder/backend/${module.git-clone-backend[0].folder_name}"
+  workspace_folder = module.git-clone-backend[0].repo_dir
+}
+```
+
+Each dev container appears as a separate agent, so developers can connect to any
+component in the workspace.
+
+## Conditional Startup
+
+Use `coder_parameter` booleans to let workspace creators choose which dev containers start automatically,
+reducing resource usage for unneeded components:
+
+```terraform
+data "coder_parameter" "enable_frontend" {
+  type        = "bool"
+  name        = "Enable frontend container"
-data "coder_parameter" "enable_frontend" {
-  type        = "bool"
-  name        = "Enable frontend container"
+data "coder_parameter" "autostart_frontend" {
+  type        = "bool"
+  name        = "Autostart frontend container"
-data "coder_parameter" "enable_frontend" {
-  type        = "bool"
-  name        = "Enable frontend container"
+data "coder_parameter" "autostart_frontend" {
+  type        = "bool"
+  name        = "Autostart frontend container"
+  default     = true
+  mutable     = true
+  order       = 3
+}
+
+resource "coder_devcontainer" "frontend" {
+  count            = data.coder_parameter.enable_frontend.value ? data.coder_workspace.me.start_count : 0
+  agent_id         = coder_agent.main.id
+  workspace_folder = "/home/coder/frontend/${module.git-clone-frontend[0].folder_name}"
+}
+```
+
+## Repository-selection Patterns
+
+Prompt users to pick a repository or team at workspace creation time and clone the selected repo(s) automatically into the workspace:
+
+1. Add a parameter to the template:
+
+   ```terraform
+   data "coder_parameter" "project" {
+     name        = "project"
+     display_name = "Choose a project"
+     type        = "string"
+     default     = "https://github.com/coder/coder.git"
+
+     option {
+        name = "coder/coder"
+        value = "https://github.com/coder/coder.git"
+     }
+     option {
+       name = "Dev Container template"
+       value = "https://github.com/devcontainers/template-starter.git"
+     }
+   }
+   ```
+
+1. Change the `git-clone` module to accept the `value` as the `url`:
+
+    ```terraform
+    module "git-clone" {
+     count    = data.coder_workspace.me.start_count
+     source   = "dev.registry.coder.com/modules/git-clone/coder"
+     agent_id = coder_agent.main.id
+     url      = data.coder_parameter.project.value
+     base_dir = "/home/coder"
+    }
+    ```
+
+## Troubleshooting
+
+1. Run `docker ps` inside the workspace to ensure Docker is available.
+1. Check `/tmp/coder-agent.log` for agent logs.
+1. Verify that the workspace image includes Node/npm.
diff --git a/docs/admin/templates/extending-templates/dev-containers-envbuilder.md b/docs/admin/templates/extending-templates/dev-containers-envbuilder.md
@@ -0,0 +1,57 @@
+# Choose an Approach To Dev Containers
+
+Coder supports two independent ways to run Dev Containers inside a workspace.
+
+Both implement the [Dev Container specification](https://containers.dev/), but they differ in how the container is built,
+who controls it, and which runtime requirements exist.
+
+Use this page to decide which path fits your project or platform needs.
+
+## Options at a Glance
+
+| Capability / Trait                       | Dev Containers integration (CLI-based)   | Envbuilder Dev Containers                 |
+|------------------------------------------|------------------------------------------|-------------------------------------------|
+| Build engine                             | `@devcontainers/cli` + Docker            | Envbuilder transforms the workspace image |
+| Runs separate Docker container           | Yes (parent workspace + child container) | No (modifies the parent container)        |
+| Multiple Dev Containers per workspace    | Yes                                      | No                                        |
+| Rebuild when `devcontainer.json` changes | Yes (auto-prompt)                        | Limited (requires full workspace rebuild) |
+| Docker required in workspace             | Yes                                      | No (works in restricted envs)             |
+| Templates                                | Standard `devcontainer.json`             | Terraform + Envbuilder blocks             |
+| Suitable for CI / AI agents              | Yes. Deterministic, composable           | Less ideal. No isolated container         |
+
+## How To Migrate From Envbuilder to the Dev Containers Integration
+
+1. Ensure the workspace image can run Docker and has sufficient resources:
+
+   ```shell
+   docker ps
+   ```
+
+1. Remove any Envbuilder blocks that reference `coder_dev_envbuilder` from the template.
+1. Add (or keep) a standard `.devcontainer/` folder with `devcontainer.json` in the repository.
+1. Follow the [dev containers documentation](./devcontainers.md) for the full list of steps and options.
+
+   At minimum, add the `devcontainers-cli` module and `coder_devcontainer` resource:
+
+   ```terraform
+   module "devcontainers_cli" {
-   module "devcontainers_cli" {
+   module "devcontainers-cli" {
-   module "devcontainers_cli" {
+   module "devcontainers-cli" {
+     source   = "dev.registry.coder.com/modules/devcontainers-cli/coder"
+     agent_id = coder_agent.main.id
+   }
+   resource "coder_devcontainer" "project" { # `project` in this example is how users will connect to the dev container: `ssh://project.<workspace>.me.coder`
+     count            = data.coder_workspace.me.start_count
+     agent_id         = coder_agent.main.id
+     workspace_folder = "/home/coder/project"
+   }
+   ```
+
+1. Start a new workspace.
+   Coder detects and launches the dev container automatically.
+1. Verify ports, SSH, and rebuild prompts function as expected.
+
+## Related Reading
+
+- [Dev Containers Integration](./index.md)
+- [Troubleshooting Dev Containers](../../../user-guides/devcontainers/troubleshooting-dev-containers.md)
+- [Envbuilder on GitHub](https://github.com/coder/envbuilder)
+- [Dev Container specification](https://containers.dev/)