coder · EdwardAngert · Jul 15, 2025 · Jul 16, 2025 · Jul 16, 2025 · Jul 16, 2025
diff --git a/docs/about/contributing/backend.md b/docs/about/contributing/backend.md
@@ -49,7 +49,7 @@ Coder's backend is built using a collection of robust, modern Go libraries and i
 
 The Coder backend is organized into multiple packages and directories, each with a specific purpose. Here's a high-level overview of the most important ones:
 
-* [agent](https://github.com/coder/coder/tree/main/agent): core logic of a workspace agent, supports DevContainers, remote SSH, startup/shutdown script execution. Protobuf definitions for DRPC communication with `coderd` are kept in [proto](https://github.com/coder/coder/tree/main/agent/proto).
+* [agent](https://github.com/coder/coder/tree/main/agent): core logic of a workspace agent, supports dev containers, remote SSH, startup/shutdown script execution. Protobuf definitions for DRPC communication with `coderd` are kept in [proto](https://github.com/coder/coder/tree/main/agent/proto).
 * [cli](https://github.com/coder/coder/tree/main/cli): CLI interface for `coder` command built on [coder/serpent](https://github.com/coder/serpent). Input controls are defined in [cliui](https://github.com/coder/coder/tree/docs-backend-contrib-guide/cli/cliui), and [testdata](https://github.com/coder/coder/tree/docs-backend-contrib-guide/cli/testdata) contains golden files for common CLI calls
 * [cmd](https://github.com/coder/coder/tree/main/cmd): entry points for CLI and services, including `coderd`
 * [coderd](https://github.com/coder/coder/tree/main/coderd): the main API server implementation with [chi](https://github.com/go-chi/chi) endpoints
@@ -72,7 +72,7 @@ The Coder backend is organized into multiple packages and directories, each with
   * [dbpurge](https://github.com/coder/coder/tree/main/coderd/database/dbpurge): simple wrapper for periodic database cleanup operations
   * [migrations](https://github.com/coder/coder/tree/main/coderd/database/migrations): an ordered list of up/down database migrations, use `./create_migration.sh my_migration_name` to modify the database schema
   * [pubsub](https://github.com/coder/coder/tree/main/coderd/database/pubsub): PubSub implementation using PostgreSQL and in-memory drop-in replacement
-  * [queries](https://github.com/coder/coder/tree/main/coderd/database/queries): contains SQL files with queries, `sqlc` compiles them to [Go functions](https://github.com/coder/coder/blob/docs-backend-contrib-guide/coderd/database/queries.sql.go)
+  * [queries](https://github.com/coder/coder/tree/main/coderd/database/queries): contains SQL files with queries, `sqlc` compiles them to [Go functions](https://github.com/coder/coder/tree/main/coderd/database/queries.sql.go)
   * [sqlc.yaml](https://github.com/coder/coder/tree/main/coderd/database/sqlc.yaml): defines mappings between SQL types and custom Go structures
 * [codersdk](https://github.com/coder/coder/tree/main/codersdk): user-facing API entities used by CLI and site to communicate with `coderd` endpoints
 * [dogfood](https://github.com/coder/coder/tree/main/dogfood): Terraform definition of the dogfood cluster deployment

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,100 @@
+# Advanced Dev Container Configuration
+
+This page extends the [dev containers 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: repositories called `frontend` and `backend`:
+
+```terraform
+# Clone each repo
+module "git-clone-frontend" {
+  count  = data.coder_workspace.me.start_count
+  source  = "registry.coder.com/modules/git-clone/coder"
+
+  agent_id  = coder_agent.main.id
+  url  = "https://github.com/your-org/frontend.git"
+}
+
+module "git-clone-backend" {
+  count  = data.coder_workspace.me.start_count
+  source  = "registry.coder.com/modules/git-clone/coder"
+
+  agent_id  = coder_agent.main.id
+  url  = "https://github.com/your-org/backend.git"
+}
+
+# Dev container resources
+resource "coder_devcontainer" "frontend" {
+  count  = data.coder_workspace.me.start_count
+  agent_id  = coder_agent.main.id
+  workspace_folder  = module.git-clone-frontend[0].repo_dir
+}
+
+resource "coder_devcontainer" "backend" {
+  count  = data.coder_workspace.me.start_count
+  agent_id  = coder_agent.main.id
+  workspace_folder  = module.git-clone-backend[0].repo_dir
+}
+```
+
+Each dev container appears as a separate agent, so developers can connect to each separately.
+
+## 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" "autostart_frontend" {
+  type  = "bool"
+  name  = "Autostart frontend container"
+  default  = true
+  mutable  = true
+  order  = 3
+}
+
+resource "coder_devcontainer" "frontend" {
+  count  = data.coder_parameter.autostart_frontend.value ? data.coder_workspace.me.start_count : 0
+  agent_id  = coder_agent.main.id
+  workspace_folder  = module.git-clone-frontend[0].repo_dir
+}
+```
+
+## 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  = "terraform-provider-coder"
+       value  = "https://github.com/coder/terraform-provider-coder.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  = "registry.coder.com/modules/git-clone/coder"
+     agent_id  = coder_agent.main.id
+     url  = data.coder_parameter.project.value
+    }
+    ```
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,23 @@
+# 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                 | Envbuilder                                |
+|------------------------------------------|--------------------------------------------|-------------------------------------------|
+| How it's built                           | `@devcontainers/cli` and Docker            | Envbuilder transforms the workspace image |
+| Docker-in-Docker?                        | Yes (parent workspace and child container) | No (modifies the parent container)        |
+| Multiple dev containers per workspace    | Yes                                        | No                                        |
+| Rebuild when `devcontainer.json` changes | Yes - user-initiated                       | Requires full workspace restart           |
+
+## Related Reading
+
+- [Dev Containers integration](./devcontainers.md)
+- [Dev Containers specification](https://containers.dev/)
+- [Envbuilder on GitHub](https://github.com/coder/envbuilder)