Does Claude Code Need a VM for This Workflow?

Compare Claude Code’s Sandbox Bash tool, Sandbox Runtime, and a VM using the same benign fixture and observed outcomes. Price the VM’s extra setup and compute once you know which boundaries meet the workflow’s requirements.

Separate workflow failures from policy failures

Build a fixture with a readable input, a permitted output directory, and an inert marker outside the intended workspace. Keep the fixture free of credentials and production data. Run the same task under each candidate boundary. Record whether the build succeeds and whether each in-scope Claude Code surface respects the expected access rule. Test the shell and file tool independently. A successful build with the shell marker denied and the file tool marker allowed is consistent with shell-only enforcement and fails a requirement covering both surfaces. An unexpected denial is also actionable because it signals a broken workflow. Keep an explicit row for each required surface, including any hook or MCP server used in the real workflow, and record a missing observation as untested.

Configure the sandboxed Bash tool - Claude Code Docs

Quote the VM using the whole billed interval

Start timing when billed VM allocation begins and stop when it ends. Record setup and checkout separately from the time it takes the fixture to pass. Compare those intervals against the same run inside Anthropic Sandbox Runtime, which uses host operating system primitives and proxy-based network filtering. In an illustrative VM quote of $0.60 per hour, six extra billed minutes per job add $0.06 per job before storage and other charges. At 800 jobs a month, that setup time contributes $48. Repeat with a warm image and report the cold and warm timings separately so a fast repeat run cannot hide the launch cost. If your policy requires a separate guest kernel, treat that requirement as an eligibility check before comparing prices.

GitHub - anthropics/sandbox-runtime: A lightweight sandboxing tool for enforcing filesystem and network restrictions on arbitrary processes at the OS level, without requiring a container. · GitHub

List every process that needs containment

Claude Code's built-in Bash sandbox restricts filesystem and network access for Bash, PowerShell, and Monitor commands and their child processes. Claude's file tools, MCP servers, and hooks run outside that shell boundary. Inventory those surfaces along with the shell before choosing a setup. Record which project paths, credentials, and services each surface needs.

Use the built-in sandbox for a supervised repository task when the shell is the surface you need to restrict. Use a container or VM for a worker whose entire Claude Code process needs isolation. Run the relevant hooks and integrations inside that same environment, and account separately for any remote services they call. Keep tool approvals in place according to the job's oversight requirements.

Configure the sandboxed Bash tool - Claude Code Docs

Check the policy from the working directory

Start a test session in a disposable repository on a supported host. Use the sandbox setup instructions for the installed Claude Code version to enable it, then inspect the applicable user, project, and managed settings. Claude Code reads the shared settings file from the session's primary working directory, so start at the repository root when testing policy stored there.

For an illustrative repository cleanup, allow writes inside the checkout and deny shell reads of a harmless marker file in a test directory outside it. Ask Claude to run the normal test suite and separately attempt to read the marker through the shell. Require the tests to pass and the marker read to be denied. If a file tool can still read the marker and that matters for the job, use an outer boundary that leaves the directory inaccessible.

Settings files and precedence - Claude Code Docs

Test private access without broadening the worker

For a private database test, use a staging database and a disposable credential scoped to the operations the test requires. Run Claude Code inside the selected outer environment. Give that environment only the required project files and network path. Verify the expected query succeeds, then attempt to connect to a harmless test endpoint outside the approved network path and verify the connection is refused.

If the staging test fails, check whether Claude is waiting for tool approval, the network path is blocked, or the database rejects authentication. A tool approval prompt points to permission policy. A denied connection or rejected credential needs a fix at the corresponding layer. Repeat both tests after any change so restoring authorized access also preserves the restriction.

Choose a sandbox environment - Claude Code Docs

Sources