Skip to main content
Agent Safehouse operates in two distinct modes depending on whether you provide a command to execute.

​
Policy Mode

Generates a sandbox policy file without executing a command. Use this mode when you want to inspect the policy or pass it to your own sandbox-exec invocation. 
safehouse [policy options]
Generates a temporary policy file and prints its path to stdout. Example: 
# Generate policy and capture path
policy_path=$(safehouse --enable=docker)

# Use with your own sandbox-exec command
sandbox-exec -f "$policy_path" -- /usr/bin/true

​
Print Policy Content

safehouse --stdout [policy options]
Prints the generated policy content directly to stdout instead of creating a file. Example: 
# View the policy text
safehouse --stdout

# View policy with integrations enabled
safehouse --stdout --enable=docker,kubectl

# Save policy to a file
safehouse --stdout > my-policy.sb
Policy mode is useful for:
  • Inspecting generated policies before execution
  • Debugging sandbox behavior
  • Creating reusable policy files
  • Understanding what permissions are granted

​
Execute Mode

Generates a sandbox policy and immediately executes the specified command inside that sandbox.

​
Basic Execution

safehouse [policy options] -- <command> [args...]
The -- separator is recommended to clearly distinguish policy options from command arguments. Examples: 
# Run Claude CLI in sandbox
safehouse -- claude --dangerously-skip-permissions

# Run with Docker integration
safehouse --enable=docker -- docker ps

# Run with custom workdir
safehouse --workdir=/path/to/project -- npm test

​
Execution Without Separator

safehouse [policy options] <command> [args...]
You can omit -- if the command is unambiguous (doesn’t start with --). Example: 
safehouse --enable=ssh git push origin main
If your command arguments include options starting with --, always use the -- separator to avoid ambiguity.

​
Explain Mode

Debugging mode that prints detailed information about policy decisions to stderr. 
safehouse --explain [other options]
Shows:
  • Effective workdir and its source (flag, env, or default)
  • Path grants (read-only and read-write)
  • Selected agent profiles
  • Integration selections and reasons
Example: 
safehouse --explain --enable=docker --stdout
--explain is invaluable for troubleshooting:
  • Why certain files are accessible/inaccessible
  • Which profiles are being loaded
  • Where configuration values come from

​
Common Usage Patterns

Quick Testing

# Test policy without execution
safehouse --stdout --enable=docker

Development Workflow

# Run agent with project access
safehouse --workdir=~/projects/myapp -- aider

CI/CD Integration

# Sandbox test execution
safehouse --enable=docker -- npm run test:e2e

Debugging

# Diagnose permission issues
safehouse --explain --enable=all-agents --stdout

​
Command Resolution

Safehouse automatically detects the command being executed and loads appropriate agent profiles: 
# Loads Claude profile automatically
safehouse -- claude

# Detects npx wrapper and loads profile for actual command
safehouse -- npx aider

# Works with .app bundles
safehouse -- /Applications/Claude.app/Contents/MacOS/Claude

​
Supported Wrappers

Safehouse looks through these wrapper commands to find the actual target:
  • npx
  • bunx
  • uvx
  • pipx
  • xcrun
For wrappers, safehouse uses the second argument (the actual command name) for profile selection.

​
Exit Status

In execute mode, safehouse exits with the same status code as the wrapped command: 
safehouse -- false
echo $?  # outputs: 1

safehouse -- true
echo $?  # outputs: 0

Build docs developers (and LLMs) love

Get started for freeTalk to us