Cấu hình sandboxed Bash tool

Bash sandbox cho phép Claude chạy hầu hết lệnh shell mà không cần dừng lại hỏi quyền. Thay vì phê duyệt từng lệnh, bạn định nghĩa những file và network domain nào lệnh được chạm tới, và hệ điều hành thực thi ranh giới đó cho mỗi lệnh Bash và các process con của nó.

Ghi chú

Để so sánh với các phương án cô lập khác (dev container, custom container, VM), xem Sandbox environments. Để giảm prompt phê duyệt cho các tool khác ngoài Bash, xem permission modes.

Bắt đầu

Sandbox tích hợp sẵn trong Claude Code, chạy trên macOS, Linux, và WSL2. Windows thuần không được hỗ trợ - chạy Claude Code trong một distro WSL2.

Trên macOS không cần cài gì thêm: sandbox dùng framework Seatbelt có sẵn. Trên Linux và WSL2, sandbox dựa vào hai package (xem Set up Linux and WSL2).

1. Chạy /sandbox - mở panel sandbox với ba tab (Mode, Overrides, Config), cộng tab Dependencies trên Linux nếu thiếu seccomp filter tuỳ chọn.
2. Chọn mode - trên tab Mode, chọn auto-allow hoặc regular permissions.
3. Chạy một lệnh Bash - mặc định lệnh trong sandbox chỉ ghi được vào working directory và session temp directory. Lần đầu một lệnh cần domain mạng mới, Claude Code hỏi phê duyệt.

Khi bạn chọn mode trong panel, Claude Code lưu vào .claude/settings.local.json của project (áp dụng cho project hiện tại). Để bật sandbox cho mọi project, đặt sandbox.enabled thành true trong user settings tại ~/.claude/settings.json. Để ép buộc cho toàn tổ chức, dùng managed settings.

Chú ý

Mặc định, nếu sandbox không khởi động được (thiếu dependency hoặc platform không hỗ trợ), Claude Code hiện cảnh báo và chạy lệnh không sandbox. Để biến đây thành lỗi cứng, đặt sandbox.failIfUnavailable thành true - dùng cho triển khai managed cần sandbox như một cổng bảo mật.

Set up Linux và WSL2

Sandbox trên Linux/WSL2 dựa vào hai package:

• bubblewrap: công cụ sandbox không cần quyền root, thực thi cô lập filesystem
• socat: relay dùng để định tuyến network traffic qua sandbox proxy

# Ubuntu/Debian
sudo apt-get install bubblewrap socat

# Fedora
sudo dnf install bubblewrap socat

Ripgrep đi kèm sẵn với binary Claude Code native. Seccomp filter là tuỳ chọn, thêm chặn Unix domain socket - cài bằng npm install -g @anthropic-ai/sandbox-runtime nếu thiếu.

Sandbox modes

Claude Code có hai sandbox mode:

Auto-allow mode: khi một lệnh có thể sandbox được, Claude Code chạy nó trong sandbox và tự động phê duyệt, không hỏi quyền. Lệnh không sandbox được (ví dụ cần truy cập host chưa được allow) sẽ rơi về flow permission thông thường.

Ngay cả ở auto-allow mode, các điều sau vẫn áp dụng:

• Deny rule tường minh luôn được tôn trọng
• Lệnh rm/rmdir nhắm vào /, home directory, hoặc path hệ thống quan trọng khác vẫn kích hoạt prompt phê duyệt (hoặc classifier check trong auto mode)
• Ask rule có scope nội dung như Bash(git push *) vẫn ép hỏi kể cả với lệnh đã sandbox
• Ask rule trần Bash (hoặc Bash(*)) bị bỏ qua với lệnh chạy sandboxed; vẫn áp dụng với lệnh rơi về flow thông thường. Trong plan mode, rule không bị bỏ qua - vẫn hỏi cho lệnh sandboxed kể cả read-only

Regular permissions mode: mọi lệnh Bash đi qua flow permission thông thường, kể cả khi đã sandbox. Cho kiểm soát chặt hơn nhưng cần phê duyệt nhiều hơn.

Session temp directory mặc định ghi được trong sandbox, bên cạnh working directory. Claude Code đặt $TMPDIR trỏ vào đây cho lệnh sandboxed.

Một số lệnh không chạy được trong sandbox. Thay vì làm task fail, Claude Code có escape hatch: khi lệnh fail vì hạn chế sandbox, Claude phân tích lỗi và có thể retry với param dangerouslyDisableSandbox. Lệnh retry chạy ngoài sandbox, đi qua flow permission thông thường. Bạn có thể tắt escape hatch này bằng "allowUnsandboxedCommands": false trong sandbox settings (hiển thị trong tab Overrides là Strict sandbox mode).

Cấu hình sandboxing

Tuỳ chỉnh hành vi sandbox qua file settings.json. Mặc định, lệnh sandboxed chỉ ghi được vào working directory và session temp directory. Nếu subprocess như kubectl, terraform, npm cần ghi ngoài các thư mục đó, dùng sandbox.filesystem.allowWrite:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "/tmp/build"]
    }
  }
}

Các path này được thực thi ở cấp OS, áp dụng cho mọi lệnh chạy trong sandbox kể cả process con. Khi cùng một mảng filesystem được định nghĩa ở nhiều settings scope, các mảng được gộp lại.

Tiền tố path quy định cách resolve:

Tiền tố	Ý nghĩa	Ví dụ
/	Absolute path từ filesystem root	/tmp/build giữ nguyên /tmp/build
~/	Tương đối với home directory	~/.kube thành $HOME/.kube
./ hoặc không tiền tố	Tương đối với project root (project settings) hoặc ~/.claude (user settings)	./output trong .claude/settings.json resolve thành <project-root>/output

Chú ý

Cú pháp này khác với Read/Edit permission rule, vốn dùng //path cho absolute và /path cho project-relative. Sandbox filesystem path dùng quy ước chuẩn: /tmp/build là absolute.

Bạn cũng có thể deny write/read access bằng sandbox.filesystem.denyWrite/denyRead, và mở lại các path cụ thể trong vùng bị deny bằng sandbox.filesystem.allowRead.

Tắt cô lập filesystem

Đặt sandbox.filesystem.disabled thành true để bỏ qua cô lập filesystem trong khi vẫn giữ cô lập mạng:

{
  "sandbox": {
    "enabled": true,
    "filesystem": { "disabled": true },
    "network": { "allowedDomains": ["github.com", "*.npmjs.org"] }
  }
}

Chú ý

Với cô lập filesystem tắt và lệnh auto-allow, một lệnh sandboxed có thể ghi file mà lệnh sau đó chạy hoặc đọc (shell startup file, executable trên $PATH, ~/.claude/settings.json…) và dùng chúng để mở rộng quyền truy cập của chính nó ở lần chạy sau. Chỉ đặt filesystem.disabled cho các workload bạn tin tưởng không tự leo thang quyền.

Bảo vệ credential

Setting sandbox.credentials khai báo file credential và env var cần bảo vệ khỏi lệnh sandboxed. Yêu cầu Claude Code v2.1.187 trở lên.

{
  "sandbox": {
    "enabled": true,
    "credentials": {
      "files": [
        { "path": "~/.aws/credentials", "mode": "deny" },
        { "path": "~/.ssh", "mode": "deny" }
      ],
      "envVars": [
        { "name": "GITHUB_TOKEN", "mode": "deny" },
        { "name": "NPM_TOKEN", "mode": "deny" }
      ]
    }
  }
}

"mode": "mask" (yêu cầu v2.1.199+) bảo vệ credential trong khi vẫn giữ tool xác thực bằng nó hoạt động: lệnh sandboxed thấy một giá trị sentinel thay vì giá trị thật; khi request rời sandbox đến một trong các injectHosts của credential, sandbox proxy thay sentinel bằng giá trị thật.

Cách sandbox hoạt động

Cô lập filesystem

• Ghi mặc định: đọc/ghi trong working directory hiện tại và subdirectory của nó, cộng session temp directory
• Đọc mặc định: đọc toàn bộ máy, trừ một số thư mục bị deny. Lưu ý mặc định này vẫn cho phép đọc file credential như ~/.aws/credentials và ~/.ssh/ - dùng sandbox.credentials để chặn
• Bị chặn: không sửa được file ngoài working directory và session temp directory nếu không được cấp quyền tường minh, kể cả shell config file như ~/.bashrc và system binary trong /bin/

Cô lập mạng

• Giới hạn domain: mặc định không domain nào được allow trước. Lần đầu một lệnh cần domain mới, Claude Code hỏi phê duyệt (chọn Yes cho phép host đó cho phần còn lại của session)
• Managed lockdown: nếu allowManagedDomainsOnly được đặt trong managed settings, domain không được allow sẽ tự động bị chặn thay vì hỏi

Thực thi cấp OS

• macOS: Seatbelt
• Linux: bubblewrap
• WSL2: bubblewrap, giống Linux

WSL1 không được hỗ trợ vì bubblewrap cần tính năng kernel chỉ có ở WSL2.

Cấu hình sandbox cho tổ chức

Ép buộc sandbox bằng managed settings

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

• failIfUnavailable: dependency thiếu (ví dụ bubblewrap trên Linux) sẽ chặn Claude Code khởi động thay vì hiện cảnh báo và fallback
• allowUnsandboxedCommands: false: escape hatch dangerouslyDisableSandbox bị bỏ qua

Custom proxy configuration

Tổ chức cần bảo mật mạng nâng cao có thể triển khai proxy tuỳ chỉnh để giải mã/kiểm tra HTTPS traffic, áp filter tuỳ chỉnh, log mọi network request:

{
  "sandbox": {
    "network": {
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    }
  }
}

Troubleshooting

• Lệnh fail với lỗi host-not-allowed: phê duyệt khi được hỏi để thêm host vào allowed list.
• jest treo hoặc fail: watchman không tương thích sandbox. Chạy jest --no-watchman.
• CLI dựa trên Go fail TLS verification trên macOS (gh, gcloud, terraform): thêm vào excludedCommands.
• docker fail: thêm docker * vào excludedCommands.
• --dangerously-skip-permissions fail khi chạy root: bị chặn khi chạy root/sudo trên Linux và macOS vì kết hợp quyền root với không prompt có thể sửa bất kỳ file/service nào.

Giới hạn

Sandboxing giảm rủi ro nhưng không phải ranh giới cô lập hoàn chỉnh.

Giới hạn bảo mật

• Lọc mạng: mặc định proxy không terminate/kiểm tra TLS trên outbound traffic, nên nội dung kết nối mã hoá không được kiểm tra. Cho phép domain rộng như github.com có thể tạo đường rò rỉ dữ liệu qua kỹ thuật domain fronting.
• Leo thang qua Unix socket: allowUnixSockets có thể vô tình cấp quyền truy cập service hệ thống mạnh, ví dụ /var/run/docker.sock cấp quyền truy cập host qua Docker socket.
• Leo thang quyền filesystem: quyền ghi quá rộng có thể dẫn đến leo thang đặc quyền.

Phạm vi

Sandbox chỉ cô lập Bash subprocess. Các tool khác hoạt động theo ranh giới khác:

• Built-in file tool: Read, Edit, Write dùng hệ thống permission trực tiếp thay vì chạy qua sandbox.
• Subagent: chạy trong cùng process với parent session và dùng cùng cấu hình sandbox.

Xem thêm

• Sandbox environments: so sánh sandbox built-in với dev container, container, VM
• Permissions: cấu hình permission và access control
• Settings: tham chiếu cấu hình đầy đủ

Nguồn

Dịch và biên soạn từ Configure the sandboxed Bash tool.