CLI Options Reference

Complete reference for all Safehouse command-line flags and options

This page documents every CLI option supported by Agent Safehouse.

Usage Syntax

safehouse [policy options]
safehouse [policy options] [--] <command> [args...]

Policy Scope Options

These options control what permissions are granted inside the sandbox.

—enable

--enable · string

Enable optional integration features (comma-separated).

Syntax: --enable FEATURES or --enable=FEATURES

Supported values:

• docker - Docker socket and CLI access
• kubectl - Kubernetes client access
• macos-gui - macOS GUI automation (AXUIElement)
• electron - Electron app requirements (implies macos-gui)
• chromium-headless - Headless browser support
• chromium-full - Full Chromium/Chrome (implies chromium-headless)
• ssh - SSH client access
• spotlight - macOS Spotlight search
• cleanshot - CleanShot media access
• clipboard - System clipboard access
• 1password - 1Password CLI integration
• cloud-credentials - Cloud provider credential access (AWS, GCP, Azure)
• agent-browser - Browser automation for agents (implies chromium-headless)
• browser-native-messaging - Browser native messaging protocol
• shell-init - Read shell startup files (.zshrc, .bashrc, etc.)
• process-control - Host process enumeration and signaling
• lldb - LLDB debugger with task-port access (implies process-control)
• all-agents - Load all agent profiles from 60-agents/
• all-apps - Load all app profiles from 65-apps/
• wide-read - Grant broad read-only access across / (use cautiously)

Examples:

safehouse --enable=docker -- docker ps
safehouse --enable=clipboard,macos-gui -- cursor
safehouse --enable=all-agents -- claude

Security note: Features like wide-read, process-control, and lldb grant significant system access. Only enable them when necessary.

—add-dirs-ro

--add-dirs-ro · string

Grant read-only access to additional file paths (colon-separated).

Syntax: --add-dirs-ro PATHS or --add-dirs-ro=PATHS

Default: None

Paths can be files or directories. For directories, access is granted recursively. Multiple paths are separated by colons (:).

Examples:

safehouse --add-dirs-ro="$HOME/docs" -- claude
safehouse --add-dirs-ro="$HOME/project:$HOME/libs" -- npm test

Environment equivalent: SAFEHOUSE_ADD_DIRS_RO

—add-dirs

--add-dirs · string

Grant read/write access to additional file paths (colon-separated).

Syntax: --add-dirs PATHS or --add-dirs=PATHS

Default: None

Paths can be files or directories. For directories, access is granted recursively. Multiple paths are separated by colons (:).

Examples:

safehouse --add-dirs="$HOME/output" -- node build.js
safehouse --add-dirs="/tmp/cache:$HOME/logs" -- npm test

Environment equivalent: SAFEHOUSE_ADD_DIRS

—workdir

--workdir · string

Set the main working directory with read/write access.

Syntax: --workdir DIR or --workdir=DIR

Default: Current working directory (pwd)

The workdir receives automatic read/write grants and is where the .safehouse config file is searched for (if trusted).

Special value: Empty string (--workdir="") disables automatic workdir grants entirely.

Examples:

safehouse --workdir=/path/to/project -- aider
safehouse --workdir="" -- claude  # No automatic workdir access

Environment equivalent: SAFEHOUSE_WORKDIR

—trust-workdir-config

--trust-workdir-config · boolean

Trust and load the .safehouse config file from the workdir.

Syntax: --trust-workdir-config or --trust-workdir-config=BOOL

Default: false (disabled)

Accepted values: 1, 0, true, false, yes, no, on, off

When enabled, Safehouse reads <workdir>/.safehouse and loads additional path grants specified in that file.

Examples:

safehouse --trust-workdir-config -- npm test
safehouse --trust-workdir-config=true -- claude

Environment equivalent: SAFEHOUSE_TRUST_WORKDIR_CONFIG

Only enable --trust-workdir-config for projects you trust. The config file can grant additional filesystem access, including paths outside the project directory.

—append-profile

--append-profile · string

Append an additional sandbox profile file after generated rules.

Syntax: --append-profile PATH or --append-profile=PATH

Default: None

This option is repeatable. Files are appended in the order specified. Profiles appended here have final say and can override earlier rules.

Paths starting with ~ are expanded to your home directory.

Examples:

safehouse --append-profile="$HOME/.config/safehouse/local.sb" -- claude
safehouse --append-profile=~/overrides.sb --append-profile=~/deny.sb -- aider

Use --append-profile for machine-specific overrides or final deny rules. See Shell Functions for a complete pattern.

Environment Options

These options control which environment variables are passed to the sandboxed command.

—env

--env · flag

Execute the wrapped command with full inherited environment variables.

Syntax: --env (flag only, no value)

Default: Sanitized environment with safe defaults

When specified, all environment variables from the host are passed through to the sandboxed command. This includes secrets, tokens, and credentials.

Incompatible with: --env=FILE, --env-pass

Example:

safehouse --env -- npm run build

--env grants access to all environment variables, including sensitive data like AWS_SECRET_ACCESS_KEY, API tokens, and session credentials. Use only when necessary.

—env=FILE

--env · string

Load environment variables from a file on top of sanitized defaults.

Syntax: --env=FILE

Default: Sanitized environment only

The file is sourced by /bin/bash (not parsed as dotenv). Use shell syntax with export statements. File variables override sanitized defaults.

Paths starting with ~ are expanded to your home directory.

Incompatible with: --env (full pass-through)

Compatible with: --env-pass

Example:

safehouse --env=~/dev-secrets.env -- npm test

File format:

export DATABASE_URL="postgresql://localhost/testdb"
export API_KEY="test-key-123"

—env-pass

--env-pass · string

Pass specific environment variables from the host (comma-separated).

Syntax: --env-pass NAMES or --env-pass=NAMES

Default: None (only sanitized defaults)

This option is repeatable. Variable names are deduplicated. Specified variables are added on top of sanitized defaults.

Incompatible with: --env (full pass-through)

Compatible with: --env=FILE (default mode)

Examples:

safehouse --env-pass=API_KEY -- node script.js
safehouse --env-pass=API_KEY --env-pass=DATABASE_URL -- npm test
safehouse --env-pass=AWS_PROFILE,AWS_REGION -- aws s3 ls

Environment equivalent: SAFEHOUSE_ENV_PASS

Output Options

These options control how Safehouse outputs the policy.

—output

--output · string

Write the policy to a specific file path.

Syntax: --output PATH or --output=PATH

Default: Temporary file (auto-deleted after execution)

When specified, the policy file is preserved after the command executes instead of being automatically deleted.

Examples:

safehouse --output=/tmp/my-policy.sb
safehouse --output=./policy.sb -- npm test

—stdout

--stdout · flag

Print policy text to stdout instead of executing a command.

Syntax: --stdout (flag only)

Default: Execute mode or print file path

When --stdout is specified:

• The policy is generated and printed to stdout
• If a command is provided, it is not executed
• The policy file is deleted unless --output is also specified

Examples:

safehouse --stdout
safehouse --enable=docker --stdout | less

—explain

--explain · flag

Print detailed policy generation summary to stderr.

Syntax: --explain (flag only)

Default: Silent (no explanation output)

Shows effective workdir, all path grants, loaded profiles, optional integrations, and config file status. Useful for debugging permission issues.

Examples:

safehouse --explain --stdout
safehouse --explain -- npm test

Sample output:

Effective workdir: /Users/dev/project (source: cwd)
Read-only grants: /Users/dev/shared, /Users/dev/docs
Read/write grants: /Users/dev/project
Loaded agent profiles: claude.sb (matched command: claude)
Optional integrations: docker, clipboard
workdir config: loaded from /Users/dev/project/.safehouse

General Options

-h, —help

--help · flag

Show usage information and exit.

Syntax: -h or --help

Example:

safehouse --help

Environment Variables

These environment variables provide an alternative way to set options:

SAFEHOUSE_ADD_DIRS_RO · string

Colon-separated read-only paths (same format as --add-dirs-ro).

Example:

export SAFEHOUSE_ADD_DIRS_RO="$HOME/shared:$HOME/docs"
safehouse -- claude

SAFEHOUSE_ADD_DIRS · string

Colon-separated read/write paths (same format as --add-dirs).

Example:

export SAFEHOUSE_ADD_DIRS="$HOME/output"
safehouse -- npm run build

SAFEHOUSE_WORKDIR · string

Override the working directory (same as --workdir).

Example:

export SAFEHOUSE_WORKDIR=/path/to/project
safehouse -- aider

SAFEHOUSE_TRUST_WORKDIR_CONFIG · string

Trust and load .safehouse config file (same as --trust-workdir-config).

Accepted values: 1, 0, true, false, yes, no, on, off

Example:

export SAFEHOUSE_TRUST_WORKDIR_CONFIG=1
safehouse -- npm test

SAFEHOUSE_ENV_PASS · string

Comma-separated env var names to pass through (same format as --env-pass).

Example:

export SAFEHOUSE_ENV_PASS="API_KEY,DATABASE_URL"
safehouse -- npm test

Option Precedence

When the same setting is specified in multiple ways, the precedence order is:

1. CLI flags (highest priority)
2. Environment variables
3. Config file (.safehouse if trusted)
4. Defaults (lowest priority)

Example:

export SAFEHOUSE_WORKDIR=/default/path
safehouse --workdir=/override/path -- command
# Uses: /override/path (CLI flag wins)

Path Resolution

All path options support tilde expansion:

safehouse --add-dirs-ro="~/docs" -- claude
# Expands to: /Users/username/docs

Paths are normalized to absolute paths before being included in the policy.