Skip to content
Back to search

sandvault

SkillWorks with CodexGitHub

Run AI agents isolated in a macOS user account and sandbox-exec. Configured to run Claude Code, OpenAI Codex, Cursor Agent, Google Gemini.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/webcoyote/sandvault with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/webcoyote/sandvault'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/webcoyote--sandvault/badge.svg)](/listings/webcoyote--sandvault)

HTML

<a href="/listings/webcoyote--sandvault"><img src="/api/listings/webcoyote--sandvault/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install via Homebrew:

brew install sandvault

Install via git:

# Clone the repository
  git clone https://github.com/webcoyote/sandvault

# Option 1: add the sandvault directory to your path
  export PATH="$PATH:/path/to/where/you/cloned/sandvault"

# Option 2: add to your shell configuration for easy access
  echo >> ~/.zshrc  'alias sv="/path/to/where/you/cloned/sandvault/sv"'
  echo >> ~/.bashrc 'alias sv="/path/to/where/you/cloned/sandvault/sv"'

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 631 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # SandVault - Run AI agents and shell commands in a sandboxed macOS user account. Sandboxed web and app testing with Chrome and iOS Simulator.
  2. <img src="https://www.codeofhonor.com/images/projects/sandvault.webp" align="left" width="200px"/>
  3. SandVault (`sv`) manages a limited user account to sandbox shell commands and AI agents, providing a lightweight alternative to application isolation using virtual machines.
  4. </br>
  5. </br>
  6. - **AI ready** - Includes Claude Code, OpenAI Codex, OpenCode, Google Gemini, pi, Muse Code, and the [herdr](https://herdr.dev) agent multiplexer
  7. - **Web and iOS automation** - sandbox access to Chrome / Lightpanda and iOS Simulator
  8. - **Fast context switching** - No VM overhead; instant user switching
  9. - **Passwordless** - switch accounts without a prompt (after setup)
  10. - **Shared workspace** - joint access to `/Users/Shared/sv-$USER`
  11. - **Defense in depth** - limited user account + `sandbox-exec`
  12. - **Clean uninstall** - Complete removal with `sv uninstall`
  13. </br>
  14. </br>
  15. ---
  16. ## Quick Links
  17. 0. Run [Browser Automation](#Browser-Automation) from within the sandbox that can be used for testing web interactions.
  18. 1. Run [iOS Simulator Automation](#iOS-Simulator-Automation) from within the sandbox that can be used for iOS app testing.
  19. 2. To run `xcodebuild` or `swift` see [Sandboxing xcodebuild and swift](#Sandboxing-xcodebuild-and-swift) for details.
  20. 3. To run other sandboxed applications inside sandvault, use the `-x` option. See [Sandboxing other apps](#Sandboxing-other-apps) for details.
  21. 4. It's not possible to run GUI applications from within the sandbox; see [Running GUI Applications](#Running-GUI-Applications) for details.
  22. ## Security Model
  23. SandVault has limited access to your computer:
  24. - Cannot access your home directory
  25. - Runs with standard user privileges
  26. - Cannot modify system files
  27. - Has no access to mounted drives
  28. ```
  29. - writable: /Users/Shared/sv-$USER -- only accessible by you & sandvault-$USER
  30. - writable: /Users/sandvault-$USER -- sandvault's home directory
  31. - readable: /usr, /bin, /etc, /opt -- system directories
  32. - no access: /Users/* -- other user directories
  33. - writable: /Volumes/Macintosh HD -- accessible as per file permissions
  34. - no access: /Volumes/* -- cannot access mounted/remote/network drives
  35. ```
  36. ## Installation
  37. Install via Homebrew:
  38. ```bash
  39. brew install sandvault
  40. ```
  41. Install via git:
  42. ```bash
  43. # Clone the repository
  44. git clone https://github.com/webcoyote/sandvault
  45. # Option 1: add the sandvault directory to your path
  46. export PATH="$PATH:/path/to/where/you/cloned/sandvault"
  47. # Option 2: add to your shell configuration for easy access
  48. echo >> ~/.zshrc 'alias sv="/path/to/where/you/cloned/sandvault/sv"'
  49. echo >> ~/.bashrc 'alias sv="/path/to/where/you/cloned/sandvault/sv"'
  50. ```
  51. ## Quick Start
  52. ```bash
  53. # Run Claude Code in the sandbox
  54. # shortcut: sv cl
  55. sv claude
  56. # Run OpenAI Codex in the sandbox
  57. # shortcut: sv co
  58. sv codex
  59. # Run OpenCode in the sandbox
  60. # shortcut: sv o
  61. sv opencode
  62. # Run Google Gemini in the sandbox
  63. # shortcut: sv g
  64. sv gemini
  65. # Run pi in the sandbox
  66. # shortcut: sv p
  67. sv pi
  68. # Run Muse Code in the sandbox
  69. # shortcut: sv m
  70. sv muse
  71. # Run herdr (many agents, one terminal) in the sandbox
  72. # shortcut: sv hd
  73. sv herdr
  74. # Run command shell in the sandbox
  75. # shortcut: sv s
  76. sv shell
  77. ```
  78. ## Connect via SSH
  79. The default mode for sandvault runs commands as a limited user (basically `sudo -u sandbox-$USER COMMAND`). Sandvault also configures the limited sandvault account so that you can run commands via SSH (`ssh sandbox-$USER@127.0.0.1`), and everything works the same. Use the `-s` or `--ssh` option to use SSH mode with `sv`, or use `tmux` or `screen` for users so inclined.
  80. ```bash
  81. # Run using impersonation
  82. # sv COMMAND
  83. sv gemini
  84. # Run using ssh
  85. # sv -s/--ssh COMMAND
  86. sv --ssh gemini
  87. ```
  88. To let other keys SSH into the sandvault user, drop each public key into its own file in `~/.config/codeofhonor/sandvault/authorized_keys.d/`, then run any `sv` command to apply it:
  89. ```bash
  90. cp ~/.ssh/id_ed25519_laptop.pub ~/.config/codeofhonor/sandvault/authorized_keys.d/laptop
  91. sv build
  92. ```
  93. Those files are the source of truth: sandvault regenerates the sandvault user's `authorized_keys` from them plus its own key on every run, so deleting a file revokes that key on the next run. Files that are not SSH public keys are ignored with a warning, and a private key left there stops the build rather than being copied into the sandbox.
  94. ## Advanced Commands
  95. ```bash
  96. # Run AI agent with optional arguments
  97. # Usage:
  98. # sv <agent> [PATH] [-- AGENT_ARGUMENTS]
  99. # Example:
  100. sv gemini -- --continue
  101. # Run shell command in sandvault and exit
  102. # Usage:
  103. # sv shell [PATH] -- [SHELL_COMMAND]
  104. # Example:
  105. sv shell /Users -- pwd # output: /Users
  106. # Send input via stdin
  107. # Usage:
  108. # <producer> | sv shell [PATH] [-- SHELL_COMMAND]
  109. # Examples:
  110. echo "pwd ; exit" | sv shell /Users # output: /Users
  111. echo ABC | sv shell -- tr 'A-Z' 'a-z' # output: abc
  112. cat PROMPT.md | sv gemini
  113. # Clone local/remote Git repository into /Users/Shared/sv-$USER/repos/<git-repository> and open there
  114. # Usage:
  115. # sv-clone [OPTIONS] URL_OR_LOCAL_PATH [-- SV_ARGS]
  116. # Examples:
  117. sv-clone https://github.com/webcoyote/sandvault.git -- codex
  118. sv-clone ~/src/my-app -- codex
  119. sv-clone https://github.com/webcoyote/sandvault.git -- shell
  120. sv-clone ../my-app -- shell
  121. ```
  122. Use a full or relative path with a directory name for local clones. Everything
  123. after `--` is passed to `sv`, so `sv-clone ~/src/my-app -- claude -- --model opus`
  124. clones the repository and starts Claude Code there. Run `sv-clone --help` for the
  125. full list of options, including `-k`/`-w` to provision a per-repository deploy key.
  126. For local Git repositories, sandvault also wires remotes:
  127. - Your local Git repository gets/updates remote `sandvault` -> `/Users/Shared/sv-$USER/repos/<git-repository>`
  128. - This lets you run `git fetch sandvault` from the original local Git repository to pull commits made in the sandvault Git repository.
  129. ## Native Install
  130. By default, SandVault installs AI tools via Homebrew on the host side. With `--native-install` (`-N`), tools are instead installed inside the sandbox using their own installers:
  131. - **Claude Code** — installed via `curl -fsSL https://claude.ai/install.sh | bash`
  132. - **Codex** — installed via `npm install -g @openai/codex`
  133. - **OpenCode** — installed via `curl -fsSL https://opencode.ai/install | bash`
  134. - **Gemini** — installed via `npm install -g @google/gemini-cli`
  135. - **pi** — installed via `npm install -g @earendil-works/pi-coding-agent`
  136. - **Muse Code** — installed via `curl -fsSL https://dev.meta.ai/install.sh | bash`
  137. - **herdr** — installed via `curl -fsSL https://herdr.dev/install.sh | sh`
  138. Tools are installed on first run and reused on subsequent runs.
  139. ```bash
  140. # Install and run Claude Code natively
  141. sv --native-install claude
  142. sv -N claude
  143. # Works with all AI agents
  144. sv -N codex
  145. sv -N opencode
  146. sv -N gemini
  147. sv -N pi
  148. sv -N muse
  149. sv -N herdr
  150. ```
  151. To make native install the default, set `SANDVAULT_ARGS`:
  152. ```bash
  153. # Add to your shell profile (~/.zshrc, ~/.bashrc, etc.)
  154. export SANDVAULT_ARGS="--native-install"
  155. # Now 'sv claude' uses native install automatically
  156. sv claude
  157. ```
  158. ## Environment Variables
  159. Set `SANDVAULT_ARGS` to supply default arguments that are prepended to the command line:
  160. ```bash
  161. # Add to your shell profile (~/.zshrc, ~/.bashrc, etc.)
  162. export SANDVAULT_ARGS="--verbose --ssh"
  163. # Now these are equivalent:
  164. sv claude
  165. sv --verbose --ssh claude
  166. ```
  167. Shell quoting is supported, so arguments with spaces work:
  168. ```bash
  169. export SANDVAULT_ARGS='shell "/Users/me/my project"'
  170. ```
  171. Explicit command-line arguments are appended after `SANDVAULT_ARGS`, so they are processed afterwards.
  172. ## Maintenance Commands
  173. ```bash
  174. # Build sandvault but do not run a command
  175. sv build
  176. sv b
  177. # Rebuild sandvault, including updating all file permissions and ACLs in the shared volume
  178. sv build --rebuild
  179. sv b -r
  180. # Fix permissions when using a restrictive umask (e.g. 077)
  181. sv --fix-permissions
  182. sv --fix-permissions build
  183. # Uninstall sandvault (does not delete files in the shared volume)
  184. sv uninstall
  185. # Misc commands
  186. sv --version
  187. sv --help
  188. ```
  189. ## Running sandvault from a non-admin user account
  190. Setting up sandvault requires administrative permission to create a new user account, shared directories, a sudoers file, and more, so a standard user account without the ability to run sudo cannot configure sandvault.
  191. It is possible for an administrative user to setup sandvault on behalf of a standard user account (here, `somebody`) by temporarily giving that person administrative rights, then revoking permission afterwards:
  192. ```
  193. # assumes sandvault is already installed via `brew install sandvault`
  194. echo 'somebody ALL=(ALL) NOPASSWD: ALL' | sudo tee /etc/sudoers.d/tmp-somebody
  195. sudo -u somebody -i sv build
  196. sudo rm /etc/sudoers.d/tmp-somebody
  197. ```
  198. ## `agentsview` Integration
  199. [`agentsview`](https://www.agentsview.io) is a dashboard for AI coding agents that shows session history, search, and cost tracking. If you have agentsview installed on the host, `sv-agentsview-setup` mirrors sandbox session data so that it appears next to your host-side sessions.
  200. ```bash
  201. # Detect agentsview, prompt to opt in, and configure
  202. sv-agentsview-setup
  203. ```
  204. You are prompted once, on the first run. After that, `sv-agentsview-setup` re-syncs on every run. It installs the mirror symlinks and adds the missing scan paths to `~/.agentsview/config.toml`. New agents that sandvault adds in a later release appear the next time you run the command. When a new scan path is added, the command shows a diff and asks for confirmation. If you decline, that agent is skipped permanently. Remove its key from `/Users/Shared/sv-$USER/_sandvault/setup/agentsview-declined.keys` to enable it again.
  205. Then run `agentsview serve`. You will see your sandvault AI sessions in the `agentsview` dashboard.
  206. ## Running many agents with herdr
  207. [herdr](https://herdr.dev) is a terminal multiplexer for coding agents: run several agents as panes in one session, with a sidebar showing which are working, blocked or done.
  208. ```bash
  209. sv herdr # start, or reattach to, herdr in the sandbox
  210. sv herdr -- --session experiments # arguments after -- go to herdr (separate server)
  211. ```
  212. Detach with `ctrl+b q`; the panes keep running and the next `sv herdr` reattaches.
  213. herdr runs a background server that **outlives the `sv` command**, and every pane is a child of that server. So panes keep the sandbox and environment of the session that first started the server, not of the session that later attaches:
  214. - `--no-sandbox` is refused with herdr: an unsandboxed first launch would leave every later pane unsandboxed too. Running `herdr` from inside `sv -x shell` is refused for the same reason.
  215. - `--chrome` and `--ios` are refused with herdr. Their endpoints are torn down when you detach, but the server's panes would keep the stale `SV_BROWSER_ENDPOINT` / `SV_IOS_SIMULATOR_ENDPOINT`. Run `sv --lightpanda herdr`, as the lightpanda browser runs inside the sandbox.
  216. - The starting directory and `-N` setting are also fixed when the server starts. Use `-- --session NAME` for a separate server.
  217. herdr can install state-reporting hooks into other agents (`herdr integration install claude`). This is not done automatically because it edits those agents' config files; run each agent once first so its config folder exists.
  218. ## Nested sandboxes
  219. In addition to running in a different macOS user account, sandvault also runs applications using macOS `sandbox-exec`, which further limits what resources are accessible.
  220. Some applications, like `swift`, already run inside a sandbox. Because macOS does not support nested (i.e. recursive) sandboxes, these applications fail to run.
  221. Read on for solutions.
  222. ### Sandboxing xcodebuild and swift
  223. For `swift` (and `xcodebuild`, which runs `swift`), you can set the following variables in your build scripts to run inside sandvault:
  224. For `swift`:
  225. ```bash
  226. ARGS=()
  227. # Disable sandboxing when running inside sandvault to avoid nested sandbox-exec
  228. if [[ -n "${SV_SESSION_ID:-}" ]]; then
  229. ARGS+=(--disable-sandbox)
  230. fi
  231. swift build "${ARGS[@]}" "$@"
  232. ```
  233. For `xcodebuild`:
  234. ```bash
  235. ARGS=()
  236. # Disable sandboxing when running inside sandvault to avoid nested sandbox-exec
  237. if [[ -n "${SV_SESSION_ID:-}" ]]; then
  238. export SWIFTPM_DISABLE_SANDBOX=1
  239. export SWIFT_BUILD_USE_SANDBOX=0
  240. ARGS+=("-IDEPackageSupportDisableManifestSandbox=1")
  241. ARGS+=("-IDEPackageSupportDisablePackageSandbox=1")
  242. # shellcheck disable=SC2016 # Expressions don't expand in single quotes # that is intentional
  243. ARGS+=('OTHER_SWIFT_FLAGS=$(inherited) -disable-sandbox')
  244. fi
  245. xcodebuild \
  246. build \
  247. "${ARGS[@]}" \
  248. ...
  249. ```
  250. ### Sandboxing other apps
  251. If the app you intend to run does not support disabling the use of sandbox-exec like `xcodebuild` and `swift` you can run sandvault without `sandbox-exec`:
  252. ```bash
  253. # Disable use of sandbox-exec (app still runs as sandvault user) using -x / --no-sandbox
  254. sv -x claude
  255. sv --no-sandbox codex
  256. sv --no-sandbox shell $HOME/projects/my-app -- xcodebuild ...
  257. ```
  258. Disabling `sandbox-exec` has the following security implications:
  259. - No protection against reading/writing removable drives (`/Volumes/...`)
  260. - No protection against writing files with `o+w` (`0002`) file permissions
  261. ```bash
  262. # To find all files on your computer that are "world writable" (perms: `o+w` / 0002)
  263. # run this command from your account (not in sandvault):
  264. find / \
  265. -path "/Users/sandvault-$USER" -prune \
  266. -o -path "/Users/sv-$USER" -prune \
  267. -o -perm -o=w -print 2>/dev/null
  268. ```
  269. ## Troubleshooting
  270. If your sandbox is misbehaving you can fix it with a rebuild or uninstall/reinstall. They're both safe and will not delete files in the shared sandbox folder.
  271. ```bash
  272. # Force rebuild
  273. sv --rebuild build
  274. # Uninstall then reinstall
  275. sv uninstall
  276. sv build
  277. ```
  278. ### Fix the security popup
  279. ![macOS security keychain login dialog](https://webcoyote.github.io/images/shared/sandvault/security-keychain.jpg)
  280. If you see a security popup above, it may be because files in the shared sandvault directory don't have the correct ACLs, which occurs when another user's files are copied into the sandvault shared directory (`/Users/Shared/sv-$USER`). This can be corrected by running the rebuild command `sv --rebuild build`, or adding the rebuild flag to any command, e.g. `sv -r shell`. This only needs to be done once.
  281. ### Fix permission errors from restrictive umask
  282. If you see "Permission denied" errors when running `sv`, your shell may have a restrictive `umask` (e.g., `077` instead of the default `022`). Check with:
  283. ```bash
  284. umask
  285. ```
  286. SandVault detects this and warns you. To fix it for the current session, add `--fix-permissions`:
  287. ```bash
  288. # Fix permissions (standalone or with build)
  289. sv --fix-permissions
  290. sv --fix-permissions build
  291. ```
  292. If you previously installed Homebrew under a restrictive umask, you may also need to fix its directory permissions:
  293. ```bash
  294. sudo chmod -R o+rX /opt/homebrew
  295. ```
  296. ## Custom Shell Configuration
  297. If you're using `sandvault`, you're probably the type of person who also sets custom shell configuration files, and you'd be disappointed if you had to use default zsh while running `sv shell`. Here's how to configure your custom configuration for sandvault:
  298. 1. Ensure sandvault has been installed by running a command like `sandvault build`, `sandvault shell`, `sandvault claude`, etc.
  299. 2. Copy your desired configuration files (e.g. `.zshrc`, `.zprofile`, etc.) to `/Users/Shared/sv-${USER}/user/`.
  300. Next time you run sandvault, your files will be copied to the sandvault user home directory, and your zsh configuration files will be sourced:
  301. .zshenv → .zprofile → .zshrc
  302. NOTE: .zlogin and .zlogout not supported
  303. > **Note:** Earlier versions of sandvault supported configuration files in `guest/home/user/`, which didn't work for Homebrew installations. Consequently, this is no longer supported, and you'll get an error message asking you to move `guest/home/user` to `/Users/Shared/sv-${USER}/user/`.
  304. ## Browser Automation
  305. SandVault supports a headless browser for automation from within the sandbox. The browser runs inside the sandbox as the sandvault user, so it can only read and write the same files the sandbox can, and agents connect to it via the Chrome DevTools Protocol (CDP) over localhost. Two backends are supported: **Lightpanda** (default) and **Chrome**.
  306. > **Chrome:** macOS does not let Chrome apply its own internal sandbox inside the
  307. > sandvault sandbox, so Chrome is launched with `--no-sandbox`. A malicious web page
  308. > that exploits a Chrome bug would get the sandvault user's access, the same access
  309. > the agent already has, rather than Chrome's tighter per-page sandbox.
  310. > **Muse Code:** `sv --browser muse` starts the browser, but muse is not told the
  311. > endpoint exists — it is the one agent with no way to inject a system prompt. The
  312. > `SV_BROWSER_ENDPOINT` variable below is still set in its environment, so mention
  313. > it in your prompt or the project's `AGENTS.md` to make muse aware of it.
  314. ### Usage
  315. ```bash
  316. # Launch with browser support (Lightpanda by default)
  317. sv --browser claude
  318. sv --browser shell
  319. # Explicit backend selection
  320. sv --lightpanda claude # same as --browser
  321. sv --chrome claude # use Chrome instead of Lightpanda
  322. ```
  323. Inside the sandbox, the `SV_BROWSER_ENDPOINT` environment variable contains the CDP endpoint URL (e.g. `http://127.0.0.1:52858`).
  324. ```javascript
  325. // Playwright
  326. const browser = await chromium.connectOverCDP(process.env.SV_BROWSER_ENDPOINT);
  327. // Puppeteer
  328. const browser = await puppeteer.connect({ browserURL: process.env.SV_BROWSER_ENDPOINT });
  329. ```
  330. See also [`./tests/chrome/*.js`](./tests/chrome) and [`./tests/lightpanda/*.js`](./tests/lightpanda) for examples of using Playwright and Puppeteer. See [`guest/home/bin/prompts/browser.md`](./guest/home/bin/prompts/browser.md) for prompt.
  331. ### How it works
  332. - The browser is launched headless on the host side (one per sandvault session), and the sandbox connects via `localhost`.
  333. ## iOS Simulator Automation
  334. SandVault can expose the iOS Simulator to sandboxed AI agents for iOS app testing. The simulator runs on the host (it is a GUI app and cannot run inside the sandbox), and an HTTP bridge on localhost translates sandbox-side requests into `xcrun simctl` and [`iosef`](https://github.com/riwsky/iosef) invocations.
  335. > **Muse Code:** `sv --ios muse` boots the simulator, but muse is not told the
  336. > bridge exists — it is the one agent with no way to inject a system prompt. The
  337. > `SV_IOS_SIMULATOR_ENDPOINT` variable below is still set in its environment, so
  338. > mention it in your prompt or the project's `AGENTS.md`.
  339. ### Usage
  340. ```bash
  341. # Launch with iOS Simulator support
  342. sv --ios claude
  343. sv --ios shell
  344. ```
  345. Add `--ios-gui` to also show the Simulator.app window — useful when debugging interactively or watching an agent's actions:
  346. ```bash
  347. sv --ios-gui shell
  348. ```
  349. Simulator.app is left running on session exit so that other simulators (yours or other tools') aren't disrupted.
  350. Inside the sandbox, the `SV_IOS_SIMULATOR_ENDPOINT` environment variable points at the HTTP bridge (e.g. `http://127.0.0.1:52861`).
  351. ```bash
  352. # Check if simulator is ready
  353. curl $SV_IOS_SIMULATOR_ENDPOINT/ready
  354. # Read the accessibility tree
  355. curl $SV_IOS_SIMULATOR_ENDPOINT/describe
  356. # Tap a button by accessibility name
  357. curl -X POST -H 'Content-Type: application/json' \
  358. -d '{"name":"Sign In"}' \
  359. $SV_IOS_SIMULATOR_ENDPOINT/tap
  360. # Launch an app by bundle id
  361. curl -X POST -H 'Content-Type: application/json' \
  362. -d '{"bundle_id":"com.apple.Preferences"}' \
  363. $SV_IOS_SIMULATOR_ENDPOINT/launch
  364. # Save a screenshot as JPG (point resolution)
  365. curl -o low_res.jpg $SV_IOS_SIMULATOR_ENDPOINT/view
  366. # Save a screenshot as PNG (pixel resolution)
  367. curl -o high_res.png $SV_IOS_SIMULATOR_ENDPOINT/view_pixels
  368. ```
  369. See [`guest/home/bin/prompts/ios-simulator.md`](./guest/home/bin/prompts/ios-simulator.md) for the full list of endpoints. This file is automatically included in your AI agent prompt when using --ios/--ios-gui. See [`tests/ios-simulator/scripts/tests`](./tests/ios-simulator/scripts/tests) for a runnable example.
  370. ### How it works
  371. - A fresh scratch simulator (named `sandvault-<session-id>`) is created and booted on the host for each `--ios` session, and deleted on exit.
  372. - A Python HTTP bridge (`helpers/sv-ios-bridge`) listens on a dynamic localhost port and fronts a whitelisted set of `iosef` and `xcrun simctl` subcommands.
  373. - `.app` bundles passed to `/install` must live under `/Users/Shared/` (so the sandbox user can already access them); the bridge rejects paths outside that tree.
  374. - All subprocess calls use explicit argv lists, not shells.
  375. ### Requirements
  376. - Xcode with at least one iOS runtime installed (Xcode → Settings → Platforms).
  377. - Homebrew (used to install `uv`, which installs `iosef`). sandvault installs both automatically on first use.
  378. ## Running GUI Applications
  379. TL;DR: Sorry, macOS security limitations prevent this from working.
  380. It would be great to be able to run GUI applications (e.g. browsers, Claude Desktop) in the sandbox account to limit their access to main account resources.
  381. The issue seems to be that an application cannot report to a WindowServer that's owned by a different user.
  382. Internet posts suggest it's possible using `sudo su`, `sudo launchctl asuser`, and `sudo launchctl bsexec`, but those answers are from long ago and it seems likely that Apple improvements to macOS security have closed those doors.
  383. In the event you do find a solution, send a PR please :)
  384. ## Why SandVault?
  385. After exploring Docker containers, Podman, sandbox-exec, and virtualization, I needed something that:
  386. - Works natively on macOS without virtualization overhead
  387. - Provides meaningful isolation without too much complexity
  388. - Runs Claude Code with `--dangerously-skip-permissions`
  389. - Runs OpenAI Codex with `--dangerously-bypass-approvals-and-sandbox`
  390. - Runs OpenCode with `OPENCODE_PERMISSION='{"*":"allow"}'`
  391. - Runs Google Gemini with `--yolo`
  392. - Runs pi with `--approve` to trust project-local files (pi needs no permission bypass)
  393. - Runs Muse Code with `--yolo`, which disables both its approval prompts and its own sandbox — sandvault is already the sandbox, and muse's nested one defaults to proxy-only network and workspace-only writes
  394. - Runs herdr unmodified (it is a multiplexer, not an agent) and refuses to run it without the sandbox or with `--browser` / `--ios`, because its server outlives the session
  395. - Automates Chrome for web testing (via Chrome DevTools Protocol)
  396. - Automated iOS Simulator for app testing (via `xcrun simctl`, and `iosef`)
  397. - Maintains a clean separation between trusted and untrusted code
  398. SandVault uses macOS's Unix heritage and user account system to create a simple but effective sandbox.
  399. # Alternatives
  400. - [ClodPod](https://github.com/webcoyote/clodpod) runs Claude Code inside a macOS virtual machine.
  401. - [Chamber](https://github.com/cirruslabs/chamber) is a proof-of-concept app for running Claude Code inside a macOS virtual machine.
  402. - [Claude Code Sandbox](https://github.com/textcortex/claude-code-sandbox) runs Claude Code in a Docker container (Linux)
  403. # License
  404. Apache License, Version 2.0
  405. SandVault Copyright © 2026 Patrick Wyatt
  406. See [LICENSE.md](LICENSE.md) for details.
  407. # Contributors
  408. We welcome contributions and bug reports.
  409. See [CONTRIBUTORS.md](CONTRIBUTORS.md) for the list of contributors to this project.
  410. # Thanks to
  411. This project builds on the great works of other open-source authors:
  412. - [Claude](https://www.anthropic.com/claude) - AI coding assistant
  413. - [Codex](https://openai.com/codex/) - AI coding assistant
  414. - [CMux](https://github.com/manaflow-ai/cmux) - an awesome terminal
  415. - [Ghostty](https://ghostty.org) - an awesome terminal & terminal library
  416. - [Homebrew](https://brew.sh): 🍺 The missing package manager for macOS (or Linux)
  417. - [Shellcheck](https://www.shellcheck.net): finds bugs in your shell scripts
  418. - [uv](https://docs.astral.sh/uv/): An extremely fast Python package and project manager, written in Rust
  419. - [Claude Code Hooks Mastery](https://github.com/disler/claude-code-hooks-mastery): Quickly master how to use Claude Code hooks to add deterministic (or non-deterministic) control over Claude Code's behavior
  420. - [StatusLine](https://gist.github.com/dhkts1/55709b1925b94aec55083dd1da9d8f39): project status information for Claude Code
  421. ... as well as GNU, BSD, Linux, curl, Git, Sqlite, Node, Python, netcat, jq, and more. "We stand upon the shoulders of giants."

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.