brig docs

Getting started

Install

On this page

Use Homebrew on macOS. Use install.sh on Linux, or on a Mac without Homebrew.

Method What it installs
Homebrew on macOS brig, brigd, brig-broker, hull, cosign and the shell completions
install.sh on macOS brig, brigd, brig-broker, hull and cosign
install.sh on Linux the runtime bundle, with brig, brigd and brig-broker from the Brig release, and cosign
Source build brig, brigd and brig-broker only, never a runtime

Platform support lists the hosts Brig runs on.

macOS with Homebrew #

You need a Mac with Apple silicon, macOS 15 or newer, and Homebrew (brew.sh).

brew tap brig-sh/brig
brew trust brig-sh/brig
brew install --cask brig

The cask puts every binary on PATH. brig-broker is the credential broker that a run with a route starts.

What you see What to do
Unknown command: trust Run brew update, then run brew trust again.
brew install fails, or gives an older version than you expected Use install.sh. The tap can lag the newest release.
The Mac runs macOS 14 Set the two variables in macOS 14 before you run an agent.

Unreleased builds #

Two more casks carry builds that are not releases.

brew install --cask brig-sh/brig/brig@main           # the tip of main
brew install --cask brig-sh/brig/brig@experimental   # a branch someone promoted
Cask When it moves Runtime it pulls
brig@main On every merge to main, so brew upgrade follows what is coming hull@main
brig@experimental When a maintainer promotes a particular ref to it hull@experimental

To get an unmerged branch onto brig@experimental, ask on the pull request, or run the channel workflow with that ref.

Warning Neither cask is supported. They can break, and they move without notice. Do not file a bug report against one, unless the bug is the reason you were asked to install it.

Only one of the three casks can be installed at a time. To go back to the supported build, remove the channel's hull as well:

brew uninstall --cask brig@main hull@main
brew install --cask brig

If you remove only brig@main, the hull@main that stays conflicts with the hull that the stable brig cask asks for.

install.sh #

You need curl, tar, and either sha256sum or shasum on PATH.

curl -fsSL https://brig.sh/install | sh

install.sh installs brig, brigd, brig-broker, hull and cosign.

curl -fsSL https://brig.sh/install | sudo sh

This is the install for the whole machine. Without sudo, the same command does a rootless install. See Linux for the difference.

The script downloads the newest v-tagged release, release candidates included. It checks every archive against a SHA-256 checksum. It installs to /usr/local/bin, and uses sudo when that directory is not writable.

The script stops in two cases:

Host Result
Neither sha256sum nor shasum on PATH The install stops.
Intel Mac The install stops before it writes anything. See Platform support.

hull ships as one archive of three executables: hull, vz-runner and hvi. If you move them, keep all three in the same directory.

install.sh does not install shell completions. See Completions to add them.

install.sh does not check the cosign signature on checksums.txt, even after it installs cosign. To check it yourself, see Release verification.

Settings #

BRIG_INSTALL_DIR=~/bin BRIG_VERSION=v0.2.0 sh install.sh
Variable Effect
BRIG_INSTALL_DIR Overrides the destination. Unset, the destination is /usr/local/bin.
BRIG_VERSION Pins a Brig release instead of fetching the newest one.
HULL_VERSION Pins a hull release. Brig and hull are versioned independently.
BRIG_INSTALL_HULL=0 Skips hull, and leaves macOS without a runtime.
BRIG_INSTALL_COSIGN=0 Skips cosign, and leaves the boot chain unverified.
BRIG_INSTALL_ROOTLESS=1 Linux only. Asks for the rootless bundle from a node-wide install. See Rootless installs.
BRIG_INSTALL_RUNTIME=0 Linux only. Skips the runtime bundle. See Existing runtime.

Put BRIG_INSTALL_DIR on your PATH. Otherwise the boot check reports "no tooling" although cosign is installed. install.sh warns you.

cosign #

cosign verifies the container image behind an agent. For a genericBoot profile, seven of the nine shipped profiles, it also verifies the kernel, the initrd and the guest agent that the sandbox boots. If a cosign is already on PATH, install.sh does not install another.

Without cosign on PATH, those checks report "no tooling". In the default mode Brig prints a warning, and still fetches and boots the assets. To make that a refusal, install cosign and set HULL_VERIFY=require and BRIG_VERIFY=require.

cosign is a 130 MB download, the largest one in the install. install.sh pins it by version and by hash.

Gatekeeper rejects the macOS build of cosign, which is ad-hoc signed upstream. It runs only because a curl download carries no quarantine attribute.

Linux #

There are two ways to install on Linux. The difference is whether you run install.sh under sudo.

With sudo: for the whole machine Without sudo: rootless, for your user
Command curl -fsSL https://brig.sh/install | sudo sh curl -fsSL https://brig.sh/install | sh
Who runs Brig root only, for example sudo brig doctor the user who installed it
Host preparation none a user with root prepares the host once. See Rootless installs
Tree /var/lib/brig ~/.local/share/brig
Launcher /usr/local/bin/brig ~/.local/bin

The install for the whole machine is the default:

curl -fsSL https://brig.sh/install | sudo sh

Warning After this install, run every brig command as root, for example sudo brig doctor. A run as a normal user fails. To give other users their own runtime, see Rootless installs.

A Linux sandbox is a microVM, which does not share the host kernel as a container does. The boundary differs from the one on macOS. See Security for what each one keeps out.

What the bundle installs #

install.sh installs the runtime bundle that brig-standalone-linux publishes. The bundle holds the runtime, the guest kernel and a private containerd. install.sh pins the tag of the bundle and checks it against its checksums.

install.sh replaces the bundle's own brig and brigd with the Brig release, and adds brig-broker. So BRIG_VERSION selects the Brig version on Linux too.

The brig on PATH is the bundle's launcher. Do not put the bundle's bin directory on PATH. A brig from there runs without the launcher's environment, and Brig warns about it. See Troubleshooting.

With the bundle, install.sh ignores BRIG_INSTALL_DIR, says so, and puts the binaries into the bundle's tree.

Rootless installs #

Run install.sh as a normal user, without sudo, to install everything under $HOME:

curl -fsSL https://brig.sh/install | sh
Path What goes there
~/.local/share/brig The tree
~/.local/bin The launchers
A systemd user unit Your own containerd

This install writes nothing outside your home and never asks for sudo. It ignores BRIG_INSTALL_DIR. An unprivileged install always takes the rootless bundle. The plain bundle refuses one and installs nothing.

BRIG_INSTALL_ROOTLESS=1 selects the rootless bundle for a node-wide install. Each user can then run brig-ctl rootless against the shared tree.

For either rootless route, a user with root must prepare the host once:

  • a subuid range
  • access to /dev/kvm and /dev/vhost-vsock
  • the uidmap package
  • an AppArmor profile, on Ubuntu 24.04 and later

The installer reports the missing items before it unpacks anything. The bundle's docs/rootless.md explains what each item is for.

When the bundle's installer stops, install.sh says so. Do what the installer printed, then run the same install command again.

A host that also has a node-wide install

On such a host, /usr/local/bin/brig is the launcher of the node-wide install. It runs when /usr/local/bin comes first on PATH. Put ~/.local/bin ahead of it:

export PATH="$HOME/.local/bin:$PATH"

install.sh warns when another brig comes first on PATH.

oras #

A host with the runtime bundle does not need oras. Brig boots the kernel and initrd that the bundle carries.

On a host without the bundle, oras fetches the boot bundle for a genericBoot profile. The boot bundle is the kernel and container-initrd that let an ordinary container image boot as a guest.

Profiles Need oras without the bundle
claude-code, codex, gemini, grok, herdr, opencode, ubuntu Yes
claude-desktop, cursor No

On such a host, a genericBoot run fails when the kernel and initrd are missing and oras is not on PATH. The error names the artifact to fetch by hand and the directory to put it in.

claude-desktop cannot run on Linux. See Platform support.

nft and nsenter #

Brig enforces an egress policy on Linux with nftables. A run under a policy needs nft, from the nftables package, and nsenter, from util-linux, on the host. Without them, Brig refuses the run with exit code 7. A run with no policy does not use them. See Policies.

Existing runtime #

BRIG_INSTALL_RUNTIME=0 skips the bundle and installs brig, brigd and brig-broker alone. Use it on a host that already has nerdctl, containerd and urunc.

  • That urunc must be a build of the branch that the bundle uses. A genericBoot profile never becomes ready on a urunc release.
  • A genericBoot profile also needs hvi and oras. Without the bundle, you install both yourself.
  • Runtimes covers the full command surface each runtime needs.
docker and other shims

docker. docker is accepted in place of nerdctl for an image that carries its own kernel. Brig refuses a genericBoot profile on docker and does not attempt the run. Seven of the nine shipped profiles are genericBoot.

Other shims. BRIG_CONTAINERD_RUNTIME can name another microVM shim. Brig refuses a shim that it knows shares the host kernel: runc, crun or the runc shim binaries containerd-shim-runc-v1 and -v2, by name or by path.

Source build #

You need Go 1.26.0 or newer.

git clone https://github.com/brig-sh/brig
cd brig
make build

make build writes brig, brigd and brig-broker into the current directory. It does not build a runtime. The build needs no signing and no entitlement.

A hull built from source cannot boot a sandbox without a Developer ID certificate. See Runtimes for what that needs.

Verify the install #

brig version
brig doctor

On a Linux install for the whole machine, run both under sudo.

brig version prints the version you installed. brig doctor prints one line per check, marked ok, !! or --.

Line Meaning
ok beside runtime Brig found the runtime, and where.
!! beside boot Normal before you run an agent. Brig fetches boot assets on first use.
!! anywhere else The line names the fix beside it.

Next: Quickstart.

Release verification #

This step is optional. You need cosign. You also need checksums.txt, checksums.txt.pem and checksums.txt.sig, downloaded with the archive from the release page.

cosign verify-blob \
  --certificate checksums.txt.pem \
  --signature checksums.txt.sig \
  --certificate-identity-regexp \
    '^https://github\.com/brig-sh/brig/\.github/workflows/release\.yml@refs/tags/v' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  checksums.txt

shasum -a 256 -c checksums.txt --ignore-missing

The first command verifies that the Brig release workflow signed checksums.txt. The second command checks every archive against that file.

The macOS binaries also carry a Developer ID signature, notarized with Apple. Gatekeeper checks it:

spctl -a -vv -t install "$(which brig)"   # source=Notarized Developer ID

Security says what each check proves.

Platform support #

Host Supported
Mac, Apple silicon, macOS 15 or newer Yes
Mac, Apple silicon, macOS 14 Yes, with BRIG_HYPERVISOR=vz BRIG_NETWORK=shared
Intel Mac No
Linux, x86-64 or arm64 Yes, with the runtime bundle install.sh installs

The project tests on macOS 26. Brig also runs on macOS 15.

macOS 14 #

The hvi backend needs macOS 15. On an older macOS, Brig refuses a run on hvi. Seven of the nine shipped profiles ask for hvi. To run them on macOS 14, set two variables:

Setting Why
BRIG_HYPERVISOR=vz Selects the vz backend, so the run does not hit the hvi minimum
BRIG_NETWORK=shared, or --network shared on each run Those profiles ask for isolated networking, which vz cannot provide

A shared network does not promise to separate sandboxes. See Networking.

claude-desktop limits #

claude-desktop is a graphical profile, and the one built-in profile that Linux cannot run.

Requirement Detail
macOS The Linux runtime refuses a graphical profile. The refusal names macOS as the host where the profile can run.
Apple silicon The image is published for arm64 only.
The vz backend vz is the only one of the three backends with a console. hvi and qemu refuse a graphical profile.

brig agent ls lists claude-desktop on every platform and marks neither limit.

Intel Mac #

An Intel Mac has no runtime, because hull needs Apple silicon.

install.sh refuses an Intel Mac before it writes anything. Other routes do not. The release publishes a darwin/amd64 archive of brig and brigd, and a source build succeeds. A run then fails at the runtime check, because Brig finds no hull.

Type a command, a flag or an error message.