The Complete Claude Guide
← Back to topic
Chapter 09 · CLI

Sandbox, isolated environments and devcontainers

Running commands inside a sandbox reduces the chance a tool action harms your system. You can choose between built-in sandboxing, isolated environments and devcontainers, based on the isolation level needed.

Verified against source on 2026-09-30

Video

Define an execution boundary, not just a prompt

You will inspect sandbox state, choose oversight and understand what remains outside the boundary. Example outputs are illustrations.

Sources checked September 30, 2026 distinguish the Bash sandbox, containers and virtual machines. A permission mode controls approvals. A sandbox restricts filesystem and network capabilities. Neither verifies that the task itself is correct.

Inspect the supported route

Open /sandbox in the practice session and read support, mode and overrides. macOS and Linux/WSL2 have documented platform requirements; Linux may need bubblewrap and socat. Follow the official setup for your platform rather than installing packages blindly.

For learning, prefer regular permissions with isolation retained. Auto-allow can run sandboxed Bash writes without a prompt even when file-edit tools would ask. Do not assume Manual means every sandboxed command always pauses.

Use a harmless local check

Supply a tiny practice file:

course-status.txt
Unit 1: ready
Unit 2: under review
Publication date: not set
Read course-status.txt inside this practice directory only.
Report its two unit statuses and whether a date was supplied.
Do not modify files, connect hosts, install packages or read credentials.
Before any command, explain why it is needed.

Expected output:

Unit 1 is ready; Unit 2 is under review.
No publication date was supplied.
No change or network access is needed.

Compare with the file and inspect the directory afterward. A sandbox permits some writes by design; read-only intent still needs checking.

Inspect a denied path or host without escalating

If a command is blocked, read the actual named path/host and whether it was required. For this exercise it is not necessary to add a host or permit another folder.

The blocked access is outside this exercise.
Do not retry unsandboxed or widen permissions.
Explain what could not be read and finish using only the practice file.

An unsandboxed retry is a different execution boundary. The official guide describes an escape hatch and settings to disable it; inspect the requested retry rather than approving it automatically. Do not turn filesystem isolation off to make a simple read work.

Containers are a separate setup

A devcontainer isolates a development environment but its mounts, credentials, network and capabilities still matter. A container with a mounted home directory or broad network can expose valuable data. Virtual machines provide another boundary with their own configuration and cost.

This exercise requires no Docker download, image build, cloud VM or paid service. For real adoption, inspect the exact configuration and test on copies before granting access to work material. An isolated environment does not make unknown project scripts safe to execute.

Graded practice

Easy: identify boundaries

Explain approval versus isolation. Success: distinguish mode, allowed paths and hosts.

Intermediate: bounded check

Read the practice file. Success: correct output and no modification or access expansion.

Challenging: blocked access

Respond to an unnecessary blocked request. Success: task completes without unsandboxed retry or broader permissions.

Troubleshooting

Sandbox unsupported: inspect platform and prerequisites; do not silently claim isolation.

Tool cannot write a temp file: inspect the specific allowed temp route, not the entire disk.

Network blocked: determine necessity before allowlisting.

Isolation disabled: stop sensitive work and inspect current settings.

Container mounted private material: reduce scope before running project code.

Mechanism animation (illustration)

Filmed demo · Video is added in the media phase

Recap

Comprehension check

What is the guiding principle when combining permissions and environments?

Recap

Sources and further reading

← Previous Back to topic Next →