brig docs

Guides

Guest image requirements

On this page

Brig boots an OCI image and then runs commands inside it. The commands are a readiness probe, the mounts that keep a credential off host disk, and the write of the credential file. An image must carry what those commands need.

A stock distribution image meets every requirement. The list matters when you build a smaller image. To check an image you built, see Checking an image.

Guest images for the built-in profiles are open source, built in brig-sh/community-images. That repository documents how to build an image from scratch, at bring-your-own-image.md. Profiles covers the fields that name the image and hand it a credential.

Binaries #

Brig finds each binary through the guest's PATH, except /bin/true.

Binary Why Brig runs it
/bin/true The readiness probe. Brig runs it until it succeeds
cat Reads a marker file in the guest home, /proc/self/mountinfo and /proc/swaps. Also writes a credential, as sh -c 'cat > "$1"' with the value on stdin
sh Three short scripts: create a credential file with set -C, write the value into it, create a mount target
stat stat -c '%F|%U|%a' proves that the target of a credential is a regular file of the right ownership and mode before the value goes into it. stat -c %s proves that it is not empty afterwards. stat -f -c %T reports the filesystem that a path sits on
mount mount -t tmpfs covers a directory that the profile declares. mount --bind keeps each hostmount in place under it
mkdir Creates mount targets, as mkdir -p and inside a shell script as mkdir -p -- "$(dirname "$1")"
dirname Used inside that same script. It is an external command, not a shell builtin
chown Hands the covered directories to root across a credential write and back to the guest user afterwards. Also sets the owner of the credential file
chmod Sets the mode that a files: binding declares
rm rm -f -- at the credential path before Brig creates it, so a planted symlink is removed and not followed
sleep Linux only. The sandbox runs sleep infinity so that it outlives each exec
bash brig sh runs bash -l. brig sh <agent> <command...> runs bash -lc '"$@"' bash <command...>. brig sh <agent> -c '<script>' runs bash -lc '<script>'. This applies to every profile, whatever its binary: field says
The profile's binary: brig run execs it, such as claude or codex

When each binary is needed #

Binaries Needed when
/bin/true, cat, the profile's binary: Always
sleep On Linux
bash Someone runs brig sh, or brig run on a kind: shell profile
sh, stat, mount, mkdir, dirname, chown, chmod, rm The profile declares volumes: or files:

sleep. An image without sleep works on macOS and fails on Linux. For an image that must run on both, treat sleep as required.

bash. Without bash, you cannot use brig sh to look inside a sandbox that misbehaves.

sh to rm. Of the built-in profiles, only claude-code, claude-desktop and herdr declare volumes: or files:. If your profile forwards everything as environment variables, most of the table does not apply to it.

Warning If you build against the narrower list and later add one files: binding, the image needs the whole table. The run then fails at delivery, after the sandbox boots.

stat flags #

The -c and -f format flags are the GNU coreutils spelling. busybox also implements them if it is compiled with its format feature. BSD stat spells them differently and fails the run.

Format Required answer
%F, right after Brig creates a file regular file or regular empty file
%U The owner's name
%a The octal mode
-f -c %T The filesystem type as a word. tmpfs for what Brig mounted

Paths and kernel interfaces #

  • /proc, mounted. Brig reads /proc/self/mountinfo to see what is already mounted.
  • /proc/swaps. If it holds more than a header line, Brig does not hand the sandbox a credential. A tmpfs page in swap is a credential on a disk.
  • /run, writable by root. Brig keeps each hostmount under /run/brig while it mounts the tmpfs over its real location.
  • /bin/true, at that literal path. Brig does not resolve it through PATH.
  • tmpfs in the guest kernel. It must accept size=, mode=0700, nodev and nosuid. ramfs does not qualify. It ignores size=, so a guest process can exhaust the sandbox's memory through a mount that Brig created.
  • No swap. A guest that turns swap on stops the run.

Guest user #

Brig takes the guest account from the last path element of the profile's guestHome:. /home/claude means the user claude. There is no field to set the user separately.

Profiles guestHome Guest user
claude-code, codex, gemini, grok, herdr, opencode /root root
claude-desktop /home/claude claude
cursor /home/cursor cursor
ubuntu /root/work The derived name is work, which is not an account in that image. Nothing reads it there, because the image already runs as root

The image must meet three requirements:

Requirement Why
The account exists in the image Brig passes the name to chown inside the guest, so it must resolve in /etc/passwd
The image runs as that account The image's USER decides who the agent runs as. Set it to the guest user, with its home at guestHome
Root is available to exec as Brig mounts and writes credential files as root

An image whose home directory is /home/claude but which has no claude user fails the run with could not hand /home/claude/.claude to claude in the sandbox.

Root guests #

A rootless Linux install maps container uid 0 to the invoking user. A root guest can then open /dev/kvm and own the workspace that it writes.

On a profile whose guest is root, the agent and the privileged commands share one account. The boundary is the VM, not the guest account. Brig claims nothing about what the agent can reach inside the sandbox.

A profile whose guestHome sits under a real user's home keeps the two accounts apart, and Brig guards that case against planted symlinks.

Root capabilities #

The privilege to mount comes from how the image is booted.

Boot What root gets
Through Brig A microVM. Root has every capability
A bare hull run <image> or nerdctl run <image> An ordinary container. Root has no CAP_SYS_ADMIN, so mount -t tmpfs fails with permission denied

Test an image through Brig, not with a bare container run, which reports failures that Brig's boot does not have. script/check-guest-image.sh boots through brig run -d.

Generic boot #

genericBoot: true in a profile means that the image has no kernel and no urunc metadata. Seven of the nine built-in profiles set it. That includes ubuntu, which boots docker.io/library/ubuntu:latest unmodified. claude-desktop and cursor leave it off.

An image that carries its own kernel and urunc metadata leaves genericBoot off. This section does not apply to it.

Brig supplies the kernel and the initrd from host files, never from the image. See genericBoot in Profiles for where they live and how Brig fetches them.

Two consequences for the image itself:

  • It does not have to carry a guest agent. Brig copies one in from the initrd, so it can exec into a stock image.
  • On Linux, Brig refuses docker for a genericBoot profile. Use nerdctl, or point BRIG_RUNTIME_BIN at it. See Runtimes.

Tmpfs mounts #

Brig creates one tmpfs per kind: tmpfs entry in the profile's volumes:. It mounts each at guestHome plus the entry's path, or at the entry's at: when it names one. The options are size=<size>,mode=0700,nodev,nosuid, with a default size of 64m. claude-code mounts its tmpfs at /brig/claude.

These mounts keep a credential off host disk. The guest home is a host directory, and a tmpfs over part of it has no path to the host. A tmpfs with at: is not on the home share at all. See volumes.

The image needs nothing extra for either runtime. Brig checks the result from inside the guest:

  • Each covered directory must read as tmpfs, and each hostmount must not.
  • A guest that cannot answer fails the run.
  • The covered directory stays root-owned until every credential is written, and Brig hands it to the guest user last. The agent has no window in which to plant a symlink at the path of a credential.

Volumes and files #

volumes: and files: paths are relative to guestHome, and neither can escape it. See volumes and files in Profiles for the fields.

The mount covers the guest home entirely. A host directory is mounted over guestHome. Anything the image ships inside it is invisible once the sandbox is up. Dotfiles baked into /root at image build time never appear. Put them somewhere else, or have the agent create them on first run.

volumes: targets do not have to exist in the image. Brig creates the path in the guest home and the target in the guest. It refuses a planted symlink and does not write through it.

Brig does not change the kind of something already there. A directory in the guest home where the profile says file: true stops the run, and the error names both.

A tmpfs entry hides what the guest home had under that path. What the agent writes into the tmpfs is gone at shutdown. A hostmount under the tmpfs carves a path back out and keeps it. Brig checks that every hostmount is mounted, and fails the run if one is not.

files: targets must land in a declared tmpfs. Brig refuses a profile with a files: path that no tmpfs covers. An uncovered target puts a credential in the guest home, which is host disk.

A files: binding is an ordinary file, never a bind mount. Agents rewrite a credential by writing a temp file and renaming it, which fails on a mountpoint. So Brig creates, checks and fills the file through the three sh scripts in Binaries. The image needs a stat that answers them.

Minimal image #

A small image works if it carries the list:

FROM alpine:3.20

# The utilities above. busybox already provides most of them; coreutils and
# util-linux are here so you do not have to know which busybox features your
# base was compiled with.
RUN apk add --no-cache bash coreutils util-linux

RUN adduser -D -h /home/mine mine
COPY mine /usr/local/bin/mine

USER mine
WORKDIR /home/mine

Pair it with this profile:

name: mine
image: docker.io/me/mine:latest
guestHome: /home/mine
binary: mine
genericBoot: true
mem: 2048
cpus: 2

mem: and cpus: are required. Brig refuses a profile that leaves either at zero.

Import the profile, then check the image under it:

brig agent import mine.yaml
script/check-guest-image.sh docker.io/me/mine:latest mine
Base Result
Debian, Ubuntu Pass as they ship. bash, coreutils and util-linux are all in the base
Alpine busybox provides every name on the list. Whether a given busybox was compiled with the stat format flags Brig parses depends on the build. The two extra packages above remove that doubt

Run the script on your image to check either row.

Scratch and distroless #

FROM scratch with one static binary is missing the entire list. The failures, in rough order:

What is missing What happens
sleep On Linux, the sandbox exits immediately
/bin/true The readiness probe never passes. Brig waits out BRIG_READY_TIMEOUT and reports sandbox did not become ready, which says nothing about the image
cat Brig cannot read the guest home, so it treats the guest as not mounting this guest home
sh, stat, mount, mkdir, dirname, chown, chmod, rm No credential is delivered
/etc/passwd chown has no name to resolve. The guest user does not exist even if the binaries did
bash brig sh cannot get you in to look

Distroless images fail the same way. The static and base variants carry no shell and no coreutils, so every row above applies except /etc/passwd. They ship that file with a nonroot user. The :debug variants add a busybox shell, which still does not cover the whole list.

Tip To run a static binary in a small image, put it in a distribution base, not in scratch. The cost is a few megabytes of userland.

Checking an image #

script/check-guest-image.sh <image> [profile]

The script is script/check-guest-image.sh in the brig repository. It runs the requirements against a real image and prints one line per requirement.

The profile defaults to claude-code. To check under a profile of your own, import it with brig agent import first.

The script boots the image with BRIG_IMAGE=<image> brig run -d <profile>@image-check, in a scratch guest home. It removes the sandbox with brig rm at the end. A boot through Brig gives root the capabilities described in Root capabilities.

The profile decides what the script checks:

Profile value What the check uses it for
guestHome: The guest home
Last path element of guestHome: The user that chown has to resolve
binary: The agent CLI the last line looks for

The requirements run as root inside the sandbox that Brig created, one check per line of the Binaries table. They test behaviour, not only presence.

If the image does not come up, the script falls back to listing the image filesystem, and says so. Those checks are presence only.

The script sets BRIG_VERIFY=off for the boot, so Brig does not refuse an image that nobody has signed.

Warning The check is a real run of a real profile. The credentials that profile delivers are delivered into the image under test.

CI does not run the script. Run it yourself against an image that you build.

Exit status Meaning
0 Every requirement is met
1 Something is missing
2 There was nothing to check with: no brig, no runtime, or no such profile

The script never reports a pass it did not perform.

To print what the script plans to boot and stop before the boot, set BRIG_DRY_RUN=1. This checks the argument handling and the profile lookup on a machine with no runtime.

Type a command, a flag or an error message.