From 081e820c43d9786287c85cf942024aa1adf88695 Mon Sep 17 00:00:00 2001
From: Katie Geer <katie@zed.dev>
Date: Wed, 17 Dec 2025 08:28:32 -0800
Subject: [PATCH] docs: Dev container (#44498)

Release Notes:

- N/A

---------

Co-authored-by: Danilo Leal <67129314+danilo-leal@users.noreply.github.com>
Co-authored-by: Danilo Leal <daniloleal09@gmail.com>
---
 docs/src/SUMMARY.md        |  1 +
 docs/src/dev-containers.md | 50 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 51 insertions(+)
 create mode 100644 docs/src/dev-containers.md

diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index d6dd7a0aef9737fb095e87705e813f87fd0ed683..d64aed93de16e8806b5e384452816c5d62ed621d 100644
--- a/docs/src/SUMMARY.md
+++ b/docs/src/SUMMARY.md
@@ -46,6 +46,7 @@
 - [Tasks](./tasks.md)
 - [Tab Switcher](./tab-switcher.md)
 - [Remote Development](./remote-development.md)
+- [Dev Containers](./dev-containers.md)
 - [Environment Variables](./environment.md)
 - [REPL](./repl.md)
 
diff --git a/docs/src/dev-containers.md b/docs/src/dev-containers.md
new file mode 100644
index 0000000000000000000000000000000000000000..c87b204ee9cded48edb95752dd234fa55df71338
--- /dev/null
+++ b/docs/src/dev-containers.md
@@ -0,0 +1,50 @@
+# Dev Containers
+
+Dev Containers provide a consistent, reproducible development environment by defining your project's dependencies, tools, and settings in a container configuration.
+
+If your repository includes a `.devcontainer/devcontainer.json` file, Zed can open a project inside a development container.
+
+## Requirements
+
+- Docker must be installed and available in your `PATH`. Zed requires the `docker` command to be present. If you use Podman, you can alias it to `docker` (e.g., `alias docker=podman`).
+- Your project must contain a `.devcontainer/devcontainer.json` directory/file.
+
+## Using Dev Containers in Zed
+
+### Automatic prompt
+
+When you open a project that contains the `.devcontainer/devcontainer.json` directory/file, Zed will display a prompt asking whether to open the project inside the dev container. Choosing "Open in Container" will:
+
+1. Build the dev container image (if needed).
+2. Launch the container.
+3. Reopen the project connected to the container environment.
+
+### Manual open
+
+If you dismiss the prompt or want to reopen the project inside a container later, you can use Zed's command palette to run the "Project: Open Remote" command and select the option to open the project in a dev container.
+Alternatively, you can reach for the Remote Projects modal (through the {#kb projects::OpenRemote} binding) and choose the "Connect Dev Container" option.
+
+## Editing the dev container configuration
+
+If you modify `.devcontainer/devcontainer.json`, Zed does not currently rebuild or reload the container automatically. After changing configuration:
+
+- Stop or kill the existing container manually (e.g., via `docker kill <container>`).
+- Reopen the project in the container.
+
+## Working in a Dev Container
+
+Once connected, Zed operates inside the container environment for tasks, terminals, and language servers.
+Files are linked from your workspace into the container according to the dev container specification.
+
+## Known Limitations
+
+> **Note:** This feature is still in development.
+
+- **Extensions:** Zed does not yet manage extensions separately for container environments. The host's extensions are used as-is.
+- **Port forwarding:** Only the `appPort` field is supported. `forwardPorts` and other advanced port-forwarding features are not implemented.
+- **Configuration changes:** Updates to `devcontainer.json` do not trigger automatic rebuilds or reloads; containers must be manually restarted.
+
+## See also
+
+- [Remote Development](./remote-development.md) for connecting to remote servers over SSH.
+- [Tasks](./tasks.md) for running commands in the integrated terminal.