Customization

Overview

Agent Safehouse provides two primary customization mechanisms:

Machine-local overrides (.safehouse config files)
--append-profile flag (runtime policy overlays)

Each serves different use cases. This guide explains when to use which approach.

Machine-Local Overrides

Workdir Config Files

Place a .safehouse file in your project root to configure project-specific grants:

# ~/projects/myapp/.safehouse
SAFEHOUSE_ADD_DIRS_RO="$HOME/reference-repo:$HOME/docs"
SAFEHOUSE_ADD_DIRS="$HOME/scratch"
SAFEHOUSE_ENABLE="docker,kubectl,ssh"

Workdir config files are untrusted by default. You must explicitly opt in:

safehouse --trust-workdir-config -- myagent

Or set globally:

export SAFEHOUSE_TRUST_WORKDIR_CONFIG=1

Shell Environment Variables

Set environment variables in your shell profile (~/.zshrc, ~/.bashrc):

# ~/.zshrc
export SAFEHOUSE_ADD_DIRS_RO="$HOME/reference-docs:$HOME/design-assets"
export SAFEHOUSE_ADD_DIRS="$HOME/scratch:$HOME/tmp-experiments"
export SAFEHOUSE_ENABLE="docker,ssh,clipboard"
export SAFEHOUSE_TRUST_WORKDIR_CONFIG=1

Precedence Order

When the same variable is set in multiple locations:

CLI flags (highest priority)

safehouse --enable=docker --add-dirs=/tmp/scratch -- myagent

Environment variables

export SAFEHOUSE_ENABLE="ssh"
safehouse -- myagent

Workdir config (lowest priority)

# .safehouse
SAFEHOUSE_ENABLE="kubectl"

Path grants are merged across all sources (CLI + ENV + config). Later sources append to earlier ones.Feature flags (--enable) are replaced (not merged). CLI --enable overrides ENV SAFEHOUSE_ENABLE, which overrides config SAFEHOUSE_ENABLE.

`--append-profile` Flag

Purpose

Append a custom .sb file to the end of the generated policy. This is the final extension point in the assembly order.

safehouse --append-profile=~/my-overrides.sb -- myagent

Use Cases

Deny Sensitive Paths

Block access to specific directories even if earlier rules allowed them:

;; ~/deny-aws.sb
(deny file-read* file-write*
    (home-subpath "/.aws")
)

safehouse --append-profile=~/deny-aws.sb -- myagent

Ad-Hoc Grants

Quickly grant access to a new tool or path without editing committed profiles:

;; ~/tmp-grants.sb
(allow file-read* file-write*
    (subpath "/usr/local/mycorp-tool")
)

safehouse --append-profile=~/tmp-grants.sb -- myagent

Testing Policy Changes

Iterate on policy rules before committing them to the repository:

# Test new rule
safehouse --append-profile=./test-rule.sb -- myagent

# Once validated, move to profiles/
mv test-rule.sb profiles/55-integrations-optional/my-feature.sb

Environment-Specific Rules

Apply machine-specific grants without editing source profiles:

# ~/machine-local.sb
(allow file-read*
    (literal "/opt/local-tool/config.json")
)

safehouse --append-profile=~/machine-local.sb -- myagent

Multiple Appended Profiles

Pass --append-profile multiple times. They are concatenated in order:

safehouse \
  --append-profile=~/base-overrides.sb \
  --append-profile=~/project-specific.sb \
  -- myagent

Last Rule Wins

Because --append-profile rules are emitted last in the policy assembly order, they override earlier rules:

;; From 60-agents/myagent.sb
(allow file-read* file-write*
    (home-subpath "/.myagent")
)

The deny rule wins because it comes last.

Comparison: When to Use Which

Scenario	Recommended Approach	Why
Project-specific extra directories	Workdir `.safehouse` config	Per-project, version-controlled, no CLI friction
Machine-wide defaults	Shell ENV vars (`~/.zshrc`)	Applies to all invocations, no per-project setup
One-off path grant for debugging	CLI `--add-dirs=/tmp/foo`	Fastest, no file editing
Block sensitive path (e.g., `~/.ssh`)	`--append-profile` with deny rule	Deny rules must come last to override allows
Test new integration before committing	`--append-profile=./test.sb`	Iterate quickly without editing `profiles/`
Machine-specific tool access	`--append-profile=~/machine-local.sb`	Persistent but not committed to repo
Enable Docker/SSH for all projects	Shell ENV `SAFEHOUSE_ENABLE=docker,ssh`	Machine-wide, no per-project config
Temporary feature enable	CLI `--enable=clipboard`	One-off, no config file changes

Example Workflows

Workflow 1: Project-Specific Reference Repo

You’re working on ~/projects/myapp and need read-only access to ~/reference/design-system.

Create workdir config

# ~/projects/myapp/.safehouse
SAFEHOUSE_ADD_DIRS_RO="$HOME/reference/design-system"

Trust the config (once)

cd ~/projects/myapp
safehouse --trust-workdir-config -- myagent

Or enable trust globally:

echo 'export SAFEHOUSE_TRUST_WORKDIR_CONFIG=1' >> ~/.zshrc
source ~/.zshrc

Run agent

cd ~/projects/myapp
safehouse -- myagent

The agent now has read-only access to ~/reference/design-system.

Workflow 2: Block Cloud Credentials

You want to ensure agents never access ~/.aws or ~/.config/gcloud, even if cloud-credentials integration is enabled.

Create deny profile

;; ~/deny-cloud.sb
(deny file-read* file-write*
    (home-subpath "/.aws")
    (home-subpath "/.config/gcloud")
    (home-subpath "/.azure")
)

Run with appended profile

safehouse --append-profile=~/deny-cloud.sb -- myagent

Make it persistent (optional)

Add to shell ENV:

# ~/.zshrc
export SAFEHOUSE_APPEND_PROFILE="$HOME/deny-cloud.sb"

Now all safehouse invocations include the deny rules.

--append-profile paths are not automatically resolved in ENV vars. Use absolute paths or $HOME:

# ✅ Correct
export SAFEHOUSE_APPEND_PROFILE="$HOME/deny-cloud.sb"

# ❌ Incorrect (won't expand ~)
export SAFEHOUSE_APPEND_PROFILE="~/deny-cloud.sb"

Workflow 3: Machine-Wide Docker + SSH

You want Docker and SSH enabled for all agent invocations on your machine.

Set ENV var

# ~/.zshrc
export SAFEHOUSE_ENABLE="docker,ssh"

Reload shell

source ~/.zshrc

Verify

safehouse --explain --stdout 2>&1 | grep "optional integrations explicitly enabled"

Output:

optional integrations explicitly enabled: docker ssh

Debugging Overrides

Inspect Effective Config

Use --explain to see which config sources were loaded:

safehouse --explain --stdout

safehouse explain:
  effective workdir: /Users/alice/projects/myapp (source: PWD)
  workdir config trust: enabled (source: CLI flag)
  workdir config: loaded from /Users/alice/projects/myapp/.safehouse
  add-dirs-ro (normalized): /Users/alice/reference-docs /Users/alice/design-assets
  add-dirs (normalized): /Users/alice/scratch
  optional integrations explicitly enabled: docker ssh clipboard
  ...

Check Policy for Appended Rules

Generate policy and search for your appended profile:

safehouse --append-profile=~/my-overrides.sb --stdout > /tmp/policy.sb
grep -A 5 "#safehouse-test-id:append-profile#" /tmp/policy.sb

;; #safehouse-test-id:append-profile# Appended profile from --append-profile: /Users/alice/my-overrides.sb

(deny file-read* file-write*
    (home-subpath "/.aws")
)

Best Practices

Use Workdir Config for Projects

Commit .safehouse to your repo for team-shared project grants. Keep machine-specific overrides in ENV or --append-profile.

Use ENV for Machine Defaults

Set SAFEHOUSE_ENABLE, SAFEHOUSE_ADD_DIRS_RO in ~/.zshrc for your personal workflow defaults.

Use --append-profile for Denies

Deny rules must come last to override allows. --append-profile is the only way to guarantee last-rule-wins.

Test Before Committing

Use --append-profile=./test.sb to iterate on new rules before moving them to profiles/.

Environment Variable Reference

Variable	Type	Description	Example
`SAFEHOUSE_ENABLE`	String (CSV)	Comma-separated optional integration features	`docker,ssh,clipboard`
`SAFEHOUSE_ADD_DIRS_RO`	String (colon-separated)	Read-only directory grants	`$HOME/docs:$HOME/reference`
`SAFEHOUSE_ADD_DIRS`	String (colon-separated)	Read/write directory grants	`$HOME/scratch:/tmp/work`
`SAFEHOUSE_APPEND_PROFILE`	String (colon-separated)	Paths to `.sb` files to append	`$HOME/overrides.sb:$HOME/deny.sb`
`SAFEHOUSE_WORKDIR`	String (path)	Override working directory	`/Users/alice/projects/myapp`
`SAFEHOUSE_TRUST_WORKDIR_CONFIG`	`1` or `0`	Enable workdir config trust	`1`

All path variables (SAFEHOUSE_ADD_DIRS_RO, SAFEHOUSE_ADD_DIRS, SAFEHOUSE_APPEND_PROFILE) support colon-separated lists:

export SAFEHOUSE_ADD_DIRS_RO="$HOME/docs:$HOME/reference:$HOME/assets"

Next Steps

Write Custom Profiles

Learn how to write your own .sb files with matchers and real examples.

Policy Architecture

Understand assembly order, profile layers, and dependency system.

Get Started

Core Concepts

Usage

Advanced

Operations

Agent Compatibility

Overview

Machine-Local Overrides

Workdir Config Files

Shell Environment Variables

Precedence Order

`--append-profile` Flag

Purpose

Use Cases

Deny Sensitive Paths

Ad-Hoc Grants

Testing Policy Changes

Environment-Specific Rules

Multiple Appended Profiles

Last Rule Wins

Comparison: When to Use Which

Example Workflows

Workflow 1: Project-Specific Reference Repo

Workflow 2: Block Cloud Credentials

Workflow 3: Machine-Wide Docker + SSH

Debugging Overrides

Inspect Effective Config

Check Policy for Appended Rules

Best Practices

Use Workdir Config for Projects

Use ENV for Machine Defaults

Use --append-profile for Denies

Test Before Committing

Environment Variable Reference

Next Steps

Write Custom Profiles

Policy Architecture

Build docs developers (and LLMs) love

Get Started

Core Concepts

Usage

Advanced

Operations

Agent Compatibility

​Overview

​Machine-Local Overrides

​Workdir Config Files

​Shell Environment Variables

​Precedence Order

​--append-profile Flag

​Purpose

​Use Cases

Deny Sensitive Paths

Ad-Hoc Grants

Testing Policy Changes

Environment-Specific Rules

​Multiple Appended Profiles

​Last Rule Wins

​Comparison: When to Use Which

​Example Workflows

​Workflow 1: Project-Specific Reference Repo

​Workflow 2: Block Cloud Credentials

​Workflow 3: Machine-Wide Docker + SSH

​Debugging Overrides

​Inspect Effective Config

​Check Policy for Appended Rules

​Best Practices

Use Workdir Config for Projects

Use ENV for Machine Defaults

Use --append-profile for Denies

Test Before Committing

​Environment Variable Reference

​Next Steps

Write Custom Profiles

Policy Architecture

Build docs developers (and LLMs) love

Overview

Machine-Local Overrides

Workdir Config Files

Shell Environment Variables

Precedence Order

`--append-profile` Flag

Purpose

Use Cases

Multiple Appended Profiles

Last Rule Wins

Comparison: When to Use Which

Example Workflows

Workflow 1: Project-Specific Reference Repo

Workflow 2: Block Cloud Credentials

Workflow 3: Machine-Wide Docker + SSH

Debugging Overrides

Inspect Effective Config

Check Policy for Appended Rules

Best Practices

Environment Variable Reference

Next Steps