Claude Code Sandboxing for QA: Isolate Test Commands Safely

AI-assisted test automation is most useful when the agent can run the suite, inspect failures, and repeat targeted checks. Those same shell commands can install packages, rewrite files, contact external hosts, or expose credentials if the workspace is poorly controlled. Claude Code sandboxing for QA gives teams an operating-system-enforced boundary for Bash commands and their child processes.

This tutorial creates a disposable isolation lab for a test runner. You will enable the sandbox, define expected file and network boundaries, run allowed tests, provoke blocked actions, inspect fallback behavior, and record evidence. The goal is not merely to see a green test. It is to prove that useful QA commands run while unsafe access stays contained.

Understand the boundary before testing it

Anthropic’s official Bash sandbox documentation says the sandbox applies to Bash commands and every child process they start. By default, those commands can write only to the current working directory and the session temporary directory. Network requests go through a proxy, and a request to a new domain needs approval.

The boundary is intentionally narrower than the whole Claude Code session. Built-in Read, Edit, Write, and WebFetch tools use the permission system rather than the Bash sandbox. MCP servers and hooks are separate processes on the host. If your threat model requires every tool and helper process to be isolated, use a full-process sandbox runtime, container, or virtual machine. The official sandbox environment comparison helps choose that layer.

Create a disposable QA isolation lab

Start with a test-only repository that contains no production secrets:

claude-sandbox-lab/
  src/calculator.py
  tests/test_calculator.py
  reports/
  .claude/settings.local.json

Add a small deterministic suite with passing, failing, and boundary cases. Record the baseline test command, exit code, test count, duration, repository status, and report checksum. Use synthetic environment values only. Keep a separate marker file outside the project directory so you can prove that an attempted write is blocked without risking real data.

On Windows, run this lab in WSL2, a container, or a VM. Anthropic’s current documentation says the built-in Bash sandbox does not support native Windows. It also notes that WSL2 sandboxed commands cannot launch Windows executables or programs under /mnt/c/ through the normal boundary. Do not weaken isolation merely to make a cross-platform test shortcut work.

Enable and inspect the sandbox

Start Claude Code inside the lab and open the sandbox panel:

/sandbox

The panel lets you choose an approval mode, control unsandboxed overrides, inspect resolved configuration, and review Linux dependencies when relevant. Auto-allow mode automatically approves commands that can run inside the sandbox. Regular permissions mode keeps ordinary command prompts. Both modes enforce the same filesystem and network boundary.

For a first QA exercise, choose regular permissions so each action is visible. To enable sandboxing in configuration, use the documented setting:

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false
  }
}

failIfUnavailable matters in controlled environments. Without it, the documented default is to warn and run commands unsandboxed when the sandbox cannot start. Setting allowUnsandboxedCommands to false disables the escape hatch that can retry a failed command outside the sandbox through the normal permission flow.

Run the positive test path

Ask Claude Code to run only the known test command and save a report under reports/. Confirm that the suite can read source and fixture files, create the expected report inside the project, and return the baseline result. Capture the command, approval decision, test output, report checksum, and Git diff.

Next, repeat the same command in auto-allow mode. It should run without a command prompt only when it stays inside the configured sandbox boundary. Verify that automation did not silently widen the allowed paths or domains. Auto-allow changes prompting; it does not make an unsafe command safe.

Exercise blocked filesystem access

Use harmless marker paths and test one boundary at a time:

• Attempt to create a file beside, rather than inside, the project.
• Attempt to read a synthetic credential file covered by a deny rule.
• Attempt to follow a symlink from the project to a denied location.
• Attempt to write to a tool cache outside the workspace.

Every blocked operation should produce a visible failure, leave the external marker unchanged, and preserve the repository baseline. Then grant the narrowest additional write path only if the real test runner needs it. Anthropic recommends sandbox.filesystem.allowWrite for a specific path instead of excluding the entire command from the sandbox.

Exercise blocked network access

Create a test that contacts one synthetic allowed service and one unapproved domain. Verify that the approved host succeeds and the other request is blocked or requires a decision. Avoid broad domain patterns: an allowed domain is a route for data the command can read.

Also test a dependency command in offline mode. The desired failure should be clear and recoverable, not an endless retry. Preserve proxy or sandbox notifications with the test evidence. Network isolation is domain-based; the built-in proxy does not inspect encrypted content unless your chosen configuration provides that capability.

Pair sandboxing with permissions

The official permissions documentation describes allow, ask, and deny rules. They are evaluated in that order of precedence: deny first, then ask, then allow. A matching deny cannot be overridden by a narrower allow.

Use a project policy that permits only the exact test commands required by the lab, asks before package installation or network-capable commands, and denies access to secrets or release actions. Review effective rules with /permissions. Prompt instructions and project memory can guide behavior, but they are not access-control rules.

QA sandbox validation matrix

Scenario	Expected result	Evidence
Test run writes project report	Allowed inside workspace	Exit code, report checksum
Write outside project	Blocked by OS boundary	Sandbox error, unchanged marker
Read denied credential fixture	Blocked without revealing value	Redacted failure output
Allowed test API domain	Request succeeds	Mock server log and response
Unapproved domain	Blocked or explicitly gated	Proxy notification
Sandbox dependency missing	Session fails closed when required	Startup error with failIfUnavailable
Unsandboxed retry attempted	Rejected in strict configuration	Override decision and log
Built-in Edit or MCP action	Handled by its own permission or outer isolation	Permission trace and boundary note

Know when the Bash sandbox is not enough

Use a container, VM, or full-process sandbox when testing untrusted repositories, running unattended agents, loading third-party MCP servers or hooks, or exposing powerful cloud tooling. A writable project can still be damaged, and any permitted egress can carry readable data. Isolation also does not change what selected files and prompts are sent to the configured model provider.

Anthropic’s security guidance keeps responsibility with the user to review commands and code before approval. For QA teams, that means retaining normal Git history, deterministic CI, secret scanning, dependency controls, peer review, and human defect, merge, and release decisions.

Definition of done

The lab is complete when the expected test command runs reproducibly, permitted outputs stay inside the project, denied file and network attempts fail visibly, the session fails closed when isolation is required, and the team can explain which Claude Code tools remain outside the Bash boundary. Store the matrix, logs, checksums, and configuration with your QA playbook, then repeat the drill after material runner, policy, or environment changes.