Running Claude Code Safely: Sandboxing & Isolation Guide

A common point of confusion when configuring Claude Code is the distinction between permissions and sandboxing controls. While both protect your system, they operate at completely different layers of the security stack:

• Permissions Layer: Decides whether Claude Code must ask for human approval before taking an action (such as reading a file, executing a shell command, or spawning a subagent).
• Sandboxing Layer: Decides what system resources Claude Code can physically reach, read, or modify after an action is authorized.

1# Bypassing permission prompts means ALL security relies on your Sandboxing layer:2claude -p "Refactor authentication flow" --dangerously-skip-permissions

When you use flags like --dangerously-skip-permissions, Claude Code executes actions automatically without waiting for interactive confirmation. In this unattended mode, relying solely on basic terminal permission prompts is insufficient—you must wrap the agent in a container, virtual machine, or sandbox runtime.

Depending on your threat model, repository trust level, and execution environment, Claude Code can be run across five distinct isolation tiers. Choosing the appropriate tier depends on whether you are working on trusted personal projects or untrusted open-source codebases.

The matrix below outlines the spectrum from lightweight terminal filtering to full cloud-managed VM instances, helping team leaders select the right isolation boundary for their developer workflow.

While sandboxing dramatically reduces blast radius, it is vital to recognize that sandboxing reduces security risk, but does not eliminate it completely.

Consider these key security implications when configuring sandboxed agent environments:

1. Readable Project Data: If the sandbox mounts your project folder as readable, the agent (or a compromised tool) can still inspect source code, configuration files, and embedded API keys. 2. Outbound Internet Egress: If the sandbox retains active internet access (e.g. to download npm packages or fetch documentation), readable data could potentially be transmitted externally if untrusted instructions are ingested. 3. Writable Mounts: Mounting your repository directory as writable inside a container allows the agent to modify code files. Always keep git commit checkpoints before running broad agent tasks.

To balance developer productivity with security, follow these simple operational rules based on your task context:

• Normal Personal Coding: Use the built-in /sandbox command or local terminal sandboxing for interactive feature work on your own repositories.
• Unattended or Auto Agent Work: When launching background tasks with --dangerously-skip-permissions or using Auto Mode, run inside a Sandbox Runtime or Docker Dev Container.
• Unknown or Untrusted Repositories: When evaluating third-party code, open-source pull requests, or unverified repos, always use a dedicated Virtual Machine or Claude Code Web.

Test a container boundary with a disposable project and no host credential mount. This example is a teaching baseline, not a complete security boundary:

1mkdir -p agent-sandbox-demo && cd agent-sandbox-demo2printf '%s\n' '{"name":"sandbox-demo"}' > package.json3docker run -it --rm \4  --network none \5  --cap-drop=ALL \6  --read-only \7  -v "$PWD:/workspace:rw" \8  -w /workspace \9  node:20-slim bash

Do not pass a long-lived API key into an untrusted container. If the agent needs network access, add only the required egress and use short-lived credentials or a host-side proxy. The bind mount remains writable, so commit checkpoints and inspect the diff after the run.