webcoyote/sandvault

SandVault – sandboxed AI agents and shell commands on macOS

What it is – SandVault (sv) is a command‑line utility that creates a lightweight, restricted macOS user account and runs commands (including AI coding agents such as Claude, Codex, Gemini, etc.) inside that account. It combines macOS sandbox‑exec with a separate user to give a VM‑like isolation without the overhead of a full virtual machine.

Key capabilities

• AI‑ready – one‑click shortcuts to launch popular coding agents (Claude, OpenAI Codex, OpenCode, Google Gemini, pi, Muse Code) either from the host or inside the sandbox.
• Web & iOS automation – the sandbox can talk to a headless Chrome (or Lightpanda) instance on the host via the Chrome DevTools Protocol, and can also control an iOS Simulator through an HTTP bridge, enabling automated UI testing of web pages and iOS apps.
• Fast context switching – because it only switches macOS users, starting a sandboxed session is near‑instant, unlike spinning up a VM.
• Password‑less switching – after the initial setup the sandbox user can be impersonated (sudo -u sandbox‑$USER …) or accessed over SSH without interactive passwords.
• Shared workspace – a directory under /Users/Shared/sv‑$USER is writable by both the main and sandbox accounts, making it easy to exchange files or Git repositories.
• Defense‑in‑depth – the sandbox user has no access to your home folder, other users, mounted drives, or system files; only a few read‑only system paths are visible.
• Clean uninstall – sv uninstall removes the sandbox user and all its files, leaving the shared workspace untouched.

How you use it

# launch Claude inside the sandbox
sv claude
# run a shell command inside the sandbox
sv shell /Users -- pwd
# clone a repo into the shared area and start an agent there
sv-clone https://github.com/example/repo.git -- codex

You can also add --ssh to run commands via an SSH connection to the sandbox user, or set SANDVAULT_ARGS to make options like --native-install (install agents inside the sandbox) the default.

Installation – Available via Homebrew (brew install sandvault) or by cloning the repo and adding the sv script to your $PATH.

Advanced features

• Native install – agents can be installed inside the sandbox using their own installers (sv -N claude).
• Browser automation – start a headless Chrome (or Lightpanda) and connect from the sandbox using the SV_BROWSER_ENDPOINT environment variable; works with Playwright or Puppeteer.
• iOS Simulator automation – a fresh simulator is launched on the host and exposed through an HTTP bridge (SV_IOS_SIMULATOR_ENDPOINT). You can query the accessibility tree, tap elements, launch apps, and capture screenshots via simple curl commands.
• SSH key management – drop public keys into ~/.config/codeofhonor/sandvault/authorized_keys.d/ and SandVault will rebuild the sandbox user’s authorized_keys automatically.
• AgentsView integration – if you use the AgentsView dashboard, sv‑agentsview‑setup mirrors sandbox session data so you can see AI‑agent activity alongside host‑side sessions.

Limitations

• GUI apps cannot run inside the sandbox because macOS prevents a different user from connecting to the WindowServer.
• Nested sandbox‑exec is not supported; for tools like swift you must disable their internal sandboxing via environment flags or run SandVault with --no‑sandbox (-x).

Who it’s for – developers who want to experiment with powerful AI coding agents or automate browsers/iOS simulators while keeping those tools isolated from their main macOS environment. It’s especially useful on macOS where Docker‑style containers are heavyweight or unavailable.

---

TL;DR – SandVault is a macOS‑only CLI that creates a restricted user account, lets you run AI coding agents, shell commands, headless Chrome, and iOS Simulator automation in a sandbox, and provides easy install/uninstall via Homebrew.