Default Assumptions

Safehouse’s default behavior is designed to make common coding workflows functional while keeping sensitive paths and integrations opt-in. This page documents the baseline assumptions so you know what to expect without configuration.

Design Assumptions

The defaults follow four principles:

Agents should work with normal developer tooling

Package managers, compilers, git, and language runtimes work out of the box

Sensitive paths require explicit opt-in

SSH keys, cloud credentials, browser data, and clipboard access are denied

Least privilege should be practical to maintain

Defaults balance security with usability; constant overrides would get disabled

Final-deny overlays remain possible

You can always add stricter rules via --append-profile

Allowed by Default

Filesystem Access

Selected Workdir (Read/Write)

What: The project directory you’re working in (git root above CWD, or CWD if not in a git repo)Why: The agent must read and modify files in your current projectSecurity Note: The agent can only touch files in this directory, not other projects

System Runtime Paths (Read-Only)

What: /usr/bin, /bin, /usr/lib, /System/Library, /Library, etc.Why: Shells, compilers, system utilities, and macOS frameworks live hereSecurity Note: These are read-only and contain system software, not personal data

Toolchain Installation Directories (Read-Only to Read/Write)

What: Node.js, Python, Go, Rust, Bun, Java, PHP, Perl, Ruby installationsWhy: Language runtimes and their package managers must be accessibleSecurity Note: Read access to binaries; read/write to caches like ~/.npm, ~/.cargo, ~/.cache/pip

Package Manager Caches (Read/Write)

What: ~/.npm, ~/.cargo, ~/.cache/pip, ~/.gem, etc.Why: Package managers need to cache downloads for performanceSecurity Note: Caches contain public packages, not sensitive data

Git Integration Paths (Selective)

What: .git directories, ~/.gitconfig, ~/.gitignore_global, ~/.ssh/config, ~/.ssh/known_hostsWhy: Git operations need repo metadata and SSH config for remotesSecurity Note: SSH private keys are explicitly denied; only config/known_hosts allowed

Temporary Directories (Read/Write)

What: /tmp, /var/tmp, $TMPDIRWhy: Many tools write temporary files during operationsSecurity Note: Standard temp dirs, automatically cleaned by OS

Integrations

Core SCM Tools (Always On)

What: git, gh (GitHub CLI), glab (GitLab CLI)Why: Version control is fundamental to coding workflowsSecurity Note: Includes config files but not private keys

Agent-Specific Config Directories

What: Config dirs for the specific agent being run (e.g., ~/.aider for Aider, ~/.claude for Claude)Why: Agents need their own state/config directoriesSecurity Note: Only the profile matching the wrapped command is loaded

Network and Environment

Network Access (Full)

What: All network operations allowedWhy: Package registries, git remotes, MCP servers, and LLM APIs require networkSecurity Note: Safehouse does not prevent network exfiltration of allowed files

Sanitized Environment

What: Minimal environment variables by default (PATH, HOME, TMPDIR, etc.)Why: Shell startup files (which may contain secrets) are denied, so full env is not passedSecurity Note: Use --pass-env or --keep-env to explicitly pass needed vars

Process Execution

What: Ability to fork/exec child processesWhy: Agents run compilers, linters, tests, git, npm, etc.Security Note: Child processes inherit the same sandbox policy

Opt-In (Disabled by Default)

Enable these with --enable=<integration> only when needed:

Optional Integrations

clipboard

What: Clipboard read/write access via pbcopy/pbpasteEnable when: Agent needs to copy output or read clipboard inputRisk: Users often copy sensitive data temporarily

cloud-credentials

What: AWS, GCP, Azure credential filesEnable when: Agent needs to deploy or query cloud resourcesRisk: Cloud credentials can access production infrastructure

docker

What: Docker socket and related accessEnable when: Agent needs to build/run containersRisk: Docker socket can be used to escape sandbox via privileged containers

kubectl

What: Kubernetes config, cache, and krew stateEnable when: Agent needs to interact with k8s clustersRisk: k8s credentials can access production workloads

shell-init

What: Shell startup files (.zshrc, .bashrc, etc.)Enable when: Agent needs environment variables from shell configRisk: Shell files often contain API keys and tokens

ssh

What: Extended SSH agent socket and system SSH configEnable when: Agent needs full SSH functionality beyond git-over-sshRisk: SSH agent can be used to authenticate to remote servers

browser-native-messaging

What: Browser native messaging host integration pathsEnable when: Agent needs to communicate with browser extensionsRisk: Can interact with browser extensions that have elevated permissions

process-control

What: Host process enumeration and signaling (ps, kill)Enable when: Agent needs to manage local processesRisk: Can list all running processes and terminate them

lldb

What: LLDB debugger toolchain and task-port accessEnable when: Agent needs to debug running processesRisk: Debugger can inspect memory of all host processes

macos-gui

What: GUI app-related integration pathsEnable when: Agent is a desktop app or needs GUI featuresRisk: Access to app-specific state directories

electron

What: Electron integration (also enables macos-gui)Enable when: Agent is an Electron app (Cursor, VS Code, etc.)Risk: Access to Electron app directories and state

wide-read

What: Broad read-only visibility across /Enable when: You need maximum convenience and trust the agent completelyRisk: Can read most files on the system (defeats much of the sandbox purpose)

Agent/App Loading

all-agents

What: Load all agent profiles (not just the one matching the command)Enable when: Running one agent that invokes other agent CLIsRisk: Grants access to config dirs for all known agents

all-apps

What: Load all desktop app profilesEnable when: Running app-hosted agents that need multiple app configsRisk: Grants access to app-specific directories for all known apps

Explicitly Denied by Default

These are blocked even if parent directories are allowed:

These denials exist even if a broader allow rule might cover the path. Explicit denies take precedence.

SSH Private Keys

Paths: ~/.ssh/id_*, ~/.ssh/*_keyRationale: Private keys provide authentication to remote servers; not needed for git-over-ssh

Browser Profile Data

Paths: Browser cookies, sessions, profiles (Chrome, Firefox, Safari)Rationale: Contains authentication sessions and personal browsing data

Setuid/Setgid Executables

Paths: Any executable with setuid/setgid bit setRationale: These can be used for privilege escalation

Raw Device Access

Paths: Most of /dev (with exceptions for /dev/null, /dev/urandom, etc.)Rationale: Direct device access can bypass filesystem permissions

Operational Defaults for Common Scenarios

Daily Coding Agent Use

# Minimal permissions: workdir + system paths
safehouse claude --dangerously-skip-permissions

Granted: Workdir, system paths, toolchains, git Denied: SSH keys, cloud credentials, other repos, clipboard

Cross-Repo Read Context

# Add specific sibling repos read-only
safehouse --add-dirs-ro="$HOME/other-repo,/Volumes/shared/team-repo" -- aider

Granted: Main workdir (read/write) + specified repos (read-only) Denied: All other dirs outside workdir and explicit grants

Cloud Task Burst

# Enable cloud credentials only for this session
safehouse --enable=cloud-credentials -- claude deploy.md

Granted: AWS/GCP/Azure config files for deployment Denied: Credentials are revoked when command exits

Docker/k8s Workflow

# Enable container/cluster access
safehouse --enable=docker --enable=kubectl -- aider

Granted: Docker socket, k8s config Denied: Other cloud credentials, SSH keys

Local Process Triage

# Allow process listing without full debugger access
safehouse --enable=process-control -- goose

Granted: Process enumeration, signaling (ps, kill) Denied: LLDB debugger, memory inspection

IDE App-Hosted Agents

# For Electron apps like Cursor or VS Code
safehouse --enable=electron -- cursor

Granted: Electron app directories, GUI integration, macos-gui Denied: Other app profiles unless --enable=all-agents

Before You Enable Anything

Ask yourself these questions:

Is this required for the current task?

Or is it just convenient? Convenience today can be a security incident tomorrow.

Can I scope it narrower?

Instead of --enable=wide-read, use --add-dirs-ro for specific paths.

Can I make it read-only?

Use --add-dirs-ro instead of --add-dirs if the agent only needs to read.

Should this be temporary?

Enable for a single command rather than adding to your shell alias.

How to Override Defaults

Grant Additional Directories

# Read-only access to specific paths
safehouse --add-dirs-ro="/path/to/docs,/path/to/reference" -- aider

# Read/write access to additional directories
safehouse --add-dirs="/path/to/shared/workspace" -- claude

Enable Optional Integrations

# Single integration
safehouse --enable=clipboard -- aider

# Multiple integrations
safehouse --enable=docker --enable=cloud-credentials -- claude

Apply Custom Policy Overlays

# Append a custom .sb file (loaded last, overrides all other rules)
safehouse --append-profile="$HOME/.config/agent-safehouse/local.sb" -- claude

Example local.sb:

;; Deny access to a specific file even if workdir is allowed
(deny file-read* (home-subpath "workdir/secrets.txt"))

;; Allow read-only access to a machine-specific path
(allow file-read* (subpath "/Volumes/Shared/Engineering"))

Use --append-profile for machine-specific exceptions that shouldn’t live in shared repo config.

Explain Current Settings

# See what would be granted without running a command
safehouse --explain --stdout

# With optional integrations
safehouse --enable=docker --enable=clipboard --explain --stdout

Trust Workdir Config

By default, .safehouse config files in project directories are ignored for security.

# Explicitly trust the current workdir's .safehouse file
safehouse --trust-workdir-config -- aider

Only use --trust-workdir-config in repos you control. A malicious .safehouse file could weaken the sandbox.

Summary Table

Category	Default	Why	Override
Workdir	✅ Read/Write	Agent must modify project files	`--workdir=""` to disable
System paths	✅ Read-Only	Required for shells, compilers	Cannot disable
Toolchains	✅ Read-Only (+ RW caches)	Language runtimes and package managers	Cannot disable
Git integration	✅ Config only	Version control workflows	Cannot disable
SSH keys	❌ Denied	Not needed; high risk	`--enable=ssh` (not recommended)
Cloud credentials	❌ Denied	Opt-in for cloud tasks	`--enable=cloud-credentials`
Clipboard	❌ Denied	Opt-in when needed	`--enable=clipboard`
Docker	❌ Denied	Opt-in for container workflows	`--enable=docker`
Shell startup	❌ Denied	Often contains secrets	`--enable=shell-init`
Network	✅ Allowed	Package managers, git, APIs	Cannot disable (by design)
Other repos	❌ Denied	Deny-first model	`--add-dirs` or `--add-dirs-ro`

Next Steps

Getting Started

Install Safehouse and run your first sandboxed agent

Customization

Learn how to create custom policies for specific needs

Debugging

Diagnose and fix sandbox denial issues

Policy Architecture

Understand how policy assembly works

Get Started

Core Concepts

Usage

Advanced

Operations

Agent Compatibility

Documentation Index

​Default Assumptions

​Design Assumptions

​Allowed by Default

​Filesystem Access

​Integrations

​Network and Environment

​Opt-In (Disabled by Default)

​Optional Integrations

clipboard

cloud-credentials

docker

kubectl

shell-init

ssh

browser-native-messaging

process-control

lldb

macos-gui

electron

wide-read

​Agent/App Loading

​Explicitly Denied by Default

SSH Private Keys

Browser Profile Data

Setuid/Setgid Executables

Raw Device Access

​Operational Defaults for Common Scenarios

​Daily Coding Agent Use

​Cross-Repo Read Context

​Cloud Task Burst

​Docker/k8s Workflow

​Local Process Triage

​IDE App-Hosted Agents

​Before You Enable Anything

​How to Override Defaults

​Grant Additional Directories

​Enable Optional Integrations

​Apply Custom Policy Overlays

​Explain Current Settings

​Trust Workdir Config

​Summary Table

​Next Steps

Getting Started

Customization

Debugging

Policy Architecture

Build docs developers (and LLMs) love

Default Assumptions

Design Assumptions

Allowed by Default

Filesystem Access

Integrations

Network and Environment

Opt-In (Disabled by Default)

Optional Integrations

Agent/App Loading

Explicitly Denied by Default

Operational Defaults for Common Scenarios

Daily Coding Agent Use

Cross-Repo Read Context

Cloud Task Burst

Docker/k8s Workflow

Local Process Triage

IDE App-Hosted Agents

Before You Enable Anything

How to Override Defaults

Grant Additional Directories

Enable Optional Integrations

Apply Custom Policy Overlays

Explain Current Settings

Trust Workdir Config

Summary Table

Next Steps