Claude Code guide in three levels, Beginner to Advanced: hands-on lessons with checked exercises, every volatile fact cited to its source. Independent community guide.
Dev containers
Advanced · Elective · about 20 minutes, plus run time · Needs: Put bounds on autonomous runs · Verified against Claude Code v2.1.292 (stable) on 2026-10-15
Goal
By the end of this Elective you can run Claude Code inside a dev container, keep your sign-in across a rebuild, and let it work unattended behind a firewall.
You need
- For the Worked example: your copy of the practice template on GitHub, and GitHub Codespaces on your account. Nothing to install on your computer: the copy's dev container installs Claude Code.
- For Your turn: one of your own repositories with no
.devcontainer/folder, with its.practice/folder set up as the Intermediate index describes. - Also for Your turn: Docker, VS Code with the Dev Containers extension (System requirements), and
jq, on macOS, Linux or WSL 2. Without Docker, do the Worked example and the Check's self-check. - Usage: light. A codespace also uses your GitHub account's Codespaces compute while it runs, and storage while it exists (GitHub Codespaces billing).
The idea
A dev container is a Docker container your editor connects to, on your computer or a cloud host such as GitHub Codespaces. With Claude Code in it, Claude's commands run in the container, while its edits land in your repository. Unlike the Bash sandbox from Intermediate lesson 4, which wraps only shell commands, it holds the whole Claude Code process: file tools, MCP servers and hooks too (Compare sandboxing approaches).
Three pieces, each adding to the one before:
- The Claude Code Dev Container Feature adds the CLI to any dev container (Add Claude Code to your dev container).
- A named volume at
~/.claude, plusCLAUDE_CONFIG_DIRset to that path, keeps your sign-in when a rebuild discards the home folder (Persist authentication and settings across rebuilds). - The reference container adds a non-root user and a firewall that limits outbound traffic to the destinations its script allows. The docs support it for unattended
--dangerously-skip-permissionsruns, which skip permission prompts (bypass mode); the CLI refuses the flag as root (Run without permission prompts, Dev containers).
[!WARNING] 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" (Development containers). VS Code's Dev Containers extension also reuses your local Git credentials in the container and forwards a running SSH agent, and the reference firewall lets GitHub and SSH through, so a run can push with them (Sharing Git credentials with your container). Use a dev container only with repositories you trust, and never mount host secrets such as~/.sshor cloud credential files into it.
Worked example
On GitHub, open
.devcontainer/devcontainer.jsonin your template copy:{ "name": "Claude Code practice", "image": "mcr.microsoft.com/devcontainers/base:ubuntu", "features": { "ghcr.io/devcontainers/features/node:1": { "version": "lts" }, "ghcr.io/anthropics/devcontainer-features/claude-code:1.0": {} }, "postCreateCommand": "sudo apt-get update && sudo apt-get install -y bubblewrap socat" }The
:1.0tag pins the feature's install script, not Claude Code: the feature installs the latest release, which then updates itself (Add Claude Code to your dev container). ThepostCreateCommandinstallsbubblewrapandsocat, which the Bash sandbox needs on Linux (Set up Linux and WSL2).Select Code, then the Codespaces tab, and create a codespace on
main(Creating a codespace for a repository). It opens in the editor set in your Codespaces settings (Setting your default editor for GitHub Codespaces); steps 3 to 6 use VS Code, in the browser or the desktop app.In its terminal:
echo "$CODESPACES"; whoami; claude --versionIt prints three lines:
true(GitHub setsCODESPACESin every codespace, Default environment variables for your codespace),vscode(the image's non-root user, Ubuntu image), and a version that can be newer than this page's stamp.Run
claude, sign in, and trust the folder when it asks. If the browser shows a code instead of returning to the terminal, paste it at thePaste code here if promptedprompt (Log in to Claude Code). Then ask:Run uname -a and whoami, then tell me which machine you're running on.Approve the command if Claude asks. Claude describes a Linux container, not your computer; your wording will differ. Quit with
/exit.Run
claude auth status --text: you're signed in (CLI commands). Rebuild: open the Command Palette (Ctrl+Shift+P, orCmd+Shift+Pon a Mac), run Codespaces: Rebuild Container, and choose Rebuild (Rebuilding the container in a codespace). When it reconnects:claude auth status --text; echo "exit $?"It ends with
exit 1: not signed in. A rebuild keeps/workspaces, where your repository lives, and clears~/.claude(Persisting data over a rebuild).Stop the codespace: run Codespaces: Stop Codespace from the Command Palette, or choose Stop codespace from the ... menu next to it on github.com/codespaces. Closing the browser tab doesn't stop it (Stopping and starting a codespace).
Your turn
Brief: put one of your own repositories in the reference container, with its firewall on and Claude Code pinned. Keep your sign-in across a rebuild, and let Claude finish one small task unattended, then review the result on your computer.
The docs' steps open Claude Code's own repository in the container; to use it with your project, you copy its .devcontainer/ folder into your repository and adjust the Dockerfile for your project's tools (Try the reference container). On a new branch, fetch the three files at the commit this guide was checked against:
git switch -c try-devcontainer
mkdir -p .devcontainer
ref=d945a61bc6346abce607252d5667df8a3bf0461a
for f in devcontainer.json Dockerfile init-firewall.sh; do
curl -fsSL "https://raw.githubusercontent.com/anthropics/claude-code/$ref/.devcontainer/$f" -o ".devcontainer/$f"
done
Acceptance criteria:
- You read all three files before the first build.
init-firewall.shruns as root each time the container starts:devcontainer.jsonruns it as thepostStartCommand(Dev Container metadata reference), and the Dockerfile lets thenodeuser run it withsudo. - Before the first build, you add
claude.aiandplatform.claude.comto the domainsinit-firewall.shresolves, next toapi.anthropic.com: signing in and refreshing the sign-in need them (Network access requirements). Hosts can share an address, and the script stops at the firstipset addthat meets an address it already added, so in the same loop changeipset add allowed-domains "$ip"toipset add -exist allowed-domains "$ip":-existignores an entry that's already in the set (ipset). devcontainer.jsonpins Claude Code: theCLAUDE_CODE_VERSIONbuild argument names a version you choose, such as2.1.285, in place oflatest, andcontainerEnvadds"DISABLE_AUTOUPDATER": "1". That's the docs' recipe: install a fixed version from the Dockerfile, and turn off auto-update (Enforce organization policy). The three files, with your changes, are committed on your branch.- Dev Containers: Reopen in Container builds and opens it. The build log's
npm warn EBADENGINElines are expected: the reference image runs Node.js 20 and the npm package requires 22 or later, but npm only warns, the install completes andclaudestill runs (Install with npm). In its terminal (Ctrl+`),whoamiprintsnode,claude --versionprints your version,curl -sS --connect-timeout 5 https://example.comfails, andcurl -sS --connect-timeout 5 https://api.github.com/zensucceeds. - You sign in with
claudeonce. After Dev Containers: Rebuild Container,claude auth statusstill exits with0: the reference mounts a named volume at/home/node/.claudeand pointsCLAUDE_CONFIG_DIRat it, and Docker keeps a volume after its container is gone (Volumes). - One unattended run finishes in the container's terminal, on a task that needs no tool the image lacks, such as
claude -p "Add a one-line summary of this repository to the top of README.md" --dangerously-skip-permissions --model sonnet --max-turns 10(CLI flags). - In a terminal on your computer, after the checks in the first Watch out bullet, you save
git status --porcelain > .practice/a-dc-status.txt, then readgit diff,.devcontainer/included, before you commit or discard the run's change.
When every item in the Check below is true, tear down:
- In the container's terminal, run
claude auth logout(CLI commands). Until you sign out, the config volume holds your credentials, and the volume outlives the container. - Close the VS Code window that's connected to the container. Closing it stops the container by default (
shutdownActionin the Dev Container metadata reference). - Remove the container: in VS Code's Remote Explorer, choose Containers, then right-click the container and remove it (Managing containers), or run
docker rm <container>(docker container rm). - Remove the two volumes whose names start with
claude-code-config-andclaude-code-bashhistory-:docker volume lslists them, thendocker volume rm <name>removes each. Docker won't remove a volume a container still uses, so this step comes after step 3 (docker volume rm).
Check
You are done when all of these are true:
- On your computer,
git ls-tree --name-only try-devcontainer .devcontainer/lists the three files, andgit show try-devcontainer:.devcontainer/devcontainer.json | jq -r '.build.args.CLAUDE_CODE_VERSION, .containerEnv.DISABLE_AUTOUPDATER'prints your version and1. - In the container,
whoamiprintsnode,claude --versionprints your version, theexample.comrequest fails and theapi.github.com/zenone succeeds. - In the container, after a rebuild,
claude auth status >/dev/null; echo $?prints0. - On your computer,
.practice/a-dc-status.txtlists the file the unattended run changed. - Self-check (not tested): in the codespace,
claude auth statusexited with1after the rebuild, and you can name two things the container doesn't protect: anything readable or usable inside it, such as~/.claudeand your forwarded Git credentials, and every file in the mounted project.
If jq reports a parse error, remove any comment or trailing comma you added to devcontainer.json. If example.com answers or api.github.com doesn't, the firewall script didn't succeed: run sudo /usr/local/bin/init-firewall.sh in the container and read its error. Element cannot be added to the set: it's already added means the -exist change is missing. If claude auth status exits with 1 after the rebuild, the volume's target and CLAUDE_CONFIG_DIR in containerEnv must name the same path (Persist authentication and settings across rebuilds). If the status file is empty, the run changed nothing, committed its change (git log -1 shows it), or stopped at --max-turns, which exits with an error (CLI flags): read what it printed, and give it a smaller task if it ran out of turns.
Watch out
- With
--dangerously-skip-permissions, Claude can also rewrite.devcontainer/and.git/: they're protected paths, but bypass mode writes protected paths without asking (Protected paths). Through the mount, the change lands on your computer: the next rebuild uses.devcontainer/, and git runs the hooks in.git/hooks, or in the folder.git/confignames, during commands such asgit commit(githooks). Before you rebuild or run git on your computer, read.git/configand list.git/hooks, then compare.devcontainer/with the commit you made (git log --oneline, thengit diff <your commit> -- .devcontainer). - A codespace keeps running until you stop it or it times out, and a stopped one still uses storage (Stopping and starting a codespace). Delete it when you're done, from the ... menu next to it on github.com/codespaces, or with
gh codespace delete(Deleting a codespace). - The firewall blocks outbound traffic its script doesn't allow, for everything in the container, Claude's commands included. When your project needs another host, such as PyPI or a private registry, add it to the script's list of domains and rebuild (Dev containers). Network access requirements lists the hosts Claude Code's own features use.
Go further
- Choose a sandbox environment: dev containers next to the Bash sandbox, other containers, virtual machines and cloud sessions.
- Enforce organization policy: managed settings built into the image, and why a file in the repository isn't an enforcement boundary.
- Explore the .claude directory: what the volume at
~/.claudeholds, including credentials, settings and session history.
Sources: Development containers · Choose a sandbox environment · Choose a permission mode · Configure the sandboxed Bash tool · Authentication · Advanced setup · CLI reference · Enterprise network configuration · Claude Code: reference dev container at d945a61 · GitHub: Creating a codespace for a repository, Setting your default editor for GitHub Codespaces, Default environment variables for your codespace, Rebuilding the container in a codespace, Stopping and starting a codespace, Deleting a codespace, GitHub Codespaces billing · VS Code: Developing inside a Container, Sharing Git credentials with your container · Dev Container metadata reference · Dev Container images: Ubuntu · Docker: Volumes, docker container rm, docker volume rm · Git: githooks · ipset
Back to the Advanced index · Topic: Permissions and safety · Stuck on this lesson?