Installation

Install Agent Safehouse CLI and configure shell functions

Agent Safehouse is a single self-contained Bash script with no dependencies beyond macOS built-ins.

Prerequisites

Agent Safehouse requires macOS with sandbox-exec (available on all modern macOS versions).

• macOS (tested on macOS 11+)
• Bash or Zsh shell
• curl for downloading the script

Install the CLI

1. Create local bin directory

   Create a directory for local executables if it doesn’t exist:

   mkdir -p ~/.local/bin
   
2. Download safehouse

   Download the self-contained script from GitHub:

   curl -fsSL https://raw.githubusercontent.com/eugene1g/agent-safehouse/main/dist/safehouse.sh \
     -o ~/.local/bin/safehouse
   

   The dist/safehouse.sh file is a single executable containing assembled policies and runtime logic.

3. Make executable

   Set execute permissions:

   chmod +x ~/.local/bin/safehouse
   
4. Add to PATH

   Ensure ~/.local/bin is in your PATH. Add to ~/.zshrc or ~/.bashrc:

   export PATH="$HOME/.local/bin:$PATH"
   

   Reload your shell:

   source ~/.zshrc  # or source ~/.bashrc
   
5. Verify installation

   Confirm safehouse is accessible:

   which safehouse
   # /Users/you/.local/bin/safehouse
   
   safehouse --help
   

Verify Sandbox Works

Test that the sandbox denies access to sensitive paths:

# Try to read SSH key - should be denied
safehouse cat ~/.ssh/id_ed25519
# cat: /Users/you/.ssh/id_ed25519: Operation not permitted

# Try to list home directory - should be denied
safehouse ls ~
# ls: /Users/you: Operation not permitted

# But current directory works
safehouse ls .
# (lists files in current directory)

If you see “Operation not permitted”, the sandbox is working correctly!

Shell Functions (Recommended)

Shell functions provide convenient shortcuts and machine-specific defaults. Add to ~/.zshrc or ~/.bashrc:

Minimal Setup

# ~/.zshrc or ~/.bashrc
safe() { safehouse "$@"; }
claude() { safe claude --dangerously-skip-permissions "$@"; }
aider() { safe aider "$@"; }

Reload your shell:

source ~/.zshrc  # or source ~/.bashrc

With shell functions, you can type claude instead of safehouse claude --dangerously-skip-permissions.

Bypass Shell Functions

To run the unsandboxed version when needed:

# Use 'command' to bypass the shell function
command claude --dangerously-skip-permissions

Optional: Local Overrides

For machine-specific policy exceptions (e.g., shared folders, team mounts), create a local override file:

1. Create config directory

   mkdir -p ~/.config/agent-safehouse
   
2. Create local overrides file

   Create ~/.config/agent-safehouse/local-overrides.sb:

   ;; Local user overrides
   ;; Host-specific exceptions that should not live in shared repo config
   (allow file-read*
     (home-literal "/.gitignore_global")
     (home-subpath "/Library/Application Support/CleanShot/media")
     (subpath "/Volumes/Shared/Engineering")
   )
   

   Use Sandbox Profile Language (.sb) syntax for custom rules. See Policy Architecture for details.

3. Reference in shell function

   Your shell function (from above) should include:

   export SAFEHOUSE_APPEND_PROFILE="$HOME/.config/agent-safehouse/local-overrides.sb"
   safe() {
     safehouse --append-profile="$SAFEHOUSE_APPEND_PROFILE" "$@"
   }
   

For single files, use --add-dirs-ro instead of creating a profile:

safehouse --add-dirs-ro=~/.gitignore -- claude --dangerously-skip-permissions

Optional: Claude Desktop Launcher

For sandboxing the Claude Desktop app (not CLI), use the pre-built launcher:

1. Download launcher

   # Online launcher (downloads latest policy at runtime)
   curl -fsSL https://raw.githubusercontent.com/eugene1g/agent-safehouse/main/dist/Claude.app.sandboxed.command \
     -o ~/Downloads/Claude.app.sandboxed.command
   chmod +x ~/Downloads/Claude.app.sandboxed.command
   
   # OR offline launcher (embedded policy, no runtime download)
   curl -fsSL https://raw.githubusercontent.com/eugene1g/agent-safehouse/main/dist/Claude.app.sandboxed-offline.command \
     -o ~/Downloads/Claude.app.sandboxed-offline.command
   chmod +x ~/Downloads/Claude.app.sandboxed-offline.command
   
2. Launch from Finder

   Double-click the .command file in Finder to launch Claude.app sandboxed.

   The launcher runs:

   safehouse --workdir="<folder-containing-launcher>" \
     --enable=electron -- \
     /Applications/Claude.app/Contents/MacOS/Claude --no-sandbox
   

The --no-sandbox flag is required because Electron apps cannot be double-sandboxed. The outer Safehouse sandbox provides the protection.

Update Safehouse

To update to the latest version, re-download the script:

curl -fsSL https://raw.githubusercontent.com/eugene1g/agent-safehouse/main/dist/safehouse.sh \
  -o ~/.local/bin/safehouse
chmod +x ~/.local/bin/safehouse

No uninstall needed - just delete ~/.local/bin/safehouse and remove shell functions from your .zshrc/.bashrc.

Next Steps

Quick Start

Get your first sandboxed agent running in 5 minutes

Usage Guide

Learn common patterns and CLI options