Claude Code in a Devcontainer: A Practical Walkthrough

Running Claude Code inside a devcontainer puts its shell commands, project dependencies, and development tools in one reproducible environment. It also creates a useful boundary between agent-driven work and your host machine. This walkthrough builds a minimal setup, connects it through CodeRelay Hub, and checks the boundaries before you trust it with real changes.

1. Create a small, explicit container definition

Install Docker and the Dev Containers extension for Visual Studio Code. In your repository, create .devcontainer/devcontainer.json with this configuration:

{ "name": "Agent workspace", "image": "mcr.microsoft.com/devcontainers/javascript-node:1-22-bookworm", "remoteUser": "node", "remoteEnv": { "ANTHROPIC_BASE_URL": "https://api.coderelayhub.com", "ANTHROPIC_AUTH_TOKEN": "${localEnv:CODERELAY_API_KEY}" } }

The Node.js image provides a practical starting point for JavaScript projects. For another stack, select an appropriate development image instead. Keep the non-root user: Claude Code should normally have the same permissions as an ordinary developer, not unrestricted administrative access.

Use the command palette to select Dev Containers: Reopen in Container. Your repository becomes a mounted workspace, so edits inside the container still change the files on your host.

2. Pass credentials at runtime

Set CODERELAY_API_KEY in the environment of the host process that launches Visual Studio Code. The localEnv expression passes that value into the editor's remote environment without writing the secret into the repository.

If you launch the editor from a desktop icon, it might not inherit variables exported in a terminal. Launch it from the configured shell, or use your organization's approved secret-injection mechanism. Reopen the container after changing credentials.

Do not put keys in a Dockerfile, committed configuration, image layer, or build argument. Also avoid printing the environment while troubleshooting. A safer presence check is: test -n "$ANTHROPIC_AUTH_TOKEN" && echo "Token is present".

3. Install Claude Code inside the container

Open a terminal in the container and follow Claude Code's current official installation instructions. Its native Linux installer is commonly invoked as: curl -fsSL https://claude.ai/install.sh | bash.

This executes a downloaded script. Review it first if your security policy requires that, and use an approved installation process in managed environments. The native installation normally places the executable under the user's home directory. If necessary, add it to the current shell with: export PATH="$HOME/.local/bin:$PATH".

Run claude --version to confirm installation. A manually installed binary may disappear when the container is rebuilt. Once the setup works, automate installation through a reviewed postCreateCommand or a custom image. For reproducible team environments, record the tested version and establish an update process rather than silently tracking the latest release.

4. Verify gateway compatibility before working

Claude Code needs an Anthropic-compatible API surface; an OpenAI-compatible endpoint alone is insufficient. CodeRelay Hub provides the routing layer here, with https://api.coderelayhub.com configured as the base URL. Do not append an OpenAI chat-completions path.

Start claude in the repository and submit a small, read-only request, such as asking it to summarize the top-level directory structure. If your account requires an explicit model, use claude --model followed by the exact model identifier documented by the gateway. Do not assume a display name is also an API identifier.

If authentication fails, check that the token reached the container and that no stale ANTHROPIC_API_KEY or shell configuration conflicts with your intended authentication. For routing failures, verify the gateway's documented Claude Code settings and model availability before changing unrelated container configuration.

5. Keep the container boundary meaningful

A devcontainer is not an automatic security sandbox. The agent can modify mounted source files and access credentials available to its process.

• Do not mount your Docker socket unless the task genuinely requires it.
• Expose only necessary directories, credentials, and forwarded ports.
• Keep Claude Code's permission prompts enabled rather than bypassing them globally.
• Use a disposable branch and inspect git diff before accepting changes.

6. Test one complete development loop

Ask for a small change, review the proposed commands, run the project's tests, and inspect the resulting diff. Then rebuild the container and repeat the version and authentication checks. This catches missing tooling, installation assumptions, and secrets that existed only in an old shell.

Open a free workspace to try it.