Sandboxing Claude Code on macOS: Stop Yolo Mode Without Losing Power

The first time you let Claude Code do git reset --hard on the wrong branch, you become permission-curious. The second time, you become sandbox-curious. The Anthropic permission prompt is great but it has two failure modes: you click "yes" without reading because you're tired, or you toggle --dangerously-skip-permissions because the prompts annoyed you that day.

macOS has a kernel-enforced sandbox available to every binary. It's called Seatbelt and it's been there since 2007. Apple uses it inside app sandbox. You can use it directly with sandbox-exec. This post is the production version of "I read the man page and built something useful."

Why people skip permissions (and what it costs)

--dangerously-skip-permissions exists because the prompt-on-every-tool-call gets old. The cost is real: an agent decides it needs to clean up node_modules across the whole filesystem, types the wrong path, and you have a bad evening. Sandbox prevents the worst outcome regardless of what the agent decides.

Seatbelt 101

A Seatbelt profile is an S-expression. You declare a default (allow or deny), then add specific allow/deny rules per operation. sandbox-exec -f profile.sb claude runs Claude Code under those rules. The kernel enforces them.

(version 1)
(deny default)
(allow process-fork)
(allow process-exec*)
(allow file-read* (subpath "/"))
(allow file-write* (subpath "/Users/me/CelistraAgents"))
(allow file-write* (subpath "/tmp"))
(allow network*)
(allow mach-lookup
  (global-name "com.apple.system.notification_center"))

That profile reads anywhere, writes only in the workspace + /tmp, runs sub-processes (so git, npm, etc. work), and has network. Drop the network line and you've got an offline agent. Drop subprocess and Claude can read but can't run anything.

The capability-token model

Hand-writing Seatbelt profiles per agent is brittle. Capability tokens make it composable. Each token is a string with a meaning:

• workspace_rw — read+write within the chosen workspace
• read_anywhere — read everywhere on the filesystem
• network — outbound network
• subprocess — fork/exec child processes
• screen_capture — Mach service for CG screen APIs
• accessibility — AX events (drive other apps via AppleScript / control)
• full_disk_access — bypass TCC fences (Mail, Messages, Safari history)
• read:<path> · write:<path> · exec:<path> — granular path grants
• privileged — escape hatch (no profile)

The default bundle is {workspace_rw, read_anywhere, network, subprocess}. That's the right policy 95% of the time: the agent can read your code, run tools, talk to the internet, and not destroy anything outside the workspace.

Per-agent grants

A single config file (~/.celistra_capabilities.json in our daemon's case, but the pattern is generic) lists grants:

{
  "grants": [
    {
      "match": { "agentNamePattern": "screenshot-*" },
      "capabilities": ["screen_capture"]
    },
    {
      "match": { "command": "claude --dangerously-skip-permissions" },
      "capabilities": ["privileged"]
    }
  ]
}

Match block is AND-within-grant; OR-across-grants. An agent named screenshot-friday gets the default bundle plus screen_capture. An agent invoking --dangerously-skip-permissions still drops the sandbox — but you've consented to that explicitly, in version-controlled config, instead of by mashing y/y/y at 11pm.

The audit log

Every spawn writes a row: agent, command, capabilities resolved, profile path, exit code. Every kernel block decision (when the agent tried to write outside the workspace) writes a row. The log is hash-chained — sha256(prev_hash || row) — and verified hourly.

Practically, this means: when something weird happens, you can answer "did the sandbox engage?" with a query, not a guess.

Restart-to-apply for TCC permissions

macOS caches some TCC grants per-process. Granting Screen Recording or Full Disk Access mid-session won't flip to "granted" in your daemon until the daemon is restarted. The daemon should detect this and offer a restart button (we do) — and persist the user's wizard step so the wizard resumes on the right screen after re-exec.

What this doesn't stop

Sandbox is a hard barrier on filesystem and network. It does not stop the agent from making bad commits, leaking secrets in git diff, or being prompt-injected into doing something silly with the capabilities you did grant. Sandbox is a containment story, not a behavior story.

Linux equivalent

For Linux, the equivalent is bubblewrap + namespaces, or firejail. The capability-token concept maps cleanly: same JSON, different profile generator. macOS is where the daily-driver dev box lives so we put the polish there first.

What we ship

This is exactly how Celistra spawns every agent. The default-on sandbox is the v2 daemon's posture. The user can flip the master switch off via the tray ("Sandbox: OFF") for an unrestricted run; the audit log shows when that happened and which agents ran during. Per-agent grants live in ~/.celistra_capabilities.json.