kosa8

Guide · Claude Code on macOS

How do I run Claude Code safely on a Mac?

Updated 2026-10-31

Keep Claude Code in a permission mode that asks before it acts (Manual or acceptEdits) and turn on its built-in /sandbox, which uses macOS Seatbelt to limit where its shell commands can write and which domains they can reach. For a stronger boundary, run Claude Code inside a virtual machine with its own kernel, such as a kosa8 microVM on an Apple silicon Mac, where it sees one project folder and never holds your API key.

01Steps

Choose a permission mode that asks first. Start Claude Code in Manual mode, or acceptEdits if you review diffs as they land. Shift+Tab cycles modes during a session.
Turn on Claude Code's sandbox. Run /sandbox inside a session and pick a mode, or enable it for one session from the shell. Setting allowUnsandboxedCommands to false stops the unsandboxed retry.
Install kosa8 and start its daemon. The installer detects an Apple or Intel chip and checks the download against published fingerprints. kosa8 doctor reports anything missing, such as the virtualization entitlement.
Run Claude Code inside its own microVM. Set your key on the Mac only, preview the plan with --dry-run, then run the claude kit from your project folder. The sandbox is removed when Claude Code exits; your folder keeps its changes.
Or give Claude Code on your Mac the kosa8 plugin. If you keep Claude Code on the host, the plugin starts kosa8 mcp serve locally so Claude can run untrusted code in sandboxes and checkpoint, rewind and fork them. Type these in Claude Code, then run /reload-plugins and check the connection with /mcp.
Review what it did and approve held calls. Every brokered request, allowed or refused, and every tool call is in a hash-chained audit log. Risky calls such as a force push wait in a queue for a person.

02What does Claude Code's /sandbox protect, and what does it not?

On macOS, /sandbox wraps the Bash commands Claude Code runs in Seatbelt: by default they can write only to the working directory and a temp directory, and they reach the network only through a local proxy that allows the domains you list. It is off by default. Claude Code's own Read, Edit and Write tools, hooks and local MCP servers run outside it, reads are allowed across most of the machine (including ~/.ssh) unless you deny them, and a failed command can be retried unsandboxed unless you set allowUnsandboxedCommands to false.

Two settings close most of the gap: sandbox.filesystem.denyRead (or sandbox.credentials) for secrets such as ~/.ssh and ~/.aws/credentials, and sandbox.network.allowedDomains, which starts empty. The docs also list what does not work inside it: docker, SSH git remotes on macOS, and tools that ignore proxy variables.

03Is it safe to use --dangerously-skip-permissions on a Mac?

Not on your main macOS user account. Anthropic's documentation says bypassPermissions, which --dangerously-skip-permissions turns on, should only be used in isolated environments like containers, VMs, or dev containers without internet access, and that it offers no protection against prompt injection or unintended actions.

If you want an agent to run unattended, give it a machine where that advice holds: a VM or container with no access to your home directory, and a network limited to the hosts it needs. Anthropic's lower-prompt alternative is auto mode, which its docs say reduces prompts but does not guarantee safety.

04What does running Claude Code in a microVM add?

A microVM puts a separate kernel and a hypervisor between Claude Code and your Mac. With kosa8, Claude Code sees only the one folder you share, its network is closed except for the hosts its kit names, and the sandbox holds a placeholder instead of your Anthropic API key: a broker on your side adds the real key to requests to api.anthropic.com.

Kernel. Seatbelt is a policy enforced by the macOS kernel that Claude Code shares with everything else on your Mac. A microVM gives the agent a Linux kernel of its own, so a bug it triggers there stays inside the VM.
Every tool, not only Bash. In the VM, file edits, package installs and any MCP server it starts are on the far side of the boundary too.
Checked tool calls. With the claude kit, each tool call is checked against kosa8's rules before it runs: a download piped into a shell is refused, and a force push waits for kosa8 mcp approve.
The shared folder is still shared. Claude Code can change anything in it, including .git and any .env file. Share a project, not your home directory, and commit first.

05Which Macs can run Claude Code in a kosa8 microVM?

Apple silicon Macs. kosa8 runs its virtual machines on Apple's Virtualization framework, using a hypervisor feature Apple ships on its own chips. On an Intel Mac kosa8 installs as the command-line tool only and connects to an Apple silicon Mac or an x86-64 Linux machine that runs the sandboxes.

The kosa8 plugin needs kosa8 on the same machine with kosa8 on your PATH (check with kosa8 version) and the daemon running. Claude Code's /sandbox needs nothing extra on macOS, because Seatbelt is built in.

06Other options

Claude Code's /sandbox alone fits day-to-day work on your own code, with the denyRead and allowedDomains settings above.
A dev container or Docker fits when your team already uses one; Anthropic documents a dev container setup for Claude Code, with an example egress firewall. On a Mac, Docker Desktop runs containers inside a Linux VM.
Docker Sandboxes runs each agent in its own microVM with its own Linux kernel, from Docker's tooling.
A full VM in UTM or Lima fits when you want a general-purpose Linux or macOS guest and are happy to manage it yourself.
Hosted sandboxes such as E2B, Daytona or Modal fit when the agent should run in the cloud rather than on your Mac.

07Sources