Help

BX takes an app you already have — Claude Code, Cursor, your terminal, VS Code, anything — and starts it inside a seatbelt sandbox. The app is not modified in any way. It keeps the project folder you point it at; credentials, shell history, mail and password manager containers drop out of its view.

Getting started

  1. Download BX, open the DMG and move the app to your Applications folder.
  2. Start BX and create a launcher: pick the app you want to run, the project folder it may access, and the protection mode.
  3. Check the policy preview. It lists every folder the session will be able to read and write.
  4. Save. The launcher appears in ~/Applications/bx/ and in the Launchpad — start it like any other app.

Launchers can be put into the Dock straight from the editor. From then on the sandboxed session is a double-click away, exactly like the app you started from.

What a session can and cannot do

BX is a file system read filter. Inside a session:

  • The project folders you listed are readable and writable.
  • Everything else in your home directory is walled off, including ~/.ssh, ~/.aws, ~/.zsh_history, Mail, Safari, Messages and password manager containers.
  • System tools, compilers and the network keep working. There is no network filter and no restriction on which processes may be spawned.

Scope

BX protects against curiosity and accidents, not against an attacker. Seatbelt escapes are documented, and whatever a process can read it can also transmit. Do not use BX as a containment for software you consider malicious.

Recording denied accesses

Turn on Record denied accesses in the launcher settings, or run bx run <mode> --observe on the command line. Every path the session was blocked from is written to ~/Library/Logs/bx/<launcher>.denied.log.

Show denied accesses lists everything a launcher was blocked from, across all its sessions. From there a path can be granted read or read-write access, which writes an RO: or RW: line into ~/.bxignore. Paths on the built-in protection lists ask for confirmation first — granting ~/.ssh is exactly the move the protection exists to prevent.

This is the fastest way to find out why a tool is not working: the list says what it did not get, and the button hands it over.

Configuration files

BX reads the same files as the bx command line tool:

  • ~/.bxconfig.toml — global configuration.
  • .bxignore — per project, in gitignore syntax, plus RO: and RW: lines for explicit grants.

The reference for both formats is the bx-mac repository.

Command line

The app binary is also the command line tool. It lives at BX.app/Contents/MacOS/bx.

bx run <mode> [workdir...] [-- app args]   start a sandboxed session
bx run <mode> --observe                    ... and report what was denied
bx dry <mode> [workdir...] [--sbpl]        show the resulting policy
bx create-launcher <mode> <workdir...>     generate a .app launcher
bx list                                    list the generated launchers

Frequently asked questions

Do I have to change or reinstall my apps?

No. BX starts the app that is already installed, from where it is installed, with the project folder you already work in. Nothing is copied, rewritten or moved into a special workspace. If you stop using BX, everything keeps working as before.

Which apps can I put into a sandbox?

Any app that is not already confined by macOS. The common ones — terminals, editors, IDEs — are recognised automatically, including the Electron quirks that would otherwise keep them from starting.

The case BX is built for is AI apps:

  • Claude and comparable MCP hosts. The value there sits in the servers rather than the app — npx some-mcp-server is third-party code running as a child process with your full rights. Quit the app before starting the launcher, see below.
  • Terminal harnesses — Claude Code, Codex, aider, opencode, goose.
  • Editors with AI extensions — VS Code, Cursor, Windsurf, Zed, JetBrains.

Everything else works too, it is just rarely worth the trouble. The apps that benefit are the ones that execute code you did not write.

Why is BX itself not sandboxed?

A confined process cannot apply a seatbelt profile — sandbox_apply fails with EPERM. That is also why BX is not available in the Mac App Store.

Why do launchers have to be created locally?

A bundle shipped inside a DMG would carry com.apple.quarantine and fail Gatekeeper unsigned. A launcher created on your own machine carries no such attribute, so no signing is needed.

A GUI app opens a window but is not sandboxed. Why?

If the app is already running unsandboxed, starting it a second time only opens a window in the existing process. Quit the app first, then start the launcher.

Does BX work with apps that are already sandboxed?

Apps that carry the App Sandbox entitlement are already confined by macOS. BX does not add anything for them.

Where are the logs?

Session logs and denied-access logs live in ~/Library/Logs/bx/, launchers in ~/Applications/bx/.