Skip to main content
Agent Safehouse provides two primary modes: policy generation and execute mode. This guide covers the most common workflows.

​
Quick Start

1

Generate a policy file

Run Safehouse without a command to generate a sandbox policy:
safehouse
This prints the path to a generated policy file. You can inspect the policy or pass it to your own sandbox-exec invocation.
Use --stdout to print the policy text directly instead of the file path.
2

Run a command in the sandbox

Pass a command after -- to execute it inside the sandbox:
safehouse -- claude --dangerously-skip-permissions
The policy is generated, the command runs inside it, and the policy file is cleaned up automatically.
3

Enable optional integrations

Enable additional features like Docker, clipboard, or GUI access:
safehouse --enable=docker -- docker ps
safehouse --enable=clipboard,macos-gui -- cursor

​
Common Workflows

​
View Policy Text

Print the generated sandbox policy to stdout: 
safehouse --stdout
This is useful for understanding what permissions are granted, debugging issues, or sharing policy configurations.
When using --stdout, the command (if provided) is not executed. This mode only generates and displays the policy.

​
Execute Mode

Run commands inside the sandbox with various permission grants: 
# Run a command with default workdir grants
safehouse -- npm test

​
Grant Additional Paths

Grant read-only or read/write access to additional directories:
Read-only access
# Grant read access to multiple directories (colon-separated)
safehouse --add-dirs-ro="$HOME/shared:$HOME/references" -- claude
Read/write access
# Grant write access to build output
safehouse --add-dirs="$HOME/build-output" -- npm run build
Paths in --add-dirs-ro and --add-dirs are colon-separated (:) on macOS, similar to PATH variables.

​
Preserve Policy Files

Save the generated policy to a specific file: 
safehouse --output=/tmp/my-policy.sb -- /usr/bin/true
When --output is specified, the policy file is preserved after execution instead of being deleted.

​
Profile Detection

Safehouse automatically loads agent and app profiles based on the command you’re running:

CLI Agents

Profiles are detected by command name:
safehouse -- claude    # Loads claude.sb
safehouse -- cursor    # Loads cursor.sb
safehouse -- aider     # Loads aider.sb

App Bundles

App profiles are detected from .app bundles:
safehouse -- open -a Claude  # Loads claude.app.sb
Use --explain to see which profiles were loaded and why. This is helpful for debugging permission issues.

​
Environment Variables

By default, Safehouse runs commands with a sanitized environment containing only safe defaults. You can customize this behavior:

​
Pass-through Mode

Inherit all environment variables from the host: 
safehouse --env -- node build.js
--env passes all environment variables, including secrets. Use carefully with untrusted code.

​
Load from File

Start with sanitized defaults and overlay variables from a file: 
safehouse --env=/path/to/env.sh -- npm test
The file is sourced by /bin/bash, so use shell syntax:
.env.sh
export DATABASE_URL="postgresql://localhost/testdb"
export API_KEY="test-key"

​
Pass Specific Variables

Add individual variables to the sanitized environment:
Single variable
safehouse --env-pass=API_KEY -- node script.js
Multiple variables
safehouse --env-pass=API_KEY,DATABASE_URL -- npm test
--env-pass is compatible with --env=FILE but not with --env (full pass-through).

​
Debugging and Inspection

​
Explain Mode

Print detailed information about the policy generation: 
safehouse --explain --stdout
This shows:
  • Effective working directory and source
  • Read-only and read/write path grants
  • Loaded agent/app profiles
  • Optional integrations included
  • Config file status (loaded, ignored, or not found)

​
Sandbox Denial Logs

When operations fail due to sandbox restrictions, check the system logs: 
/usr/bin/log stream --style compact --predicate 'eventMessage CONTAINS "Sandbox:" AND eventMessage CONTAINS "deny("'
Run this in a separate terminal while executing your sandboxed command to see real-time denial events.

​
Typical Patterns

​
Local Development

Run tests in sandbox
cd ~/my-project
safehouse -- npm test

​
Multi-Tool Workflows

Git + Docker + Agent
safehouse --enable=docker -- claude --dangerously-skip-permissions
Git and common SCM tools are enabled by default. You don’t need --enable=git.

​
Read-Only Project Access

Review mode
safehouse --workdir="" --add-dirs-ro="$HOME/project" -- claude
This grants read-only access to the project without any write permissions.

​
Command Separator

The -- separator is optional but recommended: 
safehouse --enable=docker -- docker ps -a
The separator makes it explicit where Safehouse options end and the wrapped command begins. This prevents ambiguity when command arguments look like flags.

​
Exit Codes

Safehouse preserves the exit code of the wrapped command: 
safehouse -- /bin/sh -c 'exit 42'
echo $?  # Prints: 42
If Safehouse itself encounters an error (invalid options, missing files, etc.), it exits with a non-zero code before executing the command.

Build docs developers (and LLMs) love

Get started for freeTalk to us