|
| 1 | +#Choose an approach to Dev Containers in Coder |
| 2 | + |
| 3 | +Coder supports two independent ways to run Dev Containers inside a workspace. |
| 4 | + |
| 5 | +Both implement the[Dev Container specification](https://containers.dev/), but they differ in how the container is built, |
| 6 | +who controls it, and which runtime requirements exist. |
| 7 | + |
| 8 | +Use this page to decide which path fits your project or platform needs. |
| 9 | + |
| 10 | +##Options at a glance |
| 11 | + |
| 12 | +| Capability / Trait| Dev Containers integration (CLI-based)| Envbuilder Dev Containers| |
| 13 | +|------------------------------------------|------------------------------------------|-------------------------------------------| |
| 14 | +| Build engine|`@devcontainers/cli` + Docker| Envbuilder transforms the workspace image| |
| 15 | +| Runs separate Docker container| Yes (parent workspace + child container)| No (modifies the parent container)| |
| 16 | +| Multiple Dev Containers per workspace| Yes| No| |
| 17 | +| Rebuild when`devcontainer.json` changes| Yes (auto-prompt)| Limited (requires full workspace rebuild)| |
| 18 | +| Docker required in workspace| Yes| No (works in restricted envs)| |
| 19 | +| Admin vs. developer control| Developer decides per repo| Platform admin manages via template| |
| 20 | +| Templates| Standard`devcontainer.json`| Terraform + Envbuilder blocks| |
| 21 | +| Suitable for CI / AI agents| Yes. Deterministic, composable| Less ideal. No isolated container| |
| 22 | + |
| 23 | +##When to choose the Dev Containers integration |
| 24 | + |
| 25 | +Choose the new integration if: |
| 26 | + |
| 27 | +- Your workspace image can run Docker (DinD, Sysbox, or a mounted Docker socket). |
| 28 | +- You need multiple Dev Containers (like`frontend`,`backend`,`db`) in a single workspace. |
| 29 | +- Developers should own their environment and rebuild on demand. |
| 30 | +- You rely on features such as automatic port forwarding, full SSH into containers, or change-detection prompts. |
| 31 | + |
| 32 | +[Dev Container integration](./devcontainers.md) documentation. |
| 33 | + |
| 34 | +##When to choose Envbuilder |
| 35 | + |
| 36 | +Envbuilder remains a solid choice when: |
| 37 | + |
| 38 | +- Docker isn’t available or allowed inside the workspace image. |
| 39 | +- The platform team wants tight control over container contents via Terraform. |
| 40 | +- A single layered environment is sufficient (no need for separate sub-containers). |
| 41 | +- You already have Envbuilder templates in production and they meet current needs. |
| 42 | + |
| 43 | +[Envbuilder Dev Container](../managing-templates/devcontainers/add-devcontainer.md#envbuilder-terraform-provider) documentation. |
| 44 | + |
| 45 | +##How to migrate from Envbuilder to the Dev Containers integration |
| 46 | + |
| 47 | +1. Ensure the workspace image can run Docker and has sufficient resources: |
| 48 | + |
| 49 | +```shell |
| 50 | + docker ps |
| 51 | +``` |
| 52 | + |
| 53 | +1. Remove any Envbuilder blocks that reference`coder_dev_envbuilder` from the template. |
| 54 | +1. Add (or keep) a standard`.devcontainer/` folder with`devcontainer.json` in the repository. |
| 55 | +1. Add the`devcontainers-cli` module: |
| 56 | + |
| 57 | +```terraform |
| 58 | + module "devcontainers_cli" { |
| 59 | + source = "dev.registry.coder.com/modules/devcontainers-cli/coder" |
| 60 | + agent_id = coder_agent.main.id |
| 61 | + } |
| 62 | +``` |
| 63 | + |
| 64 | +1. Start a new workspace. |
| 65 | + Coder detects and launches the dev container automatically. |
| 66 | +1. Verify ports, SSH, and rebuild prompts function as expected. |
| 67 | + |
| 68 | +##Related reading |
| 69 | + |
| 70 | +-[Dev Containers Integration](./index.md) |
| 71 | +-[Troubleshooting Dev Containers](./troubleshooting-dev-containers.md) |
| 72 | +-[Envbuilder documentation](https://github.com/coder/envbuilder) |
| 73 | +-[Dev Container specification](https://containers.dev/) |