Integrations

Optional features you can enable with —enable to extend sandbox capabilities

Integrations are optional sandbox profile extensions enabled via --enable. Each integration grants specific capabilities needed for tools, services, or workflows.

Usage

# Single integration
safehouse --enable=docker -- docker ps

# Multiple integrations
safehouse --enable=docker,kubectl,ssh -- app

# View enabled integrations
safehouse --explain --enable=docker --stdout

Container & Orchestration

docker

docker · integration

Docker daemon socket access for container operations.

Enables:

• /var/run/docker.sock (standard socket)
• ~/.docker/run/docker.sock (Docker Desktop)
• ~/.orbstack/run/docker.sock (OrbStack)
• ~/.rd/docker.sock (Rancher Desktop)
• ~/.docker/ (CLI config, contexts, buildx)
• ~/.colima/ (Colima runtime state)
• OrbStack completions directory

Example:

safehouse --enable=docker -- docker run hello-world
safehouse --enable=docker -- docker-compose up

High-risk integration. Docker socket access is equivalent to root access on the host.

kubectl

kubectl · integration

Kubernetes CLI configuration, cache, and plugin access.

Enables:

• ~/.kube/ (read: config, certs, cache)
• ~/.kube/config (write: context/credentials updates)
• ~/.kube/cache/ (write: discovery cache)
• ~/.kube/http-cache/ (write: HTTP cache)
• ~/.krew/ (krew plugin manager)

Example:

safehouse --enable=kubectl -- kubectl get pods
safehouse --enable=kubectl -- k9s

Remote Access

ssh

ssh · integration

SSH agent access and safe SSH configuration (blocks private keys).

Enables:

• SSH agent sockets (via SSH_AUTH_SOCK)
• ~/.ssh/config and ~/.ssh/config.d/ (read)
• ~/.ssh/known_hosts (read + write)
• ~/.ssh/allowed_signers (git commit signing)
• System SSH config (/etc/ssh/)

Blocks:

• All ~/.ssh/ private keys (defense-in-depth)

Example:

safehouse --enable=ssh -- git push origin main
safehouse --enable=ssh -- ssh user@host

SSH integration allows git operations and remote connections via SSH agent, while preventing private key exfiltration.

Cloud Providers

cloud-credentials

cloud-credentials · integration

Cloud provider CLI/SDK credential and configuration access.

Enables:

• ~/.aws/ (AWS profiles, SSO, cache)
• ~/.config/gcloud/ (GCP config, tokens)
• ~/.azure/ (Azure CLI credentials)
• ~/.azd/ (Azure Developer CLI)

Example:

safehouse --enable=cloud-credentials -- aws s3 ls
safehouse --enable=cloud-credentials -- gcloud compute instances list
safehouse --enable=cloud-credentials -- az account show

Provides access to cloud credentials. Use --append-profile to selectively deny specific providers if needed.

1password

1password · integration

1Password CLI and SSH agent access.

Enables:

• ~/.config/op/ (CLI config, sessions)
• ~/.1password/ (SSH agent socket)
• /Users/Shared/.1password/ (shared socket)
• 1Password app group containers (agent socket)
• ~/.config/1Password/ (SSH agent config)
• 1Password Desktop settings (read-only probe)
• Mach lookup for 1Password services

Example:

safehouse --enable=1password -- op item list
safehouse --enable=1password,ssh -- git push  # Use 1Password SSH agent

macOS Desktop

macos-gui

macos-gui · integration

Window server, AppKit, accessibility, and framework services for graphical macOS applications.

Enables:

• Window server and Core Animation
• AppKit framework services
• Fonts and icon services
• Input methods and accessibility
• TCC (Transparency, Consent, Control)
• Launch Services and Core Services
• User notifications and audio
• Dock, menu bar, and window management
• IOKit (power, HID input, storage)

Example:

safehouse --enable=macos-gui -- /Applications/MyApp.app/Contents/MacOS/MyApp

Required for any app that displays windows or UI. Automatically included when electron is enabled.

clipboard

clipboard · integration

Clipboard read/write access for pbcopy/pbpaste.

Enables:

• com.apple.pasteboard.1 (pasteboard service)
• Launch Services type lookups

Example:

safehouse --enable=clipboard -- pbcopy < file.txt
echo "data" | safehouse --enable=clipboard -- pbcopy

spotlight

spotlight · integration

Spotlight search via mdfind/mdls/mdutil.

Enables:

• com.apple.metadata.mds (Spotlight server)
• com.apple.metadata.mds.legacy (legacy interface)
• Power management control (for Spotlight helpers)

Example:

safehouse --enable=spotlight -- mdfind 'kMDItemDisplayName == "*.pdf"'

cleanshot

cleanshot · integration

Read access to CleanShot screenshot/recording media.

Enables:

• ~/Library/Application Support/CleanShot/media/

Example:

safehouse --enable=cleanshot -- ls ~/Library/Application\ Support/CleanShot/media/

Browser & Chromium

chromium-headless

chromium-headless · integration

Headless Chromium/Playwright runtime support.

Enables:

• GPU and Metal shader compilation
• Chromium crashpad
• Mach port rendezvous
• AppKit preferences (accessibility, input, graphics)
• Core rendering services
• Font and icon services

Example:

safehouse --enable=chromium-headless -- playwright test
safehouse --enable=chromium-headless -- node headless-chrome.js

For headless browser automation. Does not include shell init or browser profile directories.

chromium-full

chromium-full · integration

Additional allowances for headed Chrome for Testing.

Enables:

• All chromium-headless features
• Chrome for Testing app support directories
• Crashpad database
• DevTools active port handshake
• Chrome preferences
• Pasteboard access

Example:

safehouse --enable=chromium-full -- chrome --headless=new

Implies chromium-headless. Use for headed browser instances.

electron

electron · integration

Chromium/Electron runtime: GPU, Metal, crashpad, WebView.

Enables:

• All macos-gui features (automatically)
• GPU and Metal compiler service
• IOKit (IOSurface, AGX device)
• Chromium crashpad (Mach register + lookup)
• Safari platform support

Example:

safehouse --enable=electron -- /Applications/MyElectronApp.app/Contents/MacOS/MyElectronApp --no-sandbox

Electron apps must use --no-sandbox or ELECTRON_DISABLE_SANDBOX=1 because safehouse already provides the outer sandbox.

Implies macos-gui. Electron’s internal sandbox is incompatible with safehouse (cannot nest Seatbelt sandboxes).

agent-browser

agent-browser · integration

Agent-browser CLI state and launcher paths for skill-driven browser automation.

Enables:

• All chromium-headless features (automatically)
• ~/.agent-browser/ (daemon sockets, screenshots, state)
• ~/Library/pnpm/ (traversal for pnpm shims)

Example:

safehouse --enable=agent-browser -- agent-browser start

Implies chromium-headless.

browser-native-messaging

browser-native-messaging · integration

Browser native messaging host registration and extension detection.

Enables:

• Native messaging host registration (read+write)
• Extension directory detection (read-only)
• Supported browsers: Chrome, Brave, Arc, Edge, Chromium, Vivaldi, Opera, Firefox

No access to:

• Cookies, passwords, history, bookmarks, or profile data

Example:

safehouse --enable=browser-native-messaging -- install-native-host

Extensions directory only contains publicly-available extension source/manifests — no browsing data.

Development Tools

shell-init

shell-init · integration

Shell startup file reads for workflows requiring shell-managed PATH/bootstrap.

Enables:

• /etc/profile, /etc/bashrc, /etc/zprofile, /etc/zshrc
• /etc/paths and /etc/paths.d/
• ~/.zshenv, ~/.zprofile, ~/.zshrc
• ~/.zcompdump* (Zsh completion cache)

Example:

safehouse --enable=shell-init -- zsh -l -c 'echo $PATH'

Disabled by default to reduce accidental exposure of secrets in shell dotfiles.

process-control

process-control · integration

Host process enumeration and signalling for local supervision.

Enables:

• com.apple.sysmond (process inventory)
• signal (kill, pkill, killall)

Does NOT enable:

• Task-port access
• Debugger-grade inspection (use lldb for that)

Example:

safehouse --enable=process-control -- pkill node
safehouse --enable=process-control -- pgrep -fl python

lldb

lldb · integration

LLDB/debugserver toolchain and debugger-grade host process inspection.

Enables:

• All process-control features (automatically)
• ~/.lldbinit*
• /Library/Developer/CommandLineTools/
• /Applications/Xcode.app/Contents/Developer/
• /Applications/Xcode-beta.app/Contents/Developer/
• Task-port access (mach-priv-task-port)
• Process info (process-info-pidinfo, process-info-setcontrol)

Example:

safehouse --enable=lldb -- lldb ./myapp
safehouse --enable=lldb -- lldb -p 1234

High-risk integration. Provides task-port access and debugger capabilities. Successful attach still depends on macOS debugger policy (taskgated, SIP, hardened targets).

Implies process-control.

Meta Integrations

all-agents

all-agents · integration

Load every profile from 60-agents/.

Includes profiles for: Claude, Cursor, Aider, Gemini, OpenHands, and other coding agents.

Example:

safehouse --enable=all-agents -- unknown-agent

Use when the specific agent is unknown or when running multiple agents.

all-apps

all-apps · integration

Load every profile from 65-apps/.

Includes profiles for common desktop applications and tools.

Example:

safehouse --enable=all-apps -- /Applications/Unknown.app/Contents/MacOS/Unknown

wide-read

wide-read · integration

Grant read-only visibility across / (entire filesystem).

Example:

safehouse --enable=wide-read -- find /usr -name '*.dylib'

Broad permission grant. Use cautiously. Prefer specific --add-dirs-ro paths when possible.

Integration Dependencies

Some integrations automatically enable others:

electron

Implies macos-gui

chromium-full

Implies chromium-headless

agent-browser

Implies chromium-headless

lldb

Implies process-control

Combining Integrations

Integrations can be freely combined:

Development

# Full development environment
safehouse --enable=docker,kubectl,ssh,cloud-credentials -- aider

Security Considerations

High-risk integrations:

• docker — Socket access equivalent to root
• lldb — Task-port access and debugger capabilities
• cloud-credentials — Access to cloud provider credentials
• wide-read — Read access to entire filesystem

Only enable when necessary.

Safe integrations:

• clipboard — Limited to pasteboard
• spotlight — Read-only search
• cleanshot — Read-only media access
• process-control — Signalling only (no task-port)

Viewing Active Integrations

Use --explain to see which integrations are active:

safehouse --explain --enable=docker,kubectl --stdout

Output shows:

• Explicitly included integrations (from --enable)
• Implicitly included integrations (dependencies)
• Available but not included integrations