Skip to main content

Sandbox Troubleshooting

Common issues you may encounter when using the CLI sandbox, with symptoms, causes, and solutions.

"Sandbox runtime not available"​

Symptoms: Warning message when enabling sandbox. Commands run unsandboxed despite sandbox being enabled.

Cause: The sandbox runtime binary is not installed or not found in PATH.

Solution:

  • macOS: sandbox-exec is built into macOS. If missing, verify your macOS version supports it (macOS 10.5+). Check with:

    which sandbox-exec
  • Linux: Install Bubblewrap via your package manager:

    # Debian/Ubuntu
    sudo apt install bubblewrap

    # Fedora/RHEL
    sudo dnf install bubblewrap

    # Arch Linux
    sudo pacman -S bubblewrap

    Verify with:

    which bwrap

Command fails with permission denied​

Symptoms: A bash command fails or produces empty output. Error messages mention "deny" or "Permission denied".

Cause: The sandbox is blocking filesystem access that the command needs.

Solution:

  1. Check what was blocked:

    /sandbox:violations
  2. For a non-sensitive read path, add it to allowedReadPaths in your config. A matching deniedPaths entry takes precedence, so an allow entry cannot expose a denied file or directory:

    {
    "sandbox": {
    "filesystem": {
    "allowedReadPaths": [
    "$HOME/.gitconfig",
    "$HOME/.your-needed-path"
    ]
    }
    }
    }
  3. If a write path was blocked, remember that writes are restricted to your CWD. Either:

    • Change your working directory to where the file needs to be written
    • Temporarily disable the sandbox for that operation: /sandbox:disable

Private registry authentication fails​

Symptoms: A package command cannot find registry credentials, returns an authentication error, or reads an empty configuration file.

Cause: Credential stores such as ~/.npmrc and ~/.netrc are denied by default. On Linux, a denied file appears empty; adding it to allowedReadPaths does not override the deny rule.

Solution: Run the required authenticated command as a trusted operation outside the sandbox after reviewing it. Avoid copying credentials into the project or removing the default denied paths from shared configuration. Re-enable the sandbox before continuing agent commands.

Git staging or commits fail​

Symptoms: Git cannot create a lock file, stage files, or write a commit while the sandbox is enabled.

Cause: Your working directory's .git metadata is read-only inside the sandbox. Project .bike4mind configuration is also read-only, even when general write restrictions are disabled.

Solution: Review and run the required Git write as a trusted operation outside the sandbox, then re-enable the sandbox. Read-only Git commands and host-managed checkpoints remain available.

Network request blocked​

Symptoms: Commands that need network access fail. curl, wget, npm install, or API calls time out or return connection errors.

Cause: The domain is not in the network proxy allowlist.

Solution:

  1. Check violations to see which domain was blocked:

    /sandbox:violations
  2. Add the domain to the allowlist:

    /sandbox:trust-domain api.example.com
  3. For services with many subdomains, use a wildcard:

    /sandbox:trust-domain *.example.com
  4. Or add permanently to your config file under sandbox.network.allowedDomains.

tip

The violation log shows the exact domain that was blocked, including the method (CONNECT for HTTPS, GET/POST for HTTP). Use this to determine the correct domain to trust.

Linux: "Sandbox network on Linux requires socat"​

Symptoms: With network filtering enabled on Linux, every sandboxed command fails with this error.

Cause: Sandboxed commands on Linux have no direct network access and reach the proxy through socat, which is not installed.

Solution: Install socat with your package manager (sudo apt install socat, sudo dnf install socat or sudo pacman -S socat), or turn sandbox network filtering off.

If commands instead fail with sandbox: network relay failed to start, socat was found on your PATH but could not run inside the sandbox, usually because it is installed outside the system directories the sandbox mounts (/usr, /bin, /lib, /sbin, /etc). Install it through your system package manager.

macOS: a local test server is unreachable inside the sandbox​

Symptoms: With network filtering enabled on macOS, a sandboxed command that starts a server on a loopback port and then connects to it (for example, tests using supertest or listen(0), or a dev server checked with curl) fails with ECONNREFUSED, EPERM or curl: (7). The same command works on Linux.

Cause: On macOS the sandbox allows outbound loopback connections only to the network proxy port. Seatbelt cannot distinguish a server the command started itself from other services on your machine, so it blocks both.

Solution: Run the command outside the sandbox (/sandbox:disable, then /sandbox:enable afterwards). Turning network filtering off does not help on macOS, because with the network off the sandbox blocks all IP traffic, loopback included.

Proxy won't start​

Symptoms: /sandbox:enable succeeds but reports no proxy. Network filtering not active.

Cause: Either network.enabled is false or a port conflict prevented the proxy from binding. On Linux the proxy also needs a unix socket in your temp directory; if it cannot be created there (for example, $TMPDIR is not writable or its path is too long for a socket), the proxy does not start.

Solution:

  1. Verify network filtering is enabled in your config:

    {
    "sandbox": {
    "network": {
    "enabled": true
    }
    }
    }
  2. The proxy binds to 127.0.0.1 on an automatically assigned port (port 0). Port conflicts are rare, but if another process is interfering, check with:

    lsof -i -P | grep LISTEN
  3. Re-enable the sandbox:

    /sandbox:disable
    /sandbox:enable

Docker/Podman commands fail​

Symptoms: docker, podman, or watchman commands fail when sandbox is enabled with allowUnsandboxedCommands: false.

Cause: These commands are in the excludedCommands list. When allowUnsandboxedCommands is false, excluded commands are blocked entirely.

Solution:

  • Set allowUnsandboxedCommands: true in your config to let excluded commands run without sandbox wrapping:

    {
    "sandbox": {
    "allowUnsandboxedCommands": true
    }
    }
  • Or add the specific command to excludedCommands if it's not already there:

    {
    "sandbox": {
    "excludedCommands": ["docker", "watchman", "podman", "your-command"]
    }
    }

Violations not showing​

Symptoms: /sandbox:violations shows no results even though commands seem to be restricted.

Cause: Several possibilities:

  • Sandbox is not actually enabled (mode is disabled)
  • The command succeeded — no violation was generated
  • Violations are stored in a different location

Solution:

  1. Verify sandbox is enabled:

    /sandbox
  2. Run a command that should trigger a violation to test:

    cat ~/.ssh/id_rsa
  3. Check violations again:

    /sandbox:violations
  4. Violations are stored in ~/.bike4mind/violations.jsonl. Verify the file exists and has content.

Performance concerns​

Symptoms: Commands feel slower with sandbox enabled. Noticeable delay before command output appears.

Cause: Sandbox wrapping adds a small overhead per command — the runtime needs to create a profile, launch the sandboxed process, and parse results.

Solution:

  • Use auto-allow mode (the default when you /sandbox:enable). This avoids the additional delay of permission prompts.
  • For performance-critical workflows, temporarily disable the sandbox:
    /sandbox:disable
    # ... run performance-sensitive commands ...
    /sandbox:enable
  • The overhead is typically negligible for individual commands but can add up in tight loops.

macOS SIP or Linux AppArmor conflicts​

Symptoms: Sandbox fails to apply restrictions. Commands run but without expected isolation. Error messages about security policies.

Cause: System-level security policies (macOS System Integrity Protection, Linux AppArmor/SELinux) may interfere with sandbox-exec or bwrap.

Solution:

  • macOS: SIP generally does not conflict with Seatbelt profiles. If you see unexpected behavior, check Console.app for sandbox-related system logs.

  • Linux AppArmor: Bubblewrap needs permission to create user namespaces. Check:

    # Verify user namespaces are enabled
    cat /proc/sys/kernel/unprivileged_userns_clone
    # Should output: 1

    If disabled, enable with:

    sudo sysctl kernel.unprivileged_userns_clone=1
  • Linux SELinux: You may need to adjust SELinux policies to allow bwrap operations. Check audit logs:

    sudo ausearch -m AVC -ts recent

See Also​