Development containers changeddevcontainer
Nearest release: v2.1.273, published 3 hours before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 15 Sep 2026 21:25 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 20 Oct 2026 18:37 UTC.
Upstream edited
Recorded here
Lines+53added
Lines−59removed
From line
6
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits7to this page, all time
The whole hunk
from line 6, old and new numbered
/
from line 6
66
77This page covers [installing Claude Code in a dev container](#add-claude-code-to-your-dev-container), then a set of self-contained configuration topics: persisting authentication across rebuilds, enforcing organization policy, restricting network egress, and running without permission prompts. Read the ones that match your setup.
88
9<Warning>
10 While the dev container provides substantial protections, no system is completely immune to all attacks.
11 When executed with `--dangerously-skip-permissions`, dev containers do not prevent a malicious project from exfiltrating anything accessible inside the container, including the Claude Code credentials stored in [`~/.claude`](/docs/en/claude-directory).
12 Only use dev containers when developing with trusted repositories, and monitor Claude's activities.
13 Avoid mounting host secrets such as `~/.ssh` or cloud credential files into the container; prefer repository-scoped or short-lived tokens.
14</Warning>
9> [!WARNING]
10>
11> While the dev container provides substantial protections, no system is completely immune to all attacks.
12> When executed with `--dangerously-skip-permissions`, dev containers do not prevent a malicious project from exfiltrating anything accessible inside the container, including the Claude Code credentials stored in [`~/.claude`](/docs/en/claude-directory).
13> Only use dev containers when developing with trusted repositories, and monitor Claude's activities.
14> Avoid mounting host secrets such as `~/.ssh` or cloud credential files into the container; prefer repository-scoped or short-lived tokens.
1515
16<Accordion title="How dev containers work with your editor">
17 <img src="https://mintcdn.com/claude-code/YvJyjZfd9yMihr0i/images/devcontainer-architecture.svg?fit=max&auto=format&n=YvJyjZfd9yMihr0i&q=85&s=9017b1d16a446c6cc37ba562f35b9aae" className="dark:hidden" alt="Diagram showing an editor on the host connecting to a Docker dev container. Claude Code, the terminal, and build tools run inside the container. The host repository is bind-mounted into the container as the workspace." width="640" height="300" data-path="images/devcontainer-architecture.svg" />
16> **How dev containers work with your editor**
17>
18> 
19>
20> A dev container runs as a Docker container, either on your machine or on a cloud host such as GitHub Codespaces. An editor that supports the Dev Containers spec, such as VS Code, GitHub Codespaces, a JetBrains IDE, or Cursor, connects to that container: you browse and edit files in the editor as usual, but the integrated terminal, language servers, and build tools all run inside the container rather than on your host. Editors without dev container support, such as plain Vim, are not part of this workflow.
21>
22> Claude Code runs inside the container, so it sees the same files, dependencies, and tools as the rest of your project's toolchain. In VS Code you can use either the [Claude Code extension panel](/docs/en/vs-code) or run `claude` in the integrated terminal; both run inside the container and share the same `~/.claude` configuration.
1823
19 <img src="https://mintcdn.com/claude-code/_xqph1dUOslCOwsj/images/devcontainer-architecture-dark.svg?fit=max&auto=format&n=_xqph1dUOslCOwsj&q=85&s=a0a340b1f2afc6a590696102c8acaaca" className="hidden dark:block" alt="Diagram showing an editor on the host connecting to a Docker dev container. Claude Code, the terminal, and build tools run inside the container. The host repository is bind-mounted into the container as the workspace." width="640" height="300" data-path="images/devcontainer-architecture-dark.svg" />
20
21 A dev container runs as a Docker container, either on your machine or on a cloud host such as GitHub Codespaces. An editor that supports the Dev Containers spec, such as VS Code, GitHub Codespaces, a JetBrains IDE, or Cursor, connects to that container: you browse and edit files in the editor as usual, but the integrated terminal, language servers, and build tools all run inside the container rather than on your host. Editors without dev container support, such as plain Vim, are not part of this workflow.
22
23 Claude Code runs inside the container, so it sees the same files, dependencies, and tools as the rest of your project's toolchain. In VS Code you can use either the [Claude Code extension panel](/docs/en/vs-code) or run `claude` in the integrated terminal; both run inside the container and share the same `~/.claude` configuration.
24</Accordion>
25
2624## Add Claude Code to your dev container
2725
2826Claude Code installs into any dev container through the [Claude Code Dev Container Feature](https://github.com/anthropics/devcontainer-features/tree/main/src/claude-code).
from line 29
3129
3230When you open the container in VS Code or Codespaces, the feature also adds the Claude Code VS Code extension; other editors ignore that part.
3331
34<Tip>
35 New to dev containers? The [VS Code Dev Containers tutorial](https://code.visualstudio.com/docs/devcontainers/tutorial) walks through installing Docker, the extension, and opening your first container. For a fuller hardened example with a firewall and persistent volumes, see [Try the reference container](#try-the-reference-container).
36</Tip>
32> [!TIP]
33>
34> New to dev containers? The [VS Code Dev Containers tutorial](https://code.visualstudio.com/docs/devcontainers/tutorial) walks through installing Docker, the extension, and opening your first container. For a fuller hardened example with a firewall and persistent volumes, see [Try the reference container](#try-the-reference-container).
3735
38<Steps>
39 <Step title="Create or update devcontainer.json">
40 Save the following as `.devcontainer/devcontainer.json` in your repository, or add the `features` block to your existing file.
36**1. Create or update devcontainer.json**
4137
42 The version tag at the end, such as `:1.0`, pins the feature's install script, not the Claude Code release. The feature installs the latest Claude Code, and Claude Code auto-updates itself inside the container by default.
38Save the following as `.devcontainer/devcontainer.json` in your repository, or add the `features` block to your existing file.
4339
44 To pin the CLI version or disable auto-update, see [Enforce organization policy](#enforce-organization-policy).
40The version tag at the end, such as `:1.0`, pins the feature's install script, not the Claude Code release. The feature installs the latest Claude Code, and Claude Code auto-updates itself inside the container by default.
4541
46 ```json .devcontainer/devcontainer.json theme={null}
47 {
48 "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
49 "features": {
50 "ghcr.io/anthropics/devcontainer-features/claude-code:1.0": {}
51 }
52 }
53 ```
42To pin the CLI version or disable auto-update, see [Enforce organization policy](#enforce-organization-policy).
5443
55 Replace the `image` line with your project's base image or remove it if your existing file uses a Dockerfile.
44```json .devcontainer/devcontainer.json theme={null}
45{
46 "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
47 "features": {
48 "ghcr.io/anthropics/devcontainer-features/claude-code:1.0": {}
49 }
50}
51```
5652
57 The Claude Code feature installs Node.js itself when the base image doesn't provide it. If that install fails and the build stops with `Failed to install Node.js and npm`, add `"ghcr.io/devcontainers/features/node:1": {}` to the `features` block above the Claude Code feature and rebuild.
58 </Step>
53Replace the `image` line with your project's base image or remove it if your existing file uses a Dockerfile.
5954
60 <Step title="Rebuild the container">
61 Open the VS Code Command Palette with `Cmd+Shift+P` on Mac or `Ctrl+Shift+P` on Windows and Linux, and run **Dev Containers: Rebuild Container**.
55The Claude Code feature installs Node.js itself when the base image doesn't provide it. If that install fails and the build stops with `Failed to install Node.js and npm`, add `"ghcr.io/devcontainers/features/node:1": {}` to the `features` block above the Claude Code feature and rebuild.
6256
63 For other tools, follow that tool's rebuild action: see [rebuilding in GitHub Codespaces](https://docs.github.com/en/codespaces/developing-in-a-codespace/rebuilding-the-container-in-a-codespace), the [Dev Containers CLI](https://github.com/devcontainers/cli), or your IDE's dev container documentation.
64 </Step>
57**2. Rebuild the container**
6558
66 <Step title="Sign in to Claude Code">
67 Open a terminal in the rebuilt container and run `claude`, then follow the authentication prompt.
68 </Step>
69</Steps>
59Open the VS Code Command Palette with `Cmd+Shift+P` on Mac or `Ctrl+Shift+P` on Windows and Linux, and run **Dev Containers: Rebuild Container**.
7060
61For other tools, follow that tool's rebuild action: see [rebuilding in GitHub Codespaces](https://docs.github.com/en/codespaces/developing-in-a-codespace/rebuilding-the-container-in-a-codespace), the [Dev Containers CLI](https://github.com/devcontainers/cli), or your IDE's dev container documentation.
62
63**3. Sign in to Claude Code**
64
65Open a terminal in the rebuilt container and run `claude`, then follow the authentication prompt.
66
7167What you see at the authentication prompt depends on your provider:
7268
7369* **Anthropic**: sign in through a browser with your Claude or Anthropic Console account
from line 73
7773
7874See [Choose your API provider](/docs/en/admin-setup#choose-your-api-provider) to decide which path fits your organization.
7975
80<Note>
81 If the browser sign-in completes but the callback never reaches the container, copy the code shown in the browser and paste it at the `Paste code here if prompted` prompt in the terminal. This can happen when the editor's port forwarding doesn't route the localhost callback.
82</Note>
76> [!NOTE]
77>
78> If the browser sign-in completes but the callback never reaches the container, copy the code shown in the browser and paste it at the `Paste code here if prompted` prompt in the terminal. This can happen when the editor's port forwarding doesn't route the localhost callback.
8379
8480## Persist authentication and settings across rebuilds
8581
from line 148
152148
153149The [`anthropics/claude-code`](https://github.com/anthropics/claude-code/tree/main/.devcontainer) repository includes an example dev container that combines the CLI, the egress firewall, persistent volumes, and a Zsh-based shell. It is provided as a working example rather than a maintained base image; use it to see how the pieces fit together before applying them to your own configuration.
154150
155<Steps>
156 <Step title="Install prerequisites">
157 Install VS Code and the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
158 </Step>
151**1. Install prerequisites**
159152
160 <Step title="Clone the reference">
161 Clone the [Claude Code repository](https://github.com/anthropics/claude-code) and open it in VS Code.
162 </Step>
153Install VS Code and the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
163154
164 <Step title="Reopen in container">
165 When prompted, click **Reopen in Container**, or run **Dev Containers: Reopen in Container** from the Command Palette.
166 </Step>
155**2. Clone the reference**
167156
168 <Step title="Start Claude Code">
169 Once the container finishes building, open a terminal with `` Ctrl+` `` and run `claude` to sign in and start your first session.
170 </Step>
171</Steps>
157Clone the [Claude Code repository](https://github.com/anthropics/claude-code) and open it in VS Code.
158
159**3. Reopen in container**
160
161When prompted, click **Reopen in Container**, or run **Dev Containers: Reopen in Container** from the Command Palette.
162
163**4. Start Claude Code**
164
165Once the container finishes building, open a terminal with `` Ctrl+` `` and run `claude` to sign in and start your first session.
172166
173167To use this configuration with your own project, copy the `.devcontainer/` directory into your repository and adjust the Dockerfile for your toolchain, or return to [Add Claude Code to your dev container](#add-claude-code-to-your-dev-container) to add only the feature to a setup you already have.
174168
No line in this hunk matches that.