Commands

Complete reference of safehouse command modes and usage patterns

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.

Print Policy Path

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