claude-sandbox: Yet another sandboxing tool for Claude Code on macOS

Source: Dev.to

Introduction

This post walks through claude‑sandbox, a small tool built to provide predictable, low‑friction sandboxing for Claude Code on macOS.

Claude Code ships with a built‑in sandboxing feature, but it:

• Blocks legitimate operations in unexpected ways, making troubleshooting time‑consuming.
• Includes network isolation, which isn’t needed for many use cases and adds unnecessary complexity.

What you often want is simple: restrict file writes to the current project directory, with an easy way to allow exceptions when needed. That’s exactly what claude‑sandbox does.

How It Works

claude‑sandbox wraps the claude command and runs it under macOS’s sandbox‑exec (Apple Seatbelt—the same technology used in Claude Code’s built‑in sandbox).

The default policy:

1. Allow everything.
2. Deny all file writes.
3. Re‑allow writes to a few specific paths:
   • the current working directory,
   • ~/.claude,
   • /tmp.

If Claude Code tries to write outside those boundaries, the OS blocks the operation.

You can customize the policy by providing your own profile in TOML, but the defaults work out‑of‑the‑box.

Installation

brew install kohkimakimoto/tap/claude-sandbox

Usage

claude‑sandbox is a drop‑in replacement for the claude command.

# Before
claude --dangerously-skip-permissions

# After
claude-sandbox --dangerously-skip-permissions

Now Claude Code runs inside a sandbox that restricts where it can write files.

Example: blocked write

❯ write current time into ~/now.txt

⏺ Bash(date > ~/now.txt && cat ~/now.txt)
  ⎿  Error: Exit code 1
     (eval):1: operation not permitted: /Users/kohkimakimoto/now.txt

The sandbox prevents write access to the home directory. Use the Write tool (or adjust the policy) if you need to write elsewhere.

Configuration

You don’t need a config file to get started—the built‑in defaults are sufficient.
If you want to customize things, generate a configuration file:

# Project‑specific config
claude-sandbox init

# Global config
claude-sandbox init-global

Both commands create a .claude/sandbox.toml file. Example content:

[sandbox]
profile = '''
(version 1)
(allow default)
(deny file-write*)
(allow file-write*
    (subpath (param "WORKDIR"))
    (regex (string-append "^" (param "HOME") "/\\.claude"))
    (subpath "/tmp")
)
'''

[unboxexec]
allowed_commands = [
    "^playwright-cli",
]

The policy is written in the sandbox‑exec policy language (a Scheme‑like DSL). Two parameters are automatically injected:

• WORKDIR – the directory where you ran claude‑sandbox
• HOME – your home directory

To see the active profile:

claude-sandbox profile

Unboxexec: Running Commands Outside the Sandbox

Some tools (e.g., Playwright for browser automation) have their own sandboxing and conflict with macOS sandboxing. claude‑sandbox solves this with unboxexec:

1. When claude‑sandbox starts, it launches a small daemon outside the sandbox.
2. Claude Code, running inside the sandbox, can request the daemon to execute a command.
3. The daemon runs the command outside the sandbox and returns the result.

The daemon only executes commands that match the regex patterns in [unboxexec].allowed_commands. By default, everything is rejected.

Using unboxexec

claude-sandbox unboxexec -- playwright-cli open https://example.com

Add the allowed pattern to your config if needed:

[unboxexec]
allowed_commands = [
    "^playwright-cli",
]

Rules File

Claude Code doesn’t automatically know it’s running in a sandbox. To help it understand the available capabilities, add a rules file.

The repository includes an example at rules/sandbox.md. Copy its contents to one of the following locations:

• Project‑specific: .claude/rules/sandbox.md
• Global: ~/.claude/rules/sandbox.md

Adjust the file based on which commands you’ve allowed via unboxexec.

Summary

claude‑sandbox provides a practical middle ground:

• Full read and execute permissions for Claude Code.
• File writes safely scoped to your project directory.
• No network lockdown, no complex configuration to troubleshoot.

A straightforward constraint that addresses the most common concern for macOS users.

GitHub: