Custom Profiles

Writing `.sb` Files

Sandbox profiles use Sandbox Profile Language (SBPL), a Scheme-like DSL for macOS Seatbelt. Safehouse profiles are modular .sb files that follow a consistent structure.

Basic Structure

Every Safehouse profile includes:

Header comment (category, description, source path)
Dependency metadata (optional $$require= declarations)
Sandbox rules (allow/deny operations with matchers)

;; ---------------------------------------------------------------------------
;; Category: Feature Name
;; Description of what this profile grants access to.
;; Source: path/to/profile.sb
;; ---------------------------------------------------------------------------

(allow <operation>
    (<matcher> "<path>")
)

Operations

File Operations

Operation	Description	Example
`file-read*`	Read file contents, metadata, and list directories	`(allow file-read* (literal "/tmp/foo"))`
`file-read-metadata`	Read file metadata (stat) only, no contents	`(allow file-read-metadata (literal "/etc/hosts"))`
`file-write*`	Write, create, delete files	`(allow file-write* (subpath "/tmp"))`
`file-read* file-write*`	Combined read/write access	`(allow file-read* file-write* (home-subpath "/.myapp"))`

file-read* includes listing directory contents (readdir()). Use file-read-metadata if you only need stat access.

Network Operations

Operation	Description	Example
`network-outbound`	Establish outbound TCP/UDP connections	`(allow network-outbound (remote ip))`
`network-inbound`	Accept inbound connections (rare)	`(allow network-inbound (local tcp "*:8080"))`

IPC Operations

Operation	Description	Example
`mach-lookup`	Connect to mach services	`(allow mach-lookup (global-name "com.apple.SecurityServer"))`
`mach-register`	Register mach services (rare)	`(allow mach-register (global-name-regex #"^com\\.myapp\\."))`
`ipc-posix-shm-*`	POSIX shared memory access	`(allow ipc-posix-shm-read-data (ipc-posix-name "com.apple.AppleDatabaseChanged"))`

IOKit Operations

Operation	Description	Example
`iokit-open`	Open IOKit user clients (GPU, hardware access)	`(allow iokit-open (iokit-user-client-class "IOSurfaceRootUserClient"))`

Matchers

File Path Matchers

literal (exact path match)

Matches a single file or directory exactly. Safest and most precise.

(allow file-read*
    (literal "/Users/alice/.gitconfig")
    (literal "/etc/hosts")
)

When used on a directory, literal grants access to list the directory’s immediate children (via readdir()), but not recursive access to subdirectories or their files.

Use case: Grant access to a specific config file or single directory.

subpath (recursive directory match)

Matches a directory and all files/subdirectories recursively under it.

(allow file-read* file-write*
    (subpath "/Users/alice/projects/myapp")
    (home-subpath "/.docker")
)

Broader grant. Only use subpath when you need full recursive access. Prefer literal for single files or narrower grants.

Use case: Grant full access to a project directory or toolchain installation.

prefix (starts-with match)

Matches paths that start with the given string.

(allow file-read*
    (prefix "/usr/local/bin/node")
)

This matches /usr/local/bin/node, /usr/local/bin/node-v18, /usr/local/bin/nodejs, etc.

Less common in Safehouse profiles. Use literal or subpath when possible for clarity.

Use case: Match versioned binaries or symlinks with a common prefix.

regex (regular expression match)

Matches paths using a POSIX Extended Regular Expression.

(allow file-read*
    (regex #"^/Users/[^/]+/\\.nvm/versions/node/v[0-9]+\\.[0-9]+\\.[0-9]+/")
)

High complexity. Use sparingly. Regex patterns are harder to audit and can unintentionally match sensitive paths.

Use case: Match dynamic paths with variable components (e.g., usernames, version numbers).

Helper Macros (Safehouse-Specific)

Safehouse provides helper macros defined in 00-base.sb:

(define HOME_DIR "__SAFEHOUSE_REPLACE_ME_WITH_ABSOLUTE_HOME_DIR__")
(define (home-subpath rel) (subpath (string-append HOME_DIR rel)))
(define (home-literal rel) (literal (string-append HOME_DIR rel)))
(define (home-prefix rel) (prefix (string-append HOME_DIR rel)))

Usage:

(allow file-read* file-write*
    (home-subpath "/.myapp")               ;; /Users/alice/.myapp (recursive)
    (home-literal "/.myapp.conf")          ;; /Users/alice/.myapp.conf (exact)
    (home-prefix "/.config/myapp")         ;; /Users/alice/.config/myapp* (prefix)
)

Always use home-* macros instead of hardcoding /Users/alice. The HOME_DIR placeholder is replaced at runtime with the actual home directory path.

Mach Service Matchers

global-name (exact service name)

Matches a specific mach service name.

(allow mach-lookup
    (global-name "com.apple.SecurityServer")
    (global-name "com.apple.cfprefsd.daemon")
)

Use case: Grant access to specific macOS system services.

global-name-regex (regex service name)

Matches mach service names using a regex pattern.

(allow mach-lookup
    (global-name-regex #"^org\\.chromium\\.crashpad\\.child_port_handshake\\.")
)

Use case: Match dynamic service names (e.g., Chromium crashpad child processes).

Real Examples

Example 1: Aider Agent Profile

From profiles/60-agents/aider.sb:

;; ---------------------------------------------------------------------------
;; Agent: Aider
;; Aider CLI binary, state, and config paths.
;; Source: 60-agents/aider.sb
;; ---------------------------------------------------------------------------

(allow file-read* file-write*
    (home-prefix "/.local/bin/aider")
    (home-prefix "/.local/bin/aider-install")
    (home-prefix "/.aider")
    (home-literal "/.aider.conf.yml")
    (home-literal "/.aider.model.settings.yml")
    (home-literal "/.aider.model.metadata.json")
    (home-subpath "/.config/aider")
    (home-subpath "/.cache/aider")
    (home-subpath "/.local/share/aider")
)

Breakdown:

home-prefix "/.local/bin/aider" matches /Users/alice/.local/bin/aider, /Users/alice/.local/bin/aider-install, etc.
home-literal grants access to specific config files.
home-subpath grants recursive access to cache and data directories.

Example 2: Keychain Integration

From profiles/55-integrations-optional/keychain.sb:

;; ---------------------------------------------------------------------------
;; Integration: Keychain
;; macOS Keychain and Security framework for agent authentication/credential storage.
;; Source: 55-integrations-optional/keychain.sb
;; ---------------------------------------------------------------------------

(allow file-read* file-write*
    (home-subpath "/Library/Keychains")
    (home-literal "/Library/Preferences/com.apple.security.plist")
)

(allow file-read*
    (literal "/Library/Preferences/com.apple.security.plist")
    (literal "/Library/Keychains/System.keychain")
    (subpath "/private/var/db/mds")
)

(allow file-read-metadata
    (home-literal "/Library")
    (home-literal "/Library/Keychains")
    (literal "/Library")
    (literal "/Library/Keychains")
)

(allow mach-lookup
    (global-name "com.apple.SecurityServer")
    (global-name "com.apple.security.agent")
    (global-name "com.apple.securityd.xpc")
    (global-name "com.apple.security.authhost")
    (global-name "com.apple.secd")
    (global-name "com.apple.trustd")
)

(allow ipc-posix-shm-read-data ipc-posix-shm-write-create ipc-posix-shm-write-data
    (ipc-posix-name "com.apple.AppleDatabaseChanged")
)

Breakdown:

file-read-metadata grants stat-only access to parent directories (no content listing).
mach-lookup grants access to security-related mach services.
ipc-posix-shm-* grants shared memory access for keychain change notifications.

Example 3: Electron Integration (with Dependency)

From profiles/55-integrations-optional/electron.sb:

;; ---------------------------------------------------------------------------
;; Integration: Electron
;; Chromium/Electron runtime: GPU, Metal shaders, crashpad, and WebView.
;; Source: 55-integrations-optional/electron.sb
;; $$require=55-integrations-optional/macos-gui.sb$$
;; #safehouse-test-id:electron-integration#
;; ---------------------------------------------------------------------------

;; -- GPU / Metal shader compilation --------------------------------------------
;; #safehouse-test-id:electron-gpu-metal#

(allow mach-lookup
    (global-name "com.apple.MTLCompilerService")
    (global-name "com.apple.SafariPlatformSupport.Helper")
)

(allow iokit-open
    (iokit-user-client-class "IOSurfaceRootUserClient")
    (iokit-user-client-class "AGXDeviceUserClient")
)

(allow file-read-metadata
    (literal "/private/var/db/.AppleSetupDone")
)

;; -- Chromium crashpad crash reporting -----------------------------------------
;; #safehouse-test-id:electron-crashpad#
;; #safehouse-test-id:electron-crashpad-lookup#

(allow mach-lookup
    (global-name-regex #"^org\\.chromium\\.crashpad\\.child_port_handshake\\.")
)

;; #safehouse-test-id:electron-crashpad-register#
(allow mach-register
    (global-name-regex #"^org\\.chromium\\.crashpad\\.child_port_handshake\\.")
)

Key features:

$$require=55-integrations-optional/macos-gui.sb$$ auto-injects macos-gui.sb when electron.sb is enabled.
#safehouse-test-id:*# markers are used by test assertions to verify rule structure/order.
global-name-regex matches dynamic crashpad service names.

Authoring Checklist

When creating a new profile:

Choose the right stage prefix

Stage	Purpose
`30-toolchains/`	Language runtimes, package managers
`40-shared/`	Cross-agent resources
`50-integrations-core/`	Always-on integrations (git, gh)
`55-integrations-optional/`	Opt-in integrations (docker, ssh, keychain)
`60-agents/`	Agent-specific grants
`65-apps/`	App bundle-specific grants

Add standard header

;; ---------------------------------------------------------------------------
;; Category: Feature Name
;; Description of what this profile grants access to.
;; Source: path/to/profile.sb
;; ---------------------------------------------------------------------------

Declare dependencies (if needed)

;; $$require=55-integrations-optional/macos-gui.sb$$

Use $$require= for implicit optional integration injection. For documentation-only dependencies, use comments:

;; Requires: macos-gui integration (documentation only)

Write sandbox rules

Prefer literal > subpath > prefix > regex (narrowest first).Use home-* macros instead of hardcoded /Users/alice.

Add test markers (optional)

;; #safehouse-test-id:my-feature#
(allow file-read*
    (home-subpath "/.myapp")
)

Used by assert_policy_order_literal and assert_policy_contains in tests.

Add tests

Create a test section in tests/sections/:

# tests/sections/my-feature.sh
section_begin "my feature"

assert_allowed "read from granted path" \
  cat ~/.myapp/config.json

assert_denied "write to system path" \
  touch /System/test

register_section

Regenerate dist artifacts

./scripts/generate-dist.sh

Commit both the new profile and regenerated dist/ files in the same PR.

Best Practices

Narrow Grants

Use literal for single files/directories. Only use subpath when you need full recursive access.

Use Home Macros

Always use home-subpath, home-literal, home-prefix instead of hardcoded /Users/alice.

Document Why

Explain why a grant is needed, not just what it does. Future maintainers will thank you.

Test Behavior

Add assert_allowed and assert_denied tests for every new profile. Verify both positive and negative cases.

Debugging Sandbox Denials

Watch Live Denials

/usr/bin/log stream --style compact --predicate 'eventMessage CONTAINS "Sandbox:" AND eventMessage CONTAINS "deny("'

2026-03-09 10:23:45.123 kernel: Sandbox: myagent(1234) deny(1) file-read-data /Users/alice/.ssh/id_rsa

Recent Denial History

/usr/bin/log show --last 2m --style compact --predicate 'process == "sandboxd"'

Kernel-Level Stream

/usr/bin/log stream --style compact --info --debug --predicate '(processID == 0) AND (senderImagePath CONTAINS "/Sandbox")'

Run these commands before invoking safehouse to capture denials as they happen.

Reference Material

Official Sources

macOS built-in profiles: /System/Library/Sandbox/Profiles/ and /usr/share/sandbox/
Safehouse profiles: profiles/ (primary style reference)
Assembled examples: dist/profiles/safehouse.generated.sb and dist/profiles/safehouse-for-apps.generated.sb

Matcher Preference Order

literal — Exact path match (safest, most precise)
subpath — Recursive directory match (broader, use when needed)
prefix — Starts-with match (less common, use for versioned paths)
regex — Regular expression match (highest complexity, use sparingly)

Next Steps

Policy Architecture

Understand assembly order, profile layers, and dependency system.

Customization

Learn about machine-local overrides and --append-profile for runtime customization.

Get Started

Core Concepts

Usage

Advanced

Operations

Agent Compatibility

Writing `.sb` Files

Basic Structure

Operations

File Operations

Network Operations

IPC Operations

IOKit Operations

Matchers

File Path Matchers

Helper Macros (Safehouse-Specific)

Mach Service Matchers

Real Examples

Example 1: Aider Agent Profile

Example 2: Keychain Integration

Example 3: Electron Integration (with Dependency)

Authoring Checklist

Best Practices

Narrow Grants

Use Home Macros

Document Why

Test Behavior

Debugging Sandbox Denials

Watch Live Denials

Recent Denial History

Kernel-Level Stream

Reference Material

Official Sources

Matcher Preference Order

Next Steps

Policy Architecture

Customization

Build docs developers (and LLMs) love

Get Started

Core Concepts

Usage

Advanced

Operations

Agent Compatibility

​Writing .sb Files

​Basic Structure

​Operations

​File Operations

​Network Operations

​IPC Operations

​IOKit Operations

​Matchers

​File Path Matchers

​Helper Macros (Safehouse-Specific)

​Mach Service Matchers

​Real Examples

​Example 1: Aider Agent Profile

​Example 2: Keychain Integration

​Example 3: Electron Integration (with Dependency)

​Authoring Checklist

​Best Practices

Narrow Grants

Use Home Macros

Document Why

Test Behavior

​Debugging Sandbox Denials

​Watch Live Denials

​Recent Denial History

​Kernel-Level Stream

​Reference Material

​Official Sources

​Matcher Preference Order

​Next Steps

Policy Architecture

Customization

Build docs developers (and LLMs) love

Writing `.sb` Files

Basic Structure

Operations

File Operations

Network Operations

IPC Operations

IOKit Operations

Matchers

File Path Matchers

Helper Macros (Safehouse-Specific)

Mach Service Matchers

Real Examples

Example 1: Aider Agent Profile

Example 2: Keychain Integration

Example 3: Electron Integration (with Dependency)

Authoring Checklist

Best Practices

Debugging Sandbox Denials

Watch Live Denials

Recent Denial History

Kernel-Level Stream

Reference Material

Official Sources

Matcher Preference Order

Next Steps