> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/eugene1g/agent-safehouse/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues, sandbox denials, and debugging techniques

This guide helps you diagnose and fix common Agent Safehouse issues.

## Common Issues

<AccordionGroup>
  <Accordion title="Agent can't access files in my project" icon="folder-xmark">
    **Symptoms**: Agent reports permission errors or can't see project files.

    **Solution**: Verify workdir detection:

    ```bash theme={null}
    # Check effective workdir and grants
    safehouse --explain --stdout
    ```

    If workdir is incorrect:

    ```bash theme={null}
    # Override workdir explicitly
    safehouse --workdir=/path/to/project -- claude --dangerously-skip-permissions
    ```

    If you need additional directories:

    ```bash theme={null}
    # Grant extra read-only access
    safehouse --add-dirs-ro=/path/to/other/repo -- claude --dangerously-skip-permissions

    # Grant writable access
    safehouse --add-dirs=/tmp/scratch -- claude --dangerously-skip-permissions
    ```
  </Accordion>

  <Accordion title="Nested sandbox errors with Electron apps" icon="atom">
    **Symptoms**: `forbidden-sandbox-reinit` or `sandbox initialization failed: Operation not permitted`.

    **Cause**: Electron apps have their own sandbox that conflicts with `sandbox-exec`.

    **Solution**: Launch with `--no-sandbox` flag:

    ```bash theme={null}
    safehouse --enable=electron -- /Applications/Claude.app/Contents/MacOS/Claude --no-sandbox
    ```

    ```bash theme={null}
    safehouse --enable=electron -- "/Applications/Visual Studio Code.app/Contents/MacOS/Electron" --no-sandbox
    ```
  </Accordion>

  <Accordion title="Git operations fail" icon="code-branch">
    **Symptoms**: `git` commands fail with permission errors.

    **Solution**: Git support is enabled by default. Check if you need SSH access:

    ```bash theme={null}
    # For git-over-ssh workflows
    safehouse --enable=ssh -- claude --dangerously-skip-permissions
    ```

    SSH metadata (`~/.ssh/config`, `~/.ssh/known_hosts`) is readable by default. Private keys require `--enable=ssh`.
  </Accordion>

  <Accordion title="Environment variables missing" icon="dollar-sign">
    **Symptoms**: Agent can't find API keys or environment configuration.

    **Solution**: Safehouse uses a sanitized environment by default.

    Pass specific variables:

    ```bash theme={null}
    safehouse --env-pass=OPENAI_API_KEY,ANTHROPIC_API_KEY -- codex --dangerously-bypass-approvals-and-sandbox
    ```

    Or inherit full environment:

    ```bash theme={null}
    safehouse --env -- codex --dangerously-bypass-approvals-and-sandbox
    ```

    Or load from file:

    ```bash theme={null}
    safehouse --env=./agent.env -- codex --dangerously-bypass-approvals-and-sandbox
    ```
  </Accordion>

  <Accordion title="Docker commands fail" icon="docker">
    **Symptoms**: `docker` commands return permission errors.

    **Solution**: Docker socket access is opt-in:

    ```bash theme={null}
    safehouse --enable=docker -- claude --dangerously-skip-permissions
    ```
  </Accordion>

  <Accordion title="Clipboard integration doesn't work" icon="clipboard">
    **Symptoms**: Agent can't read from or write to clipboard.

    **Solution**: Clipboard access is opt-in:

    ```bash theme={null}
    safehouse --enable=clipboard -- claude --dangerously-skip-permissions
    ```
  </Accordion>
</AccordionGroup>

## Debugging Sandbox Denials

<Warning>
  Use `/usr/bin/log` (full path) for denial analysis, not shell-aliased `log` commands.
</Warning>

### Live Stream Denials

Watch sandbox denials in real-time:

```bash theme={null}
/usr/bin/log stream --style compact --predicate 'eventMessage CONTAINS "Sandbox:" AND eventMessage CONTAINS "deny("'
```

### Filter by Agent or Process

Filter denials for a specific process:

```bash theme={null}
/usr/bin/log stream --style compact --predicate 'eventMessage CONTAINS "Sandbox: 2.1.34(" AND eventMessage CONTAINS "deny("'
```

### Kernel-Level Denials

Capture additional low-level events:

```bash theme={null}
/usr/bin/log stream --style compact --info --debug --predicate '(processID == 0) AND (senderImagePath CONTAINS "/Sandbox")'
```

### Recent History

View recent sandbox events:

```bash theme={null}
/usr/bin/log show --last 2m --style compact --predicate 'process == "sandboxd"'
```

### Filter Common Noise

Suppress frequent harmless denials:

```bash theme={null}
/usr/bin/log stream --style compact \
  --predicate 'eventMessage CONTAINS "Sandbox:" AND eventMessage CONTAINS "deny(" AND NOT eventMessage CONTAINS "duplicate report" AND NOT eventMessage CONTAINS "/dev/dtracehelper" AND NOT eventMessage CONTAINS "apple.shm.notification_center" AND NOT eventMessage CONTAINS "com.apple.diagnosticd" AND NOT eventMessage CONTAINS "com.apple.analyticsd"'
```

Suppress dtrace noise:

```bash theme={null}
DYLD_USE_DTRACE=0 sandbox-exec -f policy.sb command
```

### Correlate with Filesystem Activity

Track filesystem operations:

```bash theme={null}
sudo fs_usage -w -f filesystem <pid> | grep -iE "open|create|write|rename"
```

## Converting Denials to Allow Rules

<Info>
  Denial log format: `deny(<pid>) <operation> <path-or-name>`
</Info>

<CardGroup cols={2}>
  <Card title="File Operations" icon="file">
    **Denial**: `deny(1234) file-read* /path/to/file`

    **Allow rule**:

    ```scheme theme={null}
    (allow file-read*
      (literal "/path/to/file")
    )
    ```
  </Card>

  <Card title="Sysctl Read" icon="gear">
    **Denial**: `deny(1234) sysctl-read kern.version`

    **Allow rule**:

    ```scheme theme={null}
    (allow sysctl-read
      (sysctl-name "kern.version")
    )
    ```
  </Card>

  <Card title="Mach Lookup" icon="network-wired">
    **Denial**: `deny(1234) mach-lookup com.apple.service`

    **Allow rule**:

    ```scheme theme={null}
    (allow mach-lookup
      (global-name "com.apple.service")
    )
    ```
  </Card>

  <Card title="Network" icon="globe">
    **Denial**: `deny(1234) network-outbound 127.0.0.1:8080`

    **Allow rule**:

    ```scheme theme={null}
    (allow network-outbound
      (remote ip "localhost:*")
    )
    ```
  </Card>
</CardGroup>

## Building a Profile from Scratch

If you need to create a custom profile:

<Steps>
  <Step title="Start with base policy">
    Create a minimal deny-all profile:

    ```scheme theme={null}
    (version 1)
    (deny default)
    ```
  </Step>

  <Step title="Run with log stream active">
    In one terminal, start the log stream:

    ```bash theme={null}
    /usr/bin/log stream --style compact --predicate 'eventMessage CONTAINS "Sandbox:" AND eventMessage CONTAINS "deny("'
    ```

    In another, run your command:

    ```bash theme={null}
    sandbox-exec -f policy.sb your-command
    ```
  </Step>

  <Step title="Map denials to allow rules">
    For each `deny(...)` event, add the minimum required allow rule to your profile.
  </Step>

  <Step title="Test full workflows">
    Exercise complete toolchain workflows (`git`, `npm`, `cargo`, etc.) since child processes inherit the sandbox policy.
  </Step>
</Steps>

<Note>
  See the [Prior Art](/reference/prior-art) page for profile examples and language reference.
</Note>

## Policy Inspection

Verify effective policy and grants:

```bash theme={null}
# Print assembled policy
safehouse --stdout

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

## Test Validation

Run Agent Safehouse's test suite (macOS only, outside existing sandbox):

```bash theme={null}
# Core tests
./tests/run.sh

# TUI simulation tests
./tests/e2e/run.sh

# Live agent tests (requires API keys)
./tests/e2e/live/run.sh
```

<Warning>
  Tests must run outside any existing sandboxed session. If you're already sandboxed, tests will fail.
</Warning>

## Getting Help

<CardGroup cols={2}>
  <Card title="FAQ" icon="circle-question" href="/reference/faq">
    Check frequently asked questions.
  </Card>

  <Card title="GitHub Issues" icon="github" href="https://github.com/eugene1g/agent-safehouse/issues">
    Report bugs or ask questions.
  </Card>
</CardGroup>