SandVault provides a lightweight, macOS-native solution for running AI agents and shell commands within an isolated, sandboxed user account. It offers a secure environment for executing untrusted code or interacting with AI models like Claude Code, OpenAI Codex, and Google Gemini, serving as a more efficient alternative to full virtual machines.

How It Works

SandVault leverages macOS's user account system and the sandbox-exec utility to create a restricted environment. It operates by managing a dedicated, limited user account (sandbox-$USER) with specific read/write permissions to system directories and a shared workspace (/Users/Shared/sv-$USER), while strictly denying access to the host's home directory and other user accounts. This approach enables fast context switching and passwordless account management without the overhead of virtualization.

Quick Start & Requirements

• Installation: Install via Homebrew (brew install sandvault) or clone the repository and add the sv script to your PATH or shell configuration.
• Primary Run Commands: Execute AI agents like sv cl (Claude), sv co (Codex), sv g (Gemini), or run a shell with sv shell.
• Prerequisites: macOS is required. For browser automation, Google Chrome/Chromium must be installed in /Applications/. For iOS Simulator automation, Xcode with an iOS runtime is necessary.
• Links: GitHub Repository

Highlighted Details

• AI Agent Integration: Pre-configured for popular AI coding assistants including Claude Code, OpenAI Codex, OpenCode, and Google Gemini.
• Web & Mobile Automation: Supports headless Chrome browser automation via Chrome DevTools Protocol (CDP) and iOS Simulator automation using xcrun simctl and an HTTP bridge.
• SSH Access: Commands can be executed remotely via SSH to the sandboxed user account using the --ssh flag.
• Native Tool Installation: An option (--native-install or -N) allows AI tools to be installed directly within the sandbox using their native installers.
• Git Repository Management: Supports cloning Git repositories into the sandbox and setting up remotes for synchronization with local repositories.

Maintenance & Community

The project welcomes contributions and bug reports, with contributors listed in CONTRIBUTORS.md. Specific community channels like Discord or Slack are not detailed in the README.

Licensing & Compatibility

SandVault is licensed under the Apache License, Version 2.0. This license is permissive and generally compatible with commercial use and linking within closed-source projects.

Limitations & Caveats

Running GUI applications directly from within the sandbox is not supported due to macOS security restrictions related to WindowServer interaction. Tools that employ their own sandboxing mechanisms (e.g., swift, xcodebuild) may require explicit disabling of SandVault's sandbox-exec (-x or --no-sandbox flag) to avoid nested sandbox conflicts, which has security implications including reduced protection for removable drives.