Claude Code in a Devcontainer: An Isolated Environment for Teams

Claude Code in a Devcontainer: An Isolated Environment for Teams

Running Claude Code in a devcontainer means placing the agent inside a container defined in the repository itself, with an unprivileged user, only the project code mounted, secrets kept out of the image, and outbound network access limited to an allowlist of destinations. The whole team then works in the same environment, and if the agent makes a mistake or is tricked into one, the damage stays contained. The container does not replace permissions or human review, but it greatly reduces what a mistake can reach.

Key takeaways

• A devcontainer standardizes versions, tools and configuration, and keeps the agent's environment versioned alongside the code.
• Useful isolation comes from three limits: what the agent can see on disk, where it can connect, and which credentials exist inside.
• A container is not an absolute boundary: it shares the host kernel, and the mounted project folder is still writable.
• The .devcontainer folder needs review like any sensitive code, because the agent may try to change it.
• Start with one repository and one workflow, test attempts that should fail, and only then roll it out to the rest of the team.

What is a devcontainer, and why use it with Claude Code?

A devcontainer is a development environment described in repository files, usually devcontainer.json and, when needed, a Dockerfile. Compatible editors and command-line tools read that description, build the container and open the project inside it. Anyone who clones the repository gets the same operating system, the same language versions and the same extensions.

For Claude Code, this solves two problems at once. The first is operational: the agent no longer depends on each person's machine, and the classic "it works on my computer" loses force. The second is risk: an agent that reads files, runs commands and installs packages has far more reach when it runs directly on a developer's laptop, where SSH keys, personal files and open sessions live. Inside a container, you decide that reach.

The Claude Code documentation includes a reference devcontainer configuration, including the idea of a firewall with an allowlist of destinations. It is a good starting point, but check the current version, because the details change. The rest of this article is implementation guidance we recommend adapting to your case, not an official rule.

What does the container protect, and what does it not protect?

Separating fact from expectation avoids a false sense of security.

What the container helps protect:

• Personal files and other projects on the computer, which are simply not mounted.
• User credentials, such as SSH keys and cloud tokens stored in the home directory.
• Consistency: the agent uses the tools you chose, at the versions you pinned.
• The network, if you apply a restrictive outbound policy.

What it does not solve on its own:

• The mounted code is writable. The agent can delete, rewrite or corrupt project files, including the container's own configuration files.
• Containers share the host kernel. For hostile code or higher-risk workloads, a separate virtual machine is a stronger boundary.
• The agent can read data inside the project. If the repository holds real personal data, data protection law (LGPD in Brazil) still applies, and isolation does not change that.
• Prompt injection: malicious text on a web page, in an issue or in a dependency can try to push the agent into acting. OWASP's guidance on preventing prompt injection describes this risk and helps you think about layered defenses.

The devcontainer is one layer. It works best combined with the permissions and sandbox covered in Claude Code security for teams.

How to set up the devcontainer, step by step

This is a lean plan for a first repository. Each step is a decision, not just a file.

• Choose a minimal base image and pin its version. Avoid huge generic images, because every extra tool adds surface area.
• Create a non-root user and configure devcontainer.json to use it (the remoteUser field does this). The agent does not need administrator rights to edit code and run tests.
• Install only what is necessary: the language runtime, package manager, git, Claude Code itself and the test tools. Use postCreateCommand or the Dockerfile so the setup is reproducible.
• Mount only the project folder. Do not mount the home directory, the SSH key folder or the Docker socket. Mounting the Docker socket is equivalent to handing over control of the host.
• Keep Claude Code's configuration in a named container volume, so history and preferences survive rebuilds without exposing the host directory.
• Inject secrets at runtime, not in a versioned file. Use variables from a secrets manager or the person's environment, with test credentials and minimal scope.
• Apply the network policy (next section).
• Version everything and protect the .devcontainer folder with mandatory review, for example through CODEOWNERS.
• Write refusal tests: attempts that should fail, listed later in this article.

If your team already uses shared standards, it is worth packaging common instructions and commands. See how in Claude Code plugins for teams.

How do you restrict the container's network?

By default, a container can reach the entire internet. For an agent that reads external content and runs commands, this is the most dangerous door: project data can leave through it, and malicious instructions can come in through it.

The recommended approach is to deny by default and allow a short list of destinations. That list usually includes:

• The address of the model API that Claude Code uses.
• The package registries the project actually uses, such as npm or PyPI.
• The code repository host, if the agent needs remote git access.
• Internal test services, when they are indispensable.

Everything outside the list is blocked. The reference configuration mentioned in the documentation applies firewall rules inside the container, which typically requires extra network capabilities for the container itself. That is a real tradeoff: whoever holds that privilege inside the container could, in theory, change the rules. So if your environment allows it, a more robust alternative is to enforce the policy outside the container, in an egress proxy or in host network rules, where the agent cannot touch it.

Whichever route you take, record which destinations were allowed and why. Every exception should have a written reason. MCP servers also open connections, so review them first: see how to configure MCP in Claude Code and, for the security review, how to audit an MCP server before installing it.

How do you restrict files and secrets?

The rule is simple: the agent only sees what it needs for the task.

• Mount only the project root. If the repository is large, consider mounting just the subdirectory of the service the person is working on.
• Keep real environment files outside the mounted folder. Provide an example file with fake values and leave the real values to whoever runs the system elsewhere.
• Use short-lived, minimal-scope tokens for git and any API. Prefer read-only credentials when the task does not require writing.
• Work on a dedicated branch. Nobody should give the agent permission to publish straight to production.
• Avoid real customer data in the repository and in tests. Anonymized or synthetic data lowers privacy risk and simplifies the conversation with legal.
• Treat the .devcontainer folder, the project's Claude Code configuration files and CI scripts as sensitive areas that need human review.

OWASP's list of risks for LLM applications includes problems such as excessive agency and sensitive information disclosure. The limits above target exactly those two: less access and fewer credentials available.

Can I run the agent without confirmation prompts inside the container?

This is a common question, because confirming every command is tiring. Claude Code has modes that reduce or remove confirmations. Our reading, which is an implementation judgment and not an official rule, is this:

• Only consider reducing confirmations when the network is restricted, there are no useful secrets inside the container, and the project is on a disposable branch.
• Even then, the agent can still read the project contents. If the network allows any destination, something can leave through it.
• For repositories with sensitive code or personal data, keep the confirmations and use allowlists of permitted commands.
• Any irreversible action, such as deleting data, publishing, or sending a message to a customer, still requires human approval.

A good decision test is to ask: if the agent were tricked into running the worst possible command in here, what would we lose? If the answer is only a disposable branch, autonomy is reasonable. If it is something unrecoverable, it is not.

Illustrative scenario: a small team and an internal system

Illustrative scenario: a company has an internal scheduling system maintained by four people. Each uses a computer with different settings, and one of them keeps production keys on their machine. The company wants to use Claude Code to refactor modules and write tests.

It creates a devcontainer with a pinned image, a non-root user, only the project folder mounted, and an outbound allowlist containing the model API, the package registry and the git host. Production credentials stay out of the container: it gets only a test token with read permission on the staging database. The .devcontainer folder now requires review by a second person.

In the first week, the team runs the refusal tests. An attempt to reach a domain outside the list fails. Reading a file outside the project fails. A request for a production variable comes back empty. Only then does the rest of the team adopt the environment. The gain is not a number: everyone works the same way, and the worst case became smaller and easier to explain.

Refusal tests before rolling out to the team

Isolation that nobody tested is only an assumption. Before handing it over, confirm that these attempts fail:

• Connecting to a domain that is not on the destination list.
• Reading files from the host's home directory or SSH keys.
• Accessing the Docker socket or creating containers from inside.
• Reading production environment variables.
• Publishing directly to a protected branch.
• Changing the .devcontainer folder without going through review.

Repeat the tests whenever the image or the network policy changes. To track usage without turning the environment into individual surveillance, see how to measure AI productivity without surveillance.

How the map, limit, pilot and hand over method applies

In consulting practice, the path follows four stages. Map: identify which repositories, data, credentials and network destinations the workflow actually touches, and how the team works today. Limit: reduce mounted files, secrets and outbound network access to the minimum necessary, and define what requires human approval. Pilot: apply the devcontainer to one real repository, with logs and an agreed success criterion, for example less time to set up a new person's machine and no refusal test failing. Hand over: document the environment, train the team and decide together whether to expand, adjust or stop.

Frequently asked questions

Do I need Docker to use Claude Code in a devcontainer? In general yes, because a devcontainer depends on a container engine, usually Docker or a compatible equivalent, and on an editor or tool that reads devcontainer.json. Check the current documentation for what your tool supports. On corporate machines, also validate IT policies before installing.

Does the devcontainer replace Claude Code permissions? No. It limits the environment, while permissions control what the agent can do inside it. The two layers complement each other, and human review of changes is still necessary, especially for code headed to production.

Does the container prevent project data from leaking? It reduces the risk but does not eliminate it. If any network destination is allowed, data the agent can read could, in theory, leave through it. That is why the destination list should be short, the project should not contain real personal data, and secrets should stay outside the container.

Is it worth it for a small team? Yes, because the cost of standardizing is low at the start and grows over time. A single well-reviewed devcontainer prevents differences between machines and gives you a clear place to apply security rules. Start with one repository and expand after validating with the refusal tests.

Sources

• OWASP: prevenção de injeção de prompt
• OWASP Top 10 para aplicações com LLM
• Model Context Protocol: introdução