Guides

Guest image requirements

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.

Each entry names the source file it comes from. 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 resolves each binary through the guest's PATH, except /bin/true.

When each binary is needed #

sleep. On the hull path, the image's entrypoint runs. A macOS-only image can work without sleep and then fail on Linux. The images of the published profiles are multi-arch, so treat sleep as required.

bash. Only brig sh uses it. Without bash, you cannot open a shell to look inside a sandbox.

sh to rm. A profile with neither volumes: nor files: returns before any of these run (deliverSecretFiles in internal/wrap/secretfiles.go). Two of the eight built-in profiles declare them: claude-code and claude-desktop, the two that deliver a credential as a file.

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 and not at boot.

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.

Right after Brig creates a file, the answers must be:

Paths and kernel interfaces #

• /proc, mounted. Brig reads /proc/self/mountinfo to find what is already a mountpoint. It does not run mountpoint -q, because a minimal image can lack that binary. Brig reads /proc/swaps to detect swap. If that file shows 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 pins each hostmount at /run/brig/persist/<escaped path> while the tmpfs goes over its real location, then binds it back. /run keeps the pin off the workspace, so the pin never reaches host disk and never survives a boot. The built-in profiles run the guest as root, so the agent can reach the pin. See persistRoot in internal/wrap/secretfiles.go.
• /bin/true, at that literal path. The probe does not resolve true through PATH.
• tmpfs in the guest kernel. It must accept size=, mode=0700, nodev and nosuid. ramfs does not qualify, because it ignores size= without a message. A guest process can then exhaust the sandbox's memory through a mount Brig created. See TmpfsOptions in internal/profile/volumes.go.
• No swap. The guest has no swap today. A guest that turns swap on stops the run.

Guest user #

Brig derives the guest account from the profile's guestHome:. It takes the last path element: /home/claude means the user claude (GuestUser in internal/profile/profile.go). There is no field to set the user separately.

The image must meet three requirements:

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 #

The five shipped agent profiles set guestHome: /root, so the guest is root. A rootless Linux install maps container uid 0 to the invoking user. That lets the guest open /dev/kvm and own the workspace it writes. Each built-in profile carries the rationale next to the field. See Built-in profiles.

On a profile whose guest is root, the agent and the privileged execs are the same 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. The symlink guards in writeSecretFiles cover that case.

ubuntu sets guestHome to /root/work, so the derived name is work. That is not an account in that image. Nothing reads the name there, because the image already runs as root.

Root capabilities #

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

Brig never boots the bare way. It passes the profile's hypervisor and rootfs type. For a genericBoot profile it also passes the kernel and initrd annotations. See runArgs in internal/runtime/hull.go, and the nerdctl equivalent in internal/runtime/nerdctl.go.

Under a bare boot, mount -t tmpfs fails with permission denied, even in an image that works under Brig. For that reason, 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. Six of the eight 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 initrd, and passes them as two OCI annotations:

com.urunc.unikernel.bootKernel
com.urunc.unikernel.bootInitrd

The pair is the same on both operating systems (internal/runtime/boot.go). Brig never reads them from the image's metadata, so an image cannot nominate a file on the host.

The kernel file is named Image on arm64 and bzImage on x86_64. The initrd is container-initrd on both.

If BRIG_BOOT_ASSETS is set, the files come from that directory on both platforms. Brig does not fetch into that directory.

A zero-length file counts as missing.

With genericBoot, the image does not have to carry a guest agent. The agent comes out of the initrd and is copied into the guest. Brig can then exec into a stock image.

See genericBoot in Profiles for the field itself.

Tmpfs mounts #

Brig creates one tmpfs per kind: tmpfs entry in the profile's volumes:. The mount point is guestHome plus the entry's path. The options are size=<size>,mode=0700,nodev,nosuid, with a default size of 64m.

The guest home is a host directory. A tmpfs over part of it has no path to the host, which keeps a credential off host disk.

How Brig makes the mounts depends on the runtime.

On both runtimes, 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. Brig hands it to the guest user last. There is no window in which the agent can plant a symlink at a credential's path.

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 host-side path in the guest home before the sandbox is created. It goes through an os.Root, so a planted symlink is refused, not written through. Brig also creates the guest-side target under a directory root owns.

Brig does not change the kind of something already there. A bind mount onto the wrong kind of target fails. 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, not what the image had. The guest home mount already hides the image's copy. What the agent writes into the tmpfs is gone at shutdown. A hostmount under the tmpfs keeps its path.

After the tmpfs is on, Brig checks that every hostmount is a mountpoint. If one is not, the run fails.

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 atomically: temp file, then rename. Rename onto a mountpoint returns EBUSY. So Brig creates, checks and fills the file through the three execs listed under sh 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

A profile of your own must set mem: and cpus:. Brig refuses a profile that leaves either at zero, so a file without them is skipped and not imported.

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

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:

Distroless images are in the same position. The static and base variants carry no shell and no coreutils, so every row above applies except the last two. They ship an /etc/passwd with a nonroot user, and the missing bash is the smallest of the problems. The :debug variants add a busybox shell, which is still not the whole list.

Tip If you want a static binary in a tiny 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. A profile of your own must be one that Brig knows, through brig agent import.

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 supplies the hypervisor, the rootfs type, the generic-boot annotations and the capabilities described in Root capabilities.

The profile decides what the script checks:

The requirements run as root through the runtime's exec against the sandbox Brig created, one exec per line of the Binaries table. They report behaviour, not the presence of a file.

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 unsigned image.

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

The script is not part of CI, which has no registry access and no runtime to boot with. Run it against an image you build.

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.