Sandboxes on macOS

Set up NVIDIA OpenShell sandboxes on an Apple-silicon Mac, where each sandbox is a MicroVM with its own Linux kernel, the agent works on a copy of your project, and you pull its changes back.

Install and configure OpenShell sandboxes on an Apple-silicon Mac. Each sandbox is a MicroVM with its own Linux kernel. The agent works on a copy of your project, and you bring its changes back when you are happy with them.

How it fits together

hooks, web
model calls
starts
Claude Code or Codexskip-permissions on
OpenShell supervisorthe only way out
DefenseClaw daemonchecks hooks, proxies the web
OpenShell gatewayHomebrew service
A copy of your projectat /sandbox/work/myapp
Internetallowed sites
Model provider

List view for small screens. Use the expand button to open the drawing.

  1. A copy of your projectat /sandbox/work/myapp
    • Claude Code or Codex
  2. Claude Code or Codexskip-permissions on
    • OpenShell supervisor
  3. OpenShell gatewayHomebrew service
    • startsOpenShell supervisor
  4. OpenShell supervisorthe only way out
    • hooks, webDefenseClaw daemon
    • model callsModel provider
  5. Model provider
  6. DefenseClaw daemonchecks hooks, proxies the web
    • Internet
  7. Internetallowed sites
A Mac sandbox. The agent works on a copy of your project inside a MicroVM; nothing reaches your folder until you pull it back.

Before you start

You needDetails
Apple siliconIntel Macs are refused. Under Rosetta, install the arm64 build of DefenseClaw.
DefenseClawInstalled, with the daemon running (quickstart). Run as your own user.
HomebrewYour account must be able to write to Homebrew's folders. OpenShell installs from the nvidia/openshell formula, without sudo.
Xcode or Command Line ToolsCurrent for your macOS release. Homebrew may build from source. They include Git 2.29 or newer, which a copy-mode run uses to copy your project and the pre-session snapshot of a git repository uses; a MicroVM mounts no host folders, so every run on a Mac works on a copy and the row fails without git; defenseclaw sandbox doctor checks it (Host Git).
e2fsprogsSetup offers to install it with Homebrew.
Docker Desktop, runningStart it once on your own account first. It asks for Rosetta, local-network access and an administrator password.
DiskAt least 13 GiB free in the VM volume (24 GiB recommended). The first image build downloads about 3 GB.

OpenShell 0.1.6 or newer is required. Setup installs it, or upgrades an older one, after asking. If another account owns Homebrew, setup stops and names the owner and folder. Ask them for write access, or install a Homebrew of your own in your home directory (below). On a managed Mac an administrator provides OpenShell: Sandboxes on managed computers.

A Homebrew that belongs to another account

Setup stops before installing and names the owner and folder. Have the owner give you write access, or install a Homebrew of your own in your home directory, put it first on PATH with eval "$(~/homebrew/bin/brew shellenv)", and run setup again. With your own Homebrew, e2fsprogs must still come from an administrator's Homebrew under /opt/homebrew or /usr/local.

Set up

Run setup

defenseclaw sandbox setup
DefenseClaw sandbox setup
  Checking this machine…  ✓ darwin/arm64  ✓ Landlock (MicroVM)  ✓ Docker 29.1.5  ✗ OpenShell and its MicroVM driver not installed
Install OpenShell … with NVIDIA's installer? (Homebrew; sha256 verified) [y/N] y
Run sandboxes in OpenShell MicroVMs? macOS needs them: Docker Desktop's Linux kernel has no Landlock. [Y/n]
  ✓ gateway configured and restarted: it runs sandboxes in OpenShell MicroVMs
  every run works on a copy (the MicroVM driver mounts no host folders); `defenseclaw sandbox pull NAME --apply` brings the changes back

  ✓ Done →  cd <project> && defenseclaw sandbox run claude

Setup installs OpenShell and e2fsprogs, switches the gateway to MicroVMs (a backed-up change to its gateway.toml, one restart), turns off OpenShell's usage telemetry, and builds the harness images. The MicroVM settings apply to every sandbox on the gateway. Flags are in the sandbox CLI reference.

You can also run setup from the TUI (defenseclaw tui, 0, Sandboxes (OpenShell)) or the macOS app (Setup, Sandbox). The app never installs OpenShell: run defenseclaw sandbox setup --install-openshell in a terminal first.

DefenseClaw TUI Setup, Sandboxes (OpenShell) form on a Mac: Docker, Landlock through MicroVMs, OpenShell 0.1.5 and the MicroVM driver ticked, the MicroVM settings, OpenShell telemetry off, shell wrappers and build images now

~/code/myapp
Bonus replay, recorded on DefenseClaw 1.0.4 on a Mac (Docker Desktop running in the account's session). First run: the shared Homebrew at /opt/homebrew belongs to another account, so setup stops before installing. Second run, after installing Homebrew into ~/homebrew and putting it first on PATH: the install plan, then the gateway changes, the harnesses and the image build (Homebrew output trimmed).

Check the Mac

defenseclaw sandbox doctor
  ⚠ Platform                   darwin/arm64: macOS sandboxes run in OpenShell MicroVMs (the vm driver, experimental upstream)
  ✓ Docker                     Docker 29.1.5 (Docker Desktop)
  ✓ MicroVM driver             e2fsprogs in /opt/homebrew/opt/e2fsprogs/sbin; …openshell-driver-vm signed for Apple's Hypervisor
  ✓ Gateway compute driver     vm (OpenShell MicroVM; experimental upstream)
  - Project bind mounts        the OpenShell MicroVM (vm) driver mounts no host folders: every run works on a copy
  ✓ Harness images             hook-verified: claudecode 2.1.156, codex 0.146.0
  …

  ✓ ready for sandboxes

The Platform warning is expected on every Mac. Checks marked - do not apply to MicroVMs. defenseclaw sandbox doctor --fix applies fixes that need only your user.

Run your first agent

cd ~/code/myapp
defenseclaw sandbox run claude

The first start of each image takes about a minute while the driver prepares its MicroVM disk. Continue with run an agent and bring the changes back.

Run on a copy

sandbox run copies the project into the sandbox and says what it left out:

Copying ~/code/myapp (secrets are held back)…
Starting a Claude Code sandbox… (the first start prepares its MicroVM disk: about a minute)
Uploading the copy (412 files, 3.1 MiB)…
⚠ 1 secret file held back from the copy: .env
⚠ not copied (git ignores them, or they are package caches): node_modules/, dist/; install the dependencies inside the sandbox

The copy is a shallow git clone (openshell.workdir.git_depth) plus your working tree, up to openshell.workdir.max_upload_mb. Secret files are held back.

Bring the changes back

At the end DefenseClaw brings the work back as a git bundle, checks it and reviews it before anything reaches your folder (pull on macOS).

MicroVM specifics

  • Every MicroVM gets the same 4 vCPUs, 4 GiB of memory and 16 GiB disk for changes, set in the gateway's gateway.toml. --cpu and --memory have no effect.
  • Each image the driver has started keeps about 5 GB in ~/.local/state/openshell/vm-driver. defenseclaw sandbox image prune removes unused ones.

Limits on a Mac

  • There is no live mount and no pre-session snapshot. --context is refused, and sandbox undo reverts the last pull --apply.

One OpenShell gateway per Mac

The gateway listens on 127.0.0.1:17670 for the account that started it, so only that account can run sandboxes. To hand sandboxes to another account, run brew services stop nvidia/openshell/openshell in the first, then setup in the second.

Check it worked

defenseclaw sandbox doctor ends with ready for sandboxes, and its Gateway compute driver row reads vm.

Undo

defenseclaw sandbox teardown removes this install's sandboxes, images and MicroVM disks, restores the gateway configuration from before setup and turns openshell.enabled off. OpenShell stays installed.

Common problems

Run defenseclaw sandbox doctor first. These are the macOS-only failures it reports.

Homebrew belongs to another account

You see: install OpenShell: Homebrew at /opt/homebrew belongs to …, and you (…) cannot write to ….

Cause: NVIDIA's installer runs Homebrew as you, without sudo.

Fix: have its owner give you write access, or use a Homebrew of your own (Mac setup), then run defenseclaw sandbox setup again.

Check: setup passes the install step.

The formula installed but the installer failed

You see: install OpenShell: the nvidia/openshell formula is installed, but NVIDIA's installer failed after it.

Cause: Homebrew installed OpenShell and started its gateway; the installer then failed starting it or registering it.

Fix: setup shows the check that still fails and its fix (on a Homebrew outside /opt/homebrew, openshell gateway add … with OPENSHELL_LOCAL_TLS_DIR set). Run it, then run setup again.

Check: the Gateway registration check passes.

Homebrew could not install the formula

You see: install OpenShell: Homebrew could not install the nvidia/openshell formula.

Cause: read Homebrew's Error: line above it. Most often your developer tools are too old (Your Xcode (26.2) … is too outdated). Homebrew checks /Applications/Xcode.app even when xcode-select selects the Command Line Tools.

Fix: update the tools as Homebrew says, or update or delete that Xcode, then run setup again.

Check: brew list nvidia/openshell/openshell succeeds.

Docker Desktop's VM has no Landlock

You see: the Landlock check reports no Landlock, no sandbox can start on this gateway: it runs sandboxes on the docker driver, or sandbox "<name>" is in error state with → this gateway runs sandboxes on the docker driver.

Cause: the gateway still runs the Docker driver, and Docker Desktop's Linux VM kernel has no Landlock. DefenseClaw refuses this combination before it builds anything.

Fix: run defenseclaw sandbox setup (or sandbox doctor --fix) and answer yes to the MicroVM question. Sandboxes made on the Docker driver cannot start on MicroVMs: setup lists them first, and after the switch they can only be deleted.

Check: the Gateway compute driver row reads vm.

Intel Mac

You see: OpenShell sandboxes do not run on this machine: … Apple silicon only.

Cause: OpenShell's MicroVM driver needs Apple silicon.

Fix: none on this machine. defenseclaw sandbox teardown still removes what an earlier setup left.

Check: not applicable.

The MicroVM driver check fails

You see: MicroVM driver fails with e2fsprogs is not installed where the MicroVM driver looks for it, or the driver is not signed for Apple's Hypervisor.

Cause: the driver formats disks with e2fsprogs and looks only under /opt/homebrew and /usr/local. An unsigned driver needs its post-install step.

Fix: run brew install e2fsprogs, or defenseclaw sandbox setup. With a Homebrew elsewhere, have an administrator install it under one of those prefixes. For the signature run brew postinstall nvidia/openshell/openshell.

Check: the MicroVM driver check passes.

If your organization re-signs openshell-driver-vm with its own Developer ID and the hardened runtime (codesign --options runtime), the Hypervisor entitlement alone is not enough: the driver's bundled libkrun and libkrunfw are ad-hoc signed, so library validation refuses them, and dyld ignores the DYLD_ variables the driver sets. A sandbox then fails with VM process exited with status 1 and the MicroVM driver check still passes. Sign the driver with all three entitlements: com.apple.security.hypervisor, com.apple.security.cs.disable-library-validation and com.apple.security.cs.allow-dyld-environment-variables. OpenShell tracks a fix that needs neither exception in NVIDIA/OpenShell#4772.

Docker Desktop is not running

You see: the Docker check fails, or says Docker Desktop is not running in this account (permission denied ...).

Cause: Docker Desktop is not started on this account.

Fix: log in to the Mac's desktop as this account and start Docker Desktop (never point DOCKER_HOST at another account's socket), then run defenseclaw sandbox image build <harness> --force.

Check: the Docker check passes.

localhost does not resolve in a MicroVM

You see: an image build reports that localhost does not resolve only to loopback, a sandbox fails its workload check before a session, or a harness reports that it cannot resolve localhost.

Cause: OpenShell 0.1.6 fills a missing or empty hosts file at guest startup but preserves a nonempty file supplied by a custom image. That file must let the image and guest resolve localhost only to 127.0.0.1, ::1, or both. An image whose /etc/ld.so.preload names a library is refused too, and so is one whose /etc/nsswitch.conf hosts: line is not files, optionally followed by dns: an NSS module or a DNS answer could replace localhost for some programs.

Fix: update the custom base so its hosts file is empty or supplies a working localhost mapping, remove any /etc/ld.so.preload, set hosts: files dns in /etc/nsswitch.conf, then run defenseclaw sandbox image build <harness> --force. Delete an existing sandbox before running it again.

Check: the new sandbox starts and its hooks reach DefenseClaw.

The first run seems to hang

You see: the run waits at Starting a Claude Code sandbox…, or fails after about 5 minutes with ProvisioningTimedOut: Provisioning repair window expired after 300 seconds.

Cause: the first start of an image prepares a MicroVM disk of about 5 GB, which takes about a minute. The timeout means the volume ran full while the disk was prepared.

Fix: wait a minute. After a timeout, check Disk space in defenseclaw sandbox doctor, then run defenseclaw sandbox image prune. Do not stop a sandbox in the ProvisioningTimedOut or ImagePreparationTimedOut error state: OpenShell refuses the stop while its cleanup runs. Wait a minute, then run defenseclaw sandbox start NAME. On OpenShell older than 0.1.6, first run defenseclaw sandbox setup --install-openshell.

Check: the next start takes a few seconds.

A start fails the identity check

You see: the vm-identity check fails, or a create says the MicroVM driver runs sandboxes as another uid.

Cause: the gateway's sandbox_uid and sandbox_gid are not your uid and gid.

Fix: run defenseclaw sandbox doctor --fix, which sets them and restarts the gateway.

Check: the MicroVM sandbox user row shows your uid.

brew services refuses in tmux

You see: the Gateway service check says `brew services` refuses to run in a tmux session that has no access to this account's macOS login session.

Cause: the tmux session was not started from your desktop session.

Fix: run the doctor outside tmux, or in a tmux you start from Terminal.

Check: the check passes.

The openshell executable is not found

You see: a run ends with import provider profile …: openshell: exec: "openshell": executable file not found in $PATH.

Cause: the daemon started before your shell had the OpenShell CLI on its PATH.

Fix: run defenseclaw sandbox setup again (it records the path as openshell.binary), or run defenseclaw-gateway restart from this shell.

Check: the run starts.

Next