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 brigThe 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 brigIf 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 | shinstall.sh installs brig, brigd, brig-broker, hull and cosign.
curl -fsSL https://brig.sh/install | sudo shThis 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 shWarning After this install, run every
brigcommand as root, for examplesudo 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/kvmand/dev/vhost-vsock - the
uidmappackage - 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
uruncmust be a build of the branch that the bundle uses. AgenericBootprofile never becomes ready on auruncrelease. - A
genericBootprofile also needshviandoras. 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 buildmake 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 doctorOn 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-missingThe 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 IDSecurity 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.