brig docs

Compare

Brig and bubblewrap

On this page

Brig gives a coding agent a microVM with a kernel of its own, your project and nothing else, a network rule you write, and its login from your keychain. bubblewrap puts a process behind Linux namespaces on the host kernel, with the paths you bind and the whole network or none.

Both tools are open source and need no root. bubblewrap is the sandbox under Flatpak, and the sandbox that Claude Code and Codex build on Linux. Brig runs coding agents on macOS and Linux. Brig compared puts both beside the other tools.

At a glance #

Brig bubblewrap
Made for Coding agents Any process. Flatpak is its main user
Runs on macOS 15 or newer on Apple silicon, and Linux Linux only
Kernel One kernel per sandbox, under a hypervisor The host kernel, behind namespaces
Host files The project and the guest home, and nothing else from the host Only the paths you bind. The root starts as an empty tmpfs
Network An egress policy of hosts and ranges, enforced outside the guest. offline has no route out All or nothing. --unshare-net leaves only loopback
Credentials A secret store, delivered by name as a file or a variable --setenv, --unsetenv and --clearenv
Agent setup Eight built-in profiles, one command None. You write the bind list
Start Boots a kernel Starts a process
Needs Homebrew on macOS. The runtime bundle on Linux A kernel with unprivileged user namespaces
Licence Apache-2.0 LGPL-2.0-or-later

What Brig gives you #

A kernel the host does not share. The agent makes its system calls to a Linux kernel inside the microVM. hvi, the VMM Brig uses on macOS, treats the guest as hostile and runs inside a Seatbelt profile of its own. The boundary in hvi describes it. On Linux, urunc boots the sandbox on Cloud Hypervisor. A process under bubblewrap makes its system calls to the host kernel. A kernel bug reachable from inside the namespaces is a way out, and so is anything you mount, as the README warns.

One host, not all hosts. You write a policy, and the agent reaches those hosts and nothing else:

apiVersion: brig.sh/v1alpha1
name: locked-down
egress:
  default: deny
  allow:
    - host: api.anthropic.com

Brig enforces the policy at the gateway on macOS and in nftables on Linux. Both points are outside the guest's kernel. A run on a backend that cannot enforce the policy is refused with exit code 7. See Networking. bubblewrap has no network filter. The agent has the host's network or loopback. To allow one API, Claude Code and Codex add a proxy over a Unix socket that they bind in.

Your login, from your keychain. Brig keeps your logins in a secret store, backed by the keychain on macOS and the Secret Service on Linux. A profile names which secret reaches the agent, as a file where the agent already reads it. The file sits on a memory-backed mount and does not reach host disk. Brig reads the value again on every exec, so a rotated secret reaches a running agent. Credentials states each limit. bubblewrap passes environment variables.

The agent in one command. Brig ships eight profiles: Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, Grok, OpenCode and a plain Ubuntu shell. Each names the image, the paths the agent keeps, the credentials it gets and the variables it must not get. A session keeps the agent's state between runs, and brig rm removes it. Under bubblewrap, you find each path the agent reads, bind it, and update the list when a release changes it.

macOS. Brig runs on macOS and Linux. bubblewrap runs on Linux.

What bubblewrap does #

bubblewrap starts one process in new Linux namespaces. It always makes a mount namespace. The root of that namespace is an empty tmpfs, and you fill it with --bind and --ro-bind. A path you do not bind is absent.

--unshare-net gives the process a network namespace with only a loopback interface. --unshare-pid, --unshare-user and --unshare-ipc do the same for processes, users and IPC. bubblewrap sets PR_SET_NO_NEW_PRIVS. It can load a seccomp filter that you compile, and it ships none.

Its README states that the protection "is entirely determined by the arguments passed to bubblewrap", and that anything mounted into the sandbox "can potentially be used to escalate privileges". bubblewrap once had a setuid mode, and the project removed it. It needs a kernel that allows unprivileged user namespaces. Ubuntu 24.04 and newer block those by default with AppArmor.

When bubblewrap fits #

  • Start time. bubblewrap starts a process. Brig boots a kernel, so a cold run takes longer.
  • A Linux host with no KVM. Brig on Linux needs /dev/kvm. bubblewrap needs only user namespaces, so it runs in a VM or a CI runner that has no nested virtualization.
  • Linux desktop applications. Flatpak is built on bubblewrap, for an application that needs the display server, D-Bus and a portal.
  • One package. The README says most Linux distributions ship it. Claude Code's Linux setup installs it with apt-get install bubblewrap socat.

Run Claude Code under each #

Under Brig:

brig run claude ~/code/demo

Under bubblewrap, on Linux:

bwrap --ro-bind /usr /usr --ro-bind /etc /etc --symlink usr/lib /lib \
  --symlink usr/lib64 /lib64 --symlink usr/bin /bin \
  --ro-bind /run/systemd/resolve /run/systemd/resolve \
  --proc /proc --dev /dev --tmpfs /tmp \
  --ro-bind ~/.local/bin ~/.local/bin \
  --ro-bind ~/.local/share/claude ~/.local/share/claude \
  --bind ~/.claude ~/.claude --bind ~/.claude.json ~/.claude.json \
  --bind ~/code/demo ~/code/demo \
  --unshare-all --share-net --new-session --die-with-parent \
  --chdir ~/code/demo ~/.local/bin/claude

The bubblewrap line is for Claude Code's native installer on a host with systemd-resolved. It binds the installer's paths under ~/.local, the login and the settings in ~/.claude and ~/.claude.json, and the resolver's directory for DNS. It gives the agent the whole network, because bubblewrap has no filter between all and none. Claude Code's own sandbox writes a line like this for you, with a proxy for the network. Brig and the agents' own sandboxes compares that path.

Sources #

Read on 2026-10-06.

Type a command, a flag or an error message.