CLI Options

All safehouse options can be specified in two formats: --option VALUE or --option=VALUE.

Policy Scope Options

—enable

--enable

string

Comma-separated list of optional features to enable.Format: --enable FEATURES or --enable=FEATURESExamples:

safehouse --enable=docker -- docker ps
safehouse --enable docker,kubectl -- kubectl get pods
safehouse --enable=all-agents -- claude

See Integrations for the complete list of available features.

—workdir

--workdir

string

default:"Current directory"

Main directory to grant read/write access. The sandbox automatically grants full access to this directory and its contents.Special value: Empty string (--workdir="") disables automatic workdir grants entirely.Examples:

# Grant access to specific project
safehouse --workdir=/path/to/project -- aider

# Disable workdir grants
safehouse --workdir="" -- claude

# Use environment variable
export SAFEHOUSE_WORKDIR=~/projects/myapp
safehouse -- cursor

Priority order:

--workdir flag (highest)
SAFEHOUSE_WORKDIR environment variable
Current working directory (default)

—add-dirs-ro

--add-dirs-ro

string

Colon-separated file/directory paths to grant read-only access.Format: --add-dirs-ro PATHS or --add-dirs-ro=PATHSExamples:

# Single path
safehouse --add-dirs-ro=/etc/config -- app

# Multiple paths
safehouse --add-dirs-ro=/etc/config:/var/data -- app

# Combine with environment variable
export SAFEHOUSE_ADD_DIRS_RO=/shared/readonly
safehouse --add-dirs-ro=/etc/ssl -- app

Paths from the flag are combined with SAFEHOUSE_ADD_DIRS_RO environment variable.

—add-dirs

--add-dirs

string

Colon-separated file/directory paths to grant read/write access.Format: --add-dirs PATHS or --add-dirs=PATHSExamples:

# Grant write access to additional directories
safehouse --add-dirs=/tmp/cache:/var/log/app -- myapp

# Combine with environment variable
export SAFEHOUSE_ADD_DIRS=/shared/writable
safehouse --add-dirs=/tmp/output -- app

Paths from the flag are combined with SAFEHOUSE_ADD_DIRS environment variable.

Read-write grants should be used sparingly. Only grant write access to directories that absolutely need it.

—env

--env

boolean | string

Controls environment variable passing to the sandboxed command.Mode 1: Full passthrough (--env)

# Pass all environment variables
safehouse --env -- myapp

Mode 2: Load from file (--env=FILE)

# Load variables from file (sourced by /bin/bash)
safehouse --env=.env.production -- myapp

The file is sourced by Bash, not parsed as dotenv. File values override sanitized defaults.Default: Sanitized environment with safe variables only (PATH, HOME, USER, etc.)

--env (passthrough) cannot be combined with --env=FILE or --env-pass.

—env-pass

--env-pass

string

Comma-separated environment variable names to pass through on top of sanitized defaults.Format: --env-pass NAMES or --env-pass=NAMESCan be specified multiple times; names are deduplicated.Examples:

# Pass specific variables
safehouse --env-pass=API_KEY,DATABASE_URL -- app

# Multiple --env-pass flags
safehouse --env-pass=AWS_PROFILE --env-pass=NODE_ENV -- app

# Combine with environment variable
export SAFEHOUSE_ENV_PASS=DEBUG,VERBOSE
safehouse --env-pass=API_KEY -- app

Compatible with default sanitized mode and --env=FILE. Incompatible with --env (passthrough).

—trust-workdir-config

--trust-workdir-config

boolean

default:"false"

Trust and load configuration from <workdir>/.safehouse file.Format: --trust-workdir-config or --trust-workdir-config=BOOLAccepted boolean values: 1, 0, true, false, yes, no, on, offExamples:

# Trust .safehouse in current directory
safehouse --trust-workdir-config -- app

# Via environment variable
export SAFEHOUSE_TRUST_WORKDIR_CONFIG=true
safehouse -- app

Supported config file keys:

add-dirs-ro=PATHS
add-dirs=PATHS

Only enable this for directories you control. Untrusted .safehouse files could grant excessive permissions.

—append-profile

--append-profile

string

Append an additional sandbox profile file after generated rules. Can be specified multiple times.Format: --append-profile PATH or --append-profile=PATHFiles are appended in argument order. Later rules override earlier ones.Examples:

# Add custom allow rules
safehouse --append-profile=./custom-rules.sb -- app

# Stack multiple profiles
safehouse --append-profile=base.sb --append-profile=overrides.sb -- app

This is the most powerful customization option. Use it to:

Add custom allow rules
Override default denials
Create project-specific policies

—output

--output

string

Write policy to a specific file path instead of a temporary file.Format: --output PATH or --output=PATHWhen specified, the policy file persists after execution (not automatically cleaned up).Examples:

# Save policy to file (policy mode)
safehouse --output=./my-policy.sb

# Save and execute
safehouse --output=./policy.sb -- myapp
# Policy file remains after execution

Output Options

—stdout

--stdout

flag

Print policy text to stdout instead of executing a command.Forces policy mode even if a command is provided.Examples:

# View generated policy
safehouse --stdout

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

# Save to file
safehouse --stdout > policy.sb

—explain

--explain

flag

Print detailed policy decision summary to stderr.Shows:

Effective workdir and source
All path grants (read-only and read-write)
Selected agent profiles and reasons
Optional integration selections
Config file status (found/trusted/loaded)

Examples:

# Debug policy generation
safehouse --explain --stdout

# Debug during execution
safehouse --explain -- myapp 2>debug.log

Use --explain to understand:

Why files are accessible or blocked
Which profiles are active
Where configuration values originate

General Options

—help

--help

flag

Show help message and exit.Aliases: -h, --help

safehouse --help
safehouse -h

Environment Variables

All major options have environment variable equivalents:

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

CLI flags take precedence over environment variables when both are specified.

Priority & Precedence

Path Grants Assembly Order

Core system profiles (base, runtime, network, toolchains)
Shared profiles and core integrations (git, scm-clis)
Optional integrations from --enable
Agent/app profiles (auto-detected from command)
--add-dirs-ro paths (CLI + environment variable)
--add-dirs paths (CLI + environment variable)
Workdir grant (if not disabled)
--append-profile overlays (in argument order)

Later rules win. Deny rules in --append-profile take precedence over all earlier allows.

Configuration Sources Priority

For --workdir:

--workdir flag (highest)
SAFEHOUSE_WORKDIR environment variable
Current working directory (default)

For --trust-workdir-config:

--trust-workdir-config flag (highest)
SAFEHOUSE_TRUST_WORKDIR_CONFIG environment variable
false (default)

Path Combination Rules

--add-dirs-ro flag + SAFEHOUSE_ADD_DIRS_RO → combined (both applied)
--add-dirs flag + SAFEHOUSE_ADD_DIRS → combined (both applied)
.safehouse config file paths → combined with CLI/env (if trusted)

Shell Argument Parsing

safehouse --enable docker
safehouse --workdir /path/to/dir

Always use the -- separator when command arguments might start with --:

# Correct
safehouse -- myapp --verbose

# Wrong (--verbose parsed as safehouse option)
safehouse myapp --verbose

CLI Reference

Policy Profiles

Resources

Policy Scope Options

—enable

—workdir

—add-dirs-ro

—add-dirs

—env

—env-pass

—trust-workdir-config

—append-profile

—output

Output Options

—stdout

—explain

General Options

—help

Environment Variables

Priority & Precedence

Path Grants Assembly Order

Configuration Sources Priority

Path Combination Rules

Shell Argument Parsing

Build docs developers (and LLMs) love

CLI Reference

Policy Profiles

Resources

​Policy Scope Options

​—enable

​—workdir

​—add-dirs-ro

​—add-dirs

​—env

​—env-pass

​—trust-workdir-config

​—append-profile

​—output

​Output Options

​—stdout

​—explain

​General Options

​—help

​Environment Variables

​Priority & Precedence

​Path Grants Assembly Order

​Configuration Sources Priority

​Path Combination Rules

​Shell Argument Parsing

Build docs developers (and LLMs) love

Policy Scope Options

—enable

—workdir

—add-dirs-ro

—add-dirs

—env

—env-pass

—trust-workdir-config

—append-profile

—output

Output Options

—stdout

—explain

General Options

—help

Environment Variables

Priority & Precedence

Path Grants Assembly Order

Configuration Sources Priority

Path Combination Rules

Shell Argument Parsing