Skip to main content
Integration profiles enable agents to interact with development tools, system services, and external platforms. They’re split into core integrations (always enabled) and optional integrations (opt-in via --enable).

​
Core Integrations (Always Enabled)

These integrations are included in every Agent Safehouse policy:

Git

Git configuration and SSH keys for git-over-ssh

SCM CLIs

GitHub CLI (gh) and GitLab CLI (glab)

Launch Services

macOS UTI resolution and app launching

Container Runtime Deny

Default-deny for Docker/Podman (must be explicitly enabled)

​
Git Integration

The Git profile provides read-only access to Git configuration and minimal SSH metadata: 
(allow file-read*
    (home-prefix "/.gitconfig")        ;; User gitconfig variants
    (home-prefix "/.gitignore")        ;; Global gitignore variants
    (home-subpath "/.config/git")      ;; XDG-style git config
    (home-literal "/.gitattributes")   ;; Global gitattributes
    (home-literal "/.ssh")             ;; Directory traversal
    (home-literal "/.ssh/config")      ;; SSH host aliases
    (home-literal "/.ssh/known_hosts") ;; Host key verification
)
The Git profile does NOT grant access to SSH private keys. For SSH key access, enable the SSH integration with --enable=ssh.

​
SCM CLI Integration

GitHub CLI (gh) and GitLab CLI (glab) for repository automation: 
(allow file-read* file-write*
    ;; GitHub CLI
    (home-subpath "/.config/gh")       ;; gh auth tokens/config
    (home-subpath "/.cache/gh")        ;; gh command cache
    (home-subpath "/.local/share/gh")  ;; gh extensions
    (home-subpath "/.local/state/gh")  ;; gh runtime state

    ;; GitLab CLI
    (home-subpath "/.config/glab-cli")
    (home-subpath "/.cache/glab-cli")
    (home-subpath "/.local/share/glab-cli")
)
Agents can read and write gh and glab authentication tokens. Treat agent access with appropriate caution for production repositories.

​
Optional Integrations

Optional integrations must be explicitly enabled with --enable=<name>:

​
Docker

Enable with: --enable=docker Grants access to Docker daemon sockets and configuration: 
(allow file-read* file-write*
    (literal "/var/run/docker.sock")          ;; Standard Docker socket
    (home-literal "/.docker/run/docker.sock") ;; Docker Desktop socket
    (home-literal "/.orbstack/run/docker.sock") ;; OrbStack socket
    (home-subpath "/.docker")                 ;; Docker config/contexts
    (home-subpath "/.colima")                 ;; Colima runtime state
    (home-literal "/.rd/docker.sock")         ;; Rancher Desktop
)
Docker socket access is high-risk: containers can mount host filesystems and execute arbitrary code. Only enable if your agent workflow requires container operations.

​
Kubernetes (kubectl)

Enable with: --enable=kubectl Grants access to kubeconfig, cluster certificates, and kubectl cache: 
(allow file-read*
    (home-subpath "/.kube")   ;; kubeconfig and certificates
    (home-subpath "/.krew")   ;; kubectl plugin manager
)

(allow file-write*
    (home-literal "/.kube/config")      ;; kubectl config updates
    (home-subpath "/.kube/cache")       ;; kubectl cache
    (home-subpath "/.krew")             ;; krew plugin installs
)

​
SSH

Enable with: --enable=ssh Grants access to SSH agent sockets while blocking private key access: 
;; Defense-in-depth: block private key reads
(deny file-read* file-write*
    (home-subpath "/.ssh")  ;; Block SSH keys
)

;; Allow SSH metadata
(allow file-read*
    (home-literal "/.ssh/known_hosts")
    (home-literal "/.ssh/config")
    (home-subpath "/.ssh/config.d")
    (literal "/private/etc/ssh/ssh_config")
)

;; SSH agent socket access
(allow file-read* file-write*
    (regex #"^/private/tmp/com\.apple\.launchd\.[^/]+/Listeners$")
)
The SSH profile uses defense-in-depth: it blocks ~/.ssh entirely, then selectively allows non-sensitive files like config and known_hosts. Private keys remain inaccessible.

​
Clipboard

Enable with: --enable=clipboard Grants access to macOS pasteboard for pbcopy and pbpaste: 
(allow mach-lookup
    (global-name "com.apple.pasteboard.1")  ;; Pasteboard service
    (global-name "com.apple.lsd.mapdb")     ;; Type lookups for pbcopy
)

​
Other Optional Integrations

Enable with: --enable=process-controlGrants broader process introspection and control beyond the sandbox:
  • process-info-pidinfo: Monitor all processes
  • process-info-setcontrol: Control process metadata
Use case: Debugging multi-process workflows
Enable with: --enable=shell-initAllows reading shell startup files:
  • ~/.bashrc, ~/.bash_profile, ~/.zshrc, ~/.zshenv
  • ~/.profile, ~/.config/fish/config.fish
Use case: Agents that need shell environment customization
Enable with: --enable=keychainGrants access to macOS Keychain for reading stored credentials:
  • com.apple.SecurityServer: Keychain daemon
  • com.apple.securityd: Security services
Warning: High-risk. Agents can read stored passwords and certificates.
Enable with: --enable=cloud-credentialsGrants access to cloud provider credential files:
  • ~/.aws (AWS CLI)
  • ~/.azure (Azure CLI)
  • ~/.config/gcloud (Google Cloud)
  • ~/.kube (Kubernetes)
Warning: High-risk. Agents can access cloud API credentials.
Enable with: --enable=macos-guiGrants accessibility and screen recording permissions for GUI automation:
  • Accessibility API access
  • Screen recording
  • Window management
Use case: Agents that control desktop applications
Enable with: --enable=spotlightGrants access to macOS Spotlight search API:
  • com.apple.metadata.mds: Spotlight daemon
Use case: Agents that need file search via mdfind
Enable with: --enable=lldbGrants debugger access for native code debugging:
  • LLDB configuration and scripts
  • Debug symbol cache
Use case: Agents debugging C/C++/Rust applications
Enable with: --enable=electronGrants Electron app runtime permissions (implies macos-gui):
  • Electron cache
  • GPU/rendering services
Use case: Running Electron-based agents or tools
Enable with: --enable=chromium-headlessMinimal Chromium permissions for headless browser automation:
  • No GPU acceleration
  • Minimal mach services
Use case: Headless browser testing (Playwright, Puppeteer)
Enable with: --enable=chromium-fullFull Chromium permissions including GPU and audio:
  • GPU acceleration
  • Audio output
  • Camera/microphone (if needed)
Use case: Full-featured browser automation
Enable with: --enable=1passwordGrants access to 1Password CLI (op):
  • ~/.config/op
  • ~/.cache/op
Use case: Agents retrieving secrets from 1Password

​
High-Risk Integrations

Some integrations grant significant system access and should be used with caution:

Docker

Risk: Container escape, host filesystem accessMitigation: Only enable for container workflows

SSH

Risk: SSH agent access (not keys themselves)Mitigation: Private keys are blocked; only agent socket allowed

Keychain

Risk: Access to stored passwords and certificatesMitigation: Only enable if agent needs credential access

Cloud Credentials

Risk: Cloud API access with user’s permissionsMitigation: Monitor agent cloud operations closely

​
Multiple Integrations

You can enable multiple integrations simultaneously: 
./bin/safehouse.sh \
  --enable=docker \
  --enable=kubectl \
  --enable=ssh \
  --enable=clipboard \
  -- ./my-devops-script.sh

​
Integration Dependencies

Some integrations automatically enable dependencies:
  • electron → implies macos-gui
  • chromium-full → implies GPU and audio services
  • Agent profiles → may imply keychain if they require credential access
Dependencies are resolved automatically by the policy assembly system.

​
Authoring Custom Integration Profiles

To create a custom integration:
  1. Choose the right directory:
    • 50-integrations-core/: Always enabled (use sparingly)
    • 55-integrations-optional/: Opt-in via --enable
  2. Create your profile: profiles/55-integrations-optional/my-integration.sb
  3. Add standard header: 
    ;; ---------------------------------------------------------------------------
;; Integration: My Integration
;; Brief description of what this integration enables.
;; Source: 55-integrations-optional/my-integration.sb
;; ---------------------------------------------------------------------------
  4. Grant minimal permissions: 
    (allow file-read* file-write*
    (home-subpath "/.config/my-integration")
)
  5. Consider defense-in-depth: 
    ;; Block sensitive data first
(deny file-read* (home-subpath "/.my-integration/secrets"))

;; Then allow safe paths
(allow file-read* (home-subpath "/.my-integration"))
  6. Regenerate and test: 
    ./scripts/generate-dist.sh
./tests/run.sh
Integration profiles should follow the principle of least privilege. Only grant the minimum permissions required for the integration to function.

​
Best Practices

Enable only what you need

Each integration increases the attack surface. Only enable integrations your workflow requires.

Understand the risks

Review the “High-Risk Integrations” section before enabling Docker, Keychain, or cloud credentials.

Use defense-in-depth

When authoring integrations, deny sensitive paths first, then allow safe subsets.

Test thoroughly

Always test custom integrations with real workflows before deploying to production agents.

Toolchains

Language-specific package managers and build tools

System Runtime

Foundation for process execution and system access

Build docs developers (and LLMs) love

Get started for freeTalk to us