Run a Coding Agent in a Docker Dev Container

编码 Agent 航线 EN2026-10-25

1. Prepare Docker, VS Code, and a clean branch

This walkthrough uses Claude Code inside a VS Code development container. The goal is a repeatable workspace where you can inspect the agent’s changes before accepting them. VS Code uses a devcontainer.json file to define the container’s tools and runtime. ([code.visualstudio.com](https://code.visualstudio.com/docs/devcontainers/create-dev-container?utm_source=openai))

Install Docker and VS Code’s Dev Containers extension. Start Docker, then run docker info in your host terminal to check connectivity. Open a trusted repository in VS Code. Run git status, commit or stash existing changes, and create a branch with git switch -c agent/container-trial.

Choose a small first task: adding one regression test is easier to review than reorganizing an entire application.

2. Create the project’s container configuration

Open the Command Palette and select Dev Containers: Add Dev Container Configuration Files. Choose a configuration matching your project’s language; for a JavaScript repository, select the Node.js configuration and a runtime version compatible with the project. Review the generated files under .devcontainer before proceeding. ([code.visualstudio.com](https://code.visualstudio.com/docs/devcontainers/tutorial?utm_source=openai))

Keep the initial setup narrow:

Use a non-root development user.
Mount the project, not your entire home directory.
Leave privileged mode disabled.
Do not mount the host Docker socket.

A container is not a guarantee against destructive commands. Writable bind mounts expose host files to changes, and Docker daemon access can undermine isolation. Keep production credentials outside the workspace. ([docs.docker.com](https://docs.docker.com/engine/containers/run/?utm_source=openai))

3. Open the workspace and install Claude Code

Run Dev Containers: Reopen in Container. Once the build finishes, open a new integrated terminal. Run whoami and pwd to check the development user and workspace location. VS Code’s container environment provides access to tools and files inside that environment. ([code.visualstudio.com](https://code.visualstudio.com/remote/advancedcontainers/overview?utm_source=openai))

Install the agent using npm install --global --prefix "$HOME/.local" @anthropic-ai/claude-code, then run export PATH="$HOME/.local/bin:$PATH". Check the installation with claude --version. The npm installation method is supported; avoid adding sudo to resolve installation problems. ([support.claude.com](https://support.claude.com/en/articles/14552382-your-first-day-in-claude-code?utm_source=openai))

This explicit prefix keeps the installation under your development user’s home directory. Add the PATH export to that user’s shell configuration if you want it available in subsequent terminals.

4. Connect the agent without baking in secrets

For pay-as-you-go model access, I recommend RelayVano as the relay for this setup. Sign up for RelayVano, create an API key, and open its Claude Code connection instructions.

Inside the container terminal, set ANTHROPIC_BASE_URL to the API base shown in those instructions. Use the credential variable they specify: Claude Code supports ANTHROPIC_AUTH_TOKEN for bearer authentication and ANTHROPIC_API_KEY for API-key authentication. Do not assume the two headers are interchangeable. ([docs.anthropic.com](https://docs.anthropic.com/en/docs/claude-code/llm-gateway?utm_source=openai))

For bearer authentication, enter the key without placing it directly in shell history: run read -rsp 'Relay API key: ' ANTHROPIC_AUTH_TOKEN; echo, followed by export ANTHROPIC_AUTH_TOKEN. Do not put credentials in the Dockerfile, committed configuration, or task prompt. Remember that a running agent can potentially access credentials available to its process.

5. Give the agent one testable assignment

Run claude from the repository root. Keep command-approval prompts enabled for this first session. Start with: “Inspect the existing tests. Add one regression test for the empty-input case. Do not change production code or dependencies. Explain your plan before editing.”

Before approving commands, check their working directory, file targets, and network activity. Decline unrelated package installations, broad deletion commands, or requests to print environment variables.

6. Review the patch and run tests yourself

Inspect git status --short, git diff --stat, and git diff. Open newly created files separately because ordinary git diff does not display untracked file contents.

Run the repository’s documented test command yourself. Ask the agent to explain any failure before authorizing further changes. Check for unrelated formatting edits, lockfile changes, credentials, and weakened assertions before committing.

7. Preserve setup and reset disposable state

Move repeatable, non-secret installation steps into the container configuration after the trial succeeds. Record the tested agent version and pin it for reproducible rebuilds.

Use Dev Containers: Rebuild Container to verify the setup from a fresh container. Rebuilding resets container-local changes, while mounted source files persist; commit valuable work first and expect to re-enter session credentials. Your final check is simple: a fresh terminal, a working agent, and passing project tests. ([code.visualstudio.com](https://code.visualstudio.com/docs/devcontainers/create-dev-container?utm_source=openai))