update user-guide

EdwardAngert · EdwardAngert · commit 0e8383e861a1 · 2025-07-16T20:16:43.000Z
diff --git a/docs/user-guides/devcontainers/index.md b/docs/user-guides/devcontainers/index.md
@@ -1,25 +1,14 @@
 # Dev Containers Integration
 
-> [!NOTE]
->
-> The Coder dev containers integration is an [early access](../../install/releases/feature-stages.md) feature.
->
-> While functional for testing and feedback, it may change significantly before general availability.
-
-The dev containers integration is an early access feature that enables seamless
-creation and management of dev containers in Coder workspaces. This feature
-leverages the [`@devcontainers/cli`](https://github.com/devcontainers/cli) and
-[Docker](https://www.docker.com) to provide a streamlined development
-experience.
-
-This implementation is different from the existing
-[Envbuilder-based dev containers](../../admin/templates/managing-templates/devcontainers/index.md)
-offering.
+The dev containers integration enables seamless creation and management of dev containers in Coder workspaces.
+
+This feature leverages the [`@devcontainers/cli`](https://github.com/devcontainers/cli) and [Docker](https://www.docker.com)
+to provide a streamlined development experience.
 
 ## Prerequisites
 
-- Coder version 2.22.0 or later
-- Coder CLI version 2.22.0 or later
+- Coder version 2.24.0 or later
+- Coder CLI version 2.24.0 or later
 - A template with:
   - Dev containers integration enabled
   - A Docker-compatible workspace image
@@ -37,63 +26,31 @@ which allows for extensive customization of your development setup.
 
 When a workspace with the dev containers integration starts:
 
-1. The workspace initializes the Docker environment.
-1. The integration detects repositories with a `.devcontainer` directory or a
-   `devcontainer.json` file.
-1. The integration builds and starts the dev container based on the
-   configuration.
+1. The integration detects repositories with a `.devcontainer` directory or a `devcontainer.json` file.
+1. The integration starts the dev container based on the template and `devcontainer.json`.
 1. Your workspace automatically detects the running dev container.
 
 ## Features
 
-### Available Now
-
-- Automatic dev container detection from repositories
-- Seamless dev container startup during workspace initialization
-- Integrated IDE experience in dev containers with VS Code
-- Direct service access in dev containers
-- Limited SSH access to dev containers
-
-### Coming Soon
-
-- Dev container change detection
-- On-demand dev container recreation
-- Support for automatic port forwarding inside the container
-- Full native SSH support to dev containers
-
-## Limitations during Early Access
+### Detection & Lifecycle
 
-During the early access phase, the dev containers integration has the following
-limitations:
+- Automatic dev container detection from repositories.
+- Change detection with rebuild prompts.
+- Rebuild containers with one click from the Coder dashboard.
 
-- Changes to the `devcontainer.json` file require manual container recreation
-- Automatic port forwarding only works for ports specified in `appPort`
-- SSH access requires using the `--container` flag
-- Some devcontainer features may not work as expected
+### Connectivity
 
-These limitations will be addressed in future updates as the feature matures.
+- Full SSH access directly into dev containers (`coder ssh <agent>.<workspace>.me.coder`).
+- Automatic port forwarding.
 
-## Comparison with Envbuilder-based Dev Containers
+## Known Limitations
 
-| Feature        | Dev Containers (Early Access)          | Envbuilder Dev Containers                    |
-|----------------|----------------------------------------|----------------------------------------------|
-| Implementation | Direct `@devcontainers/cli` and Docker | Coder's Envbuilder                           |
-| Target users   | Individual developers                  | Platform teams and administrators            |
-| Configuration  | Standard `devcontainer.json`           | Terraform templates with Envbuilder          |
-| Management     | User-controlled                        | Admin-controlled                             |
-| Requirements   | Docker access in workspace             | Compatible with more restricted environments |
+Currently, dev containers are not compatible with [prebuilt workspaces](../../admin/templates/extending-templates/prebuilt-workspaces.md).
 
-Choose the appropriate solution based on your team's needs and infrastructure
-constraints. For additional details on Envbuilder's dev container support, see
-the
-[Envbuilder devcontainer spec support documentation](https://github.com/coder/envbuilder/blob/main/docs/devcontainer-spec-support.md).
+If your template allows for prebuilt workspaces, do not select a prebuilt workspace if you plan to use a dev container.
 
 ## Next Steps
 
-- Explore the [dev container specification](https://containers.dev/) to learn
-  more about advanced configuration options
-- Read about [dev container features](https://containers.dev/features) to
-  enhance your development environment
-- Check the
-  [VS Code dev containers documentation](https://code.visualstudio.com/docs/devcontainers/containers)
-  for IDE-specific features
+- [Dev Container specification](https://containers.dev/)
+- [VS Code dev containers documentation](https://code.visualstudio.com/docs/devcontainers/containers)
+- [Choose an approach to Dev Containers](../../admin/templates/extending-templates/dev-containers-envbuilder.md)
