FAQ

Frequently asked questions about Agent Safehouse

Common questions about using and configuring Agent Safehouse.

General

What is Agent Safehouse?

Agent Safehouse is a macOS sandbox wrapper for LLM coding agents built on sandbox-exec. It uses a deny-first security model with composable policy profiles to give agents access only to the files and integrations they need.

It’s designed as a practical hardening layer for daily agent workflows, not a perfect security boundary against determined attackers.

Which agents does it support?

Agent Safehouse supports major coding agents including:

• Claude Code
• Cursor (agent mode)
• Aider
• Codex
• Amp
• Gemini CLI
• Goose
• Kilo
• Pi
• And more

The sandbox automatically detects agents and applies appropriate profiles. You can also use --enable=all-agents to load all agent profiles at once.

Does it work on Linux or Windows?

No, Agent Safehouse is macOS-only. It uses sandbox-exec, which is specific to macOS.

For cross-platform sandboxing, see Anthropic’s sandbox-runtime.

Is it safe to use with sensitive projects?

Agent Safehouse reduces risk by limiting agent access, but it’s not a perfect security boundary. Consider it a hardening layer.

It helps with:

• Accidental file access outside project scope
• Limiting agent access to credentials and sensitive paths
• Reducing network exposure

It doesn’t protect against:

• Determined attackers with sandbox escape exploits
• Malicious agents actively trying to bypass restrictions
• Vulnerabilities in the agent software itself

For sensitive work, combine sandboxing with other security practices: code review, separate environments, and minimal credential access.

What's the performance impact?

Minimal. sandbox-exec is lightweight and built into macOS. The overhead is primarily from policy evaluation on file access, which is negligible for typical agent workflows.

Configuration

How does workdir detection work?

Agent Safehouse automatically detects your working directory:

1. Starts from current directory ($PWD)
2. Searches up for git root (.git directory)
3. Uses git root if found, otherwise uses current directory
4. Grants read/write access to the detected directory

You can override this:

# Explicit workdir
safehouse --workdir=/path/to/project -- claude --dangerously-skip-permissions

# Disable automatic workdir grant
safehouse --workdir= --add-dirs=/path/to/project -- claude --dangerously-skip-permissions

Verify detection:

safehouse --explain --stdout

What's allowed by default?

By default, Agent Safehouse allows:

• Workdir access: Read/write to detected project directory
• Core integrations: Git and SCM CLIs
• Toolchains: Node, Python, Rust, Go, etc.
• System runtime: Libraries, shells, compilers
• Network: Full network access
• SSH metadata: Config and known_hosts (not private keys)

See the Default Assumptions page for complete details.

How do I enable Docker, kubectl, or cloud CLIs?

These integrations are opt-in. Enable them with --enable:

# Docker socket access
safehouse --enable=docker -- claude --dangerously-skip-permissions

# Kubernetes config/cache
safehouse --enable=kubectl -- claude --dangerously-skip-permissions

# Cloud credentials (AWS, GCP, Azure)
safehouse --enable=cloud-credentials -- claude --dangerously-skip-permissions

# Multiple integrations
safehouse --enable=docker,kubectl,cloud-credentials -- claude --dangerously-skip-permissions

How do I grant access to additional directories?

Use --add-dirs-ro (read-only) or --add-dirs (read/write):

# Read-only access to reference repos
safehouse --add-dirs-ro=/repos/shared-lib:/repos/docs -- claude --dangerously-skip-permissions

# Writable access to scratch space
safehouse --add-dirs=/tmp/scratch -- claude --dangerously-skip-permissions

# Single file access
safehouse --add-dirs-ro=~/.gitignore -- claude --dangerously-skip-permissions

Multiple paths are colon-separated (:).

Can I use a config file?

Yes, create a .safehouse file in your project directory:

cat > .safehouse <<'EOF'
add-dirs-ro=/repos/shared-lib
add-dirs=/tmp/scratch
enable=docker,kubectl
EOF

Then run with --trust-workdir-config:

safehouse --trust-workdir-config -- claude --dangerously-skip-permissions

Only use --trust-workdir-config in projects you control. Config files can escalate privileges.

How do I pass environment variables?

Safehouse uses a sanitized environment by default. Pass variables explicitly:

# Specific variables
safehouse --env-pass=OPENAI_API_KEY,ANTHROPIC_API_KEY -- claude --dangerously-skip-permissions

# All environment
safehouse --env -- claude --dangerously-skip-permissions

# From file
safehouse --env=./agent.env -- claude --dangerously-skip-permissions

Desktop Apps

How do I sandbox Claude Desktop or VS Code?

For Electron apps, use --enable=electron and launch with --no-sandbox:

# Claude Desktop
safehouse --enable=electron -- /Applications/Claude.app/Contents/MacOS/Claude --no-sandbox

# VS Code
safehouse --enable=electron -- "/Applications/Visual Studio Code.app/Contents/MacOS/Electron" --no-sandbox

For VS Code with multiple agent extensions:

safehouse --workdir=~/projects --enable=electron,all-agents,wide-read -- "/Applications/Visual Studio Code.app/Contents/MacOS/Electron" --no-sandbox

Why do I need --no-sandbox?

Electron apps have their own built-in Chromium sandbox. When you run sandbox-exec around Electron, you create nested sandboxes, which causes errors.

The --no-sandbox flag disables Electron’s internal sandbox, allowing sandbox-exec to be the only sandbox layer.

What about the one-file Claude launchers?

Agent Safehouse provides ready-to-use launchers:

# Online launcher (downloads latest policy)
curl -fsSL https://raw.githubusercontent.com/eugene1g/agent-safehouse/main/dist/Claude.app.sandboxed.command \
  -o ~/Downloads/Claude.app.sandboxed.command
chmod +x ~/Downloads/Claude.app.sandboxed.command

# Offline launcher (embedded policy)
curl -fsSL https://raw.githubusercontent.com/eugene1g/agent-safehouse/main/dist/Claude.app.sandboxed-offline.command \
  -o ~/Downloads/Claude.app.sandboxed-offline.command
chmod +x ~/Downloads/Claude.app.sandboxed-offline.command

Double-click to launch Claude Desktop in a sandbox. The workdir will be the folder containing the launcher file.

Advanced Usage

Can I customize the sandbox policy?

Yes, use --append-profile to add custom rules:

safehouse --append-profile=/path/to/custom.sb -- claude --dangerously-skip-permissions

Create a custom profile:

;; custom.sb
(allow file-read*
  (home-literal "/.lldbinit")
  (home-subpath "/Library/Application Support/CleanShot/media")
)

;; Deny sensitive paths
(deny file-read* file-write*
  (home-subpath "/.aws/credentials")
)

Rules in --append-profile are loaded last and take precedence.

How do I create machine-specific defaults?

Use a shell wrapper with environment variables:

# ~/.zshrc
export SAFEHOUSE_APPEND_PROFILE="$HOME/.config/agent-safehouse/local-overrides.sb"

safe() {
  safehouse \
    --add-dirs-ro="$HOME/reference-docs" \
    --append-profile="$SAFEHOUSE_APPEND_PROFILE" \
    "$@"
}

claudeset() { safe claude --dangerously-skip-permissions "$@"; }

This keeps machine-specific settings out of shared project configs.

How do I debug what's in the policy?

Inspect the assembled policy:

# Print full policy
safehouse --stdout

# Explain workdir and grants
safehouse --explain --stdout

# Save policy for inspection
safehouse --stdout > policy.sb

Can I use this with CI/CD?

Yes, but consider whether sandboxing adds value in CI environments:

Useful for:

• Testing sandbox compatibility
• Validating agent behavior under restrictions
• Hardening agent-driven deployments

May not be needed:

• CI already runs in isolated containers
• Overhead may slow builds
• Sandbox policy maintenance adds complexity

If using in CI, install and run as normal:

curl -fsSL https://raw.githubusercontent.com/eugene1g/agent-safehouse/main/dist/safehouse.sh -o /usr/local/bin/safehouse
chmod +x /usr/local/bin/safehouse
safehouse --workdir="$GITHUB_WORKSPACE" -- your-agent

What if I need broader file access?

Use --enable=wide-read for broad read-only visibility:

safehouse --enable=wide-read -- claude --dangerously-skip-permissions

This is a convenience mode that grants extensive read access. Use it only when necessary and understand the trade-offs.

For specific paths, prefer explicit grants:

safehouse --add-dirs-ro=/path/one:/path/two -- claude --dangerously-skip-permissions

Troubleshooting

How do I see what's being denied?

Use macOS unified logging:

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

See the Troubleshooting page for detailed debugging techniques.

Why are my tests failing?

Agent Safehouse tests require:

1. macOS with sandbox-exec
2. Not running inside an existing sandbox

If you’re already sandboxed, tests will fail. Exit the sandbox or run tests in a non-sandboxed terminal.

Verify you’re outside a sandbox:

if [ -n "$APP_SANDBOX_CONTAINER_ID" ]; then
  echo "Running in sandbox"
else
  echo "Not sandboxed"
fi

Where can I get help?

Troubleshooting Guide

Common issues and solutions.

GitHub Issues

Report bugs or ask questions.

Contributing

How can I contribute?

Contributions are welcome! See the Contributing Guide for:

• Project structure
• Policy authoring guidelines
• Testing requirements
• Pull request process

Key areas for contribution:

• New agent profiles
• Toolchain support
• Documentation improvements
• Test coverage

How do I add support for a new agent?

1. Create a profile in profiles/60-agents/<agent-name>.sb
2. Add tests in tests/sections/
3. Run ./scripts/generate-dist.sh
4. Test with the actual agent
5. Submit a pull request

See existing agent profiles for examples.