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-execis 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/Ubuntusudo apt install bubblewrap# Fedora/RHELsudo dnf install bubblewrap# Arch Linuxsudo pacman -S bubblewrapVerify 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:
-
Check what was blocked:
/sandbox:violations -
For a non-sensitive read path, add it to
allowedReadPathsin your config. A matchingdeniedPathsentry takes precedence, so an allow entry cannot expose a denied file or directory:{"sandbox": {"filesystem": {"allowedReadPaths": ["$HOME/.gitconfig","$HOME/.your-needed-path"]}}} -
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:
-
Check violations to see which domain was blocked:
/sandbox:violations -
Add the domain to the allowlist:
/sandbox:trust-domain api.example.com -
For services with many subdomains, use a wildcard:
/sandbox:trust-domain *.example.com -
Or add permanently to your config file under
sandbox.network.allowedDomains.
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:
-
Verify network filtering is enabled in your config:
{"sandbox": {"network": {"enabled": true}}} -
The proxy binds to
127.0.0.1on an automatically assigned port (port 0). Port conflicts are rare, but if another process is interfering, check with:lsof -i -P | grep LISTEN -
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: truein your config to let excluded commands run without sandbox wrapping:{"sandbox": {"allowUnsandboxedCommands": true}} -
Or add the specific command to
excludedCommandsif 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:
-
Verify sandbox is enabled:
/sandbox -
Run a command that should trigger a violation to test:
cat ~/.ssh/id_rsa -
Check violations again:
/sandbox:violations -
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-allowmode (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 enabledcat /proc/sys/kernel/unprivileged_userns_clone# Should output: 1If 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
- Sandbox Overview — How the sandbox works
- Commands Reference — All sandbox commands
- Configuration — Full config schema and adjustment options