brig docs

Help

Troubleshooting

On this page

Problems are grouped by stage. Find the message you saw, apply the fix, then run the confirm command.

Start with brig doctor #

brig doctor

It checks the host, the hypervisor, the runtime, the credential broker, the boot assets, the overlay root, cosign, the profiles, the secret store and brigd. Each check prints one line. A line marked !! names its fix.

Command What it adds
brig doctor <agent> Checks that agent's image too.
brig doctor --json Prints the same report as one document, for a script or a bug report.

Exit codes #

The table of exit codes is in CLI.

brig rm and brig logs on a ref with no sandbox exit 3 and name the ref you typed.

Checks brig doctor misses #

Only two lines in brig doctor change its exit status. They use the codes a run exits with. Every other line, a !! line included, prints its fix and leaves the exit status at 0.

Warning A script that reads only the exit status of brig doctor misses verification problems. Read the lines too.

Two verification problems print !!, exit 0, and still stop a real run:

  • A BRIG_VERIFY value Brig does not recognize.
  • BRIG_VERIFY=require with no cosign installed.

Print the setting before you rely on it:

echo "$BRIG_VERIFY"

require also refuses any image outside Brig's registry, ghcr.io/brig-sh/. claude-desktop and ubuntu are both outside it. brig doctor claude-desktop does not report that refusal.

A bare brig doctor also does not check the runtimeBin: field of a profile. See Profile runtimeBin is missing.

Install and runtime #

Homebrew rejects brew trust #

Error: Unknown command: trust

Cause. An older Homebrew does not have brew trust.

Fix. Update Homebrew:

brew --version
brew update

Confirm.

brew trust brig-sh/brig

The command runs without the error.

No runtime on PATH #

brig: no runtime found on PATH: brig drives hull on macOS, and none was there.
See https://github.com/brig-sh/brig#macos, or point BRIG_RUNTIME_BIN at a build
brig: no runtime found on PATH: install nerdctl, or point BRIG_RUNTIME_BIN at one

The exit code is 4 on both platforms.

Cause. The runtime is not installed, or not on PATH. On macOS this usually follows a from-source install of Brig.

Fix. Look for the runtime, then install it. See Install.

which hull

The cask installs hull:

brew install --cask brig

Run install.sh again, the way you ran it first. It installs the runtime bundle. For the whole machine:

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

Without sudo it does a rootless install, which needs host preparation. See Install.

If you have a build that is not on PATH, point Brig at it:

BRIG_RUNTIME_BIN=/path/to/hull brig run claude

Confirm.

brig doctor

The runtime line reads ok and names the binary it found.

Unknown BRIG_RUNTIME value #

brig: runtime unavailable: unknown BRIG_RUNTIME "podman" (want hull or nerdctl)

Cause. BRIG_RUNTIME names a runtime that Brig does not support. brig ls and brig info fail with the same message.

Fix. Print the value:

echo "$BRIG_RUNTIME"

Unset it, and Brig picks the runtime for your platform:

unset BRIG_RUNTIME

Confirm.

brig doctor

The runtime line reads ok.

Profile runtimeBin is missing #

brig: runtime unavailable: this profile's runtimeBin is /old/path/hull, which is
not there: stat /old/path/hull: no such file or directory

Cause. The runtimeBin: field of your profile names a binary that moved or was removed. A bare brig doctor does not check it, so its runtime line can read ok.

Fix. Open the profile and correct or remove the line:

brig agent edit mine

Confirm.

brig doctor mine

The runtime line reads ok and names the binary of that profile.

Docker drops the kernel annotation #

This error occurs on Linux only, for most built-in profiles.

brig: could not start the sandbox: this profile boots an unmodified image,
which needs the kernel passed as an OCI annotation; docker does not carry
annotations through to the runtime. Use nerdctl, or point BRIG_RUNTIME_BIN at
it

Cause. Brig found docker where it looks for nerdctl. Docker cannot give these profiles a kernel to boot, so Brig refuses before the boot.

Fix. Run install.sh, which installs the runtime bundle. If BRIG_RUNTIME_BIN names docker, unset it:

unset BRIG_RUNTIME_BIN

Confirm.

brig doctor

The runtime line does not name docker.

Policy refused on Linux #

On Linux, only nerdctl can enforce an egress policy. With docker, the refusal says to use nerdctl or to detach the policy.

When Brig cannot put the rules in place, the refusal contains this:

enforces the egress policy is unknown

Cause. The host lacks a tool that the rules need, or Brig cannot find the network namespace of the sandbox network. Brig exits 7.

Fix.

  1. Install nftables and the nsenter of util-linux.
  2. For a rootless install, make sure that rootless containerd runs: $XDG_RUNTIME_DIR/containerd-rootless/child_pid exists.

When the resolver did not start, the refusal quotes the start of its log, ~/.brig/egress/<sandbox>.log. Policies lists each refusal.

Confirm.

brig plan claude

The plan has no REFUSED row.

Shim shares the host kernel #

This error occurs on Linux only.

brig: refusing BRIG_CONTAINERD_RUNTIME=runc: that shim gives the guest the
host's own kernel, which is not the boundary brig provides. Unset
BRIG_CONTAINERD_RUNTIME to use the default microVM shim io.containerd.urunc.v2.
A sandbox already started on such a shim keeps it, and the next run would join
it by name: stop it first with brig stop <ref>

Cause. BRIG_CONTAINERD_RUNTIME names runc, crun, containerd-shim-runc-v1 or -v2, by name or by path. Those run the guest as a plain container on the host kernel. Brig exits 1. Brig allows a shim that it does not recognize, such as another microVM shim.

Fix. Unset the variable. If an older Brig started this sandbox on such a shim, also stop the sandbox:

unset BRIG_CONTAINERD_RUNTIME
brig stop claude

Confirm.

brig plan claude

The plan has no REFUSED row, and its ISOLATION row names io.containerd.urunc.v2.

hvi needs macOS 15 #

brig: the hvi hypervisor needs macOS 15 or newer (this is 14.5): its in-kernel
interrupt controller does not exist here. Set BRIG_HYPERVISOR=vz BRIG_NETWORK=shared
for this run, or upgrade macOS

Cause. Most built-in profiles use the hvi hypervisor backend, which needs macOS 15 or newer.

Fix. Upgrade to macOS 15 or newer and keep hvi.

To stay on the older macOS, use the vz backend. For one run:

BRIG_HYPERVISOR=vz brig run --network shared claude

vz cannot give a sandbox an isolated network, so this command uses a shared one. Brig does not promise that sandboxes on a shared network are separated. For later runs, put both BRIG_HYPERVISOR=vz and BRIG_NETWORK=shared in your shell profile. See Install.

Confirm.

brig run claude

With both settings applied, or on macOS 15 or newer with hvi, the run reaches the agent's prompt.

First boot #

Boot assets missing #

This line appears in the output of brig doctor:

!!  boot      assets missing at /Users/alex/.hull/store/assets
        run any agent once to fetch them, or set BRIG_BOOT_ASSETS to a directory that has them

Cause. Brig has not yet downloaded the kernel and initrd that most built-in profiles boot.

Fix. None. The line is normal before the first boot, and the next brig run fetches them. A run does not download into a directory that BRIG_BOOT_ASSETS names.

Confirm.

brig doctor

The boot line reads ok boot assets present at /Users/alex/.hull/store/assets.

Started without the launcher #

This happens on Linux only. brig doctor prints this line:

  !!  bundle    this brig is inside the runtime bundle, and its launcher did not run, so brig will not find the bundle's CNI plugins or boot assets
          run brig from /home/alex/.local/bin: export PATH="/home/alex/.local/bin:$PATH", or load the environment: . /home/alex/.local/share/brig/data/etc/brig-env.sh

brig run prints the same warning before it boots the sandbox.

Cause. The bundle's bin directory is on PATH ahead of the launcher in ~/.local/bin (/usr/local/bin on a node-wide install). Without the launcher, the run fails with one of these:

  • needs CNI plugin "bridge" to be installed in CNI_PATH ("/opt/cni/bin")
  • sandbox did not become ready, with exec sleep failed: No such file or directory in the log

Fix. Remove the sandbox while the bundle's bin directory is first on PATH. Then put the launcher directory first:

PATH="$HOME/.local/share/brig/data/bin:$PATH" brig rm ubuntu
export PATH="$HOME/.local/bin:$PATH"

Keep that order. Only a brig rm without the launcher removes the old network. If it stays, the next run through the launcher fails with failed to read from init socket: EOF.

Confirm.

brig doctor

The bundle line is gone, and the boot line reads ok.

Image pull or architecture failure #

brig: could not start the sandbox: <runtime error>

Cause. The detail after the colon says which of these applies:

Cause Fix
A registry Brig cannot reach Try again once the registry is reachable.
An image reference that does not exist Check the reference with brig info claude.
An image with no build for your architecture Drop the pinned tag, or pin the one for your machine (:arm64 or :amd64).

The published agents default to :root, which has builds for linux/arm64 and linux/amd64. A mismatch usually means that --image or BRIG_IMAGE pins a single-architecture tag that is not yours.

Fix. Print the image reference:

brig info claude

Read the error to find the cause. Then apply the fix from the table.

Under the default pull policy, Brig does not fetch a moving tag that was republished. To fetch it:

BRIG_PULL=always brig run claude

Brig does not publish some images, such as cursor. Brig says so before it reaches the registry. Build the image yourself and pass --image.

Confirm.

brig run claude

The sandbox boots.

Sandbox never became ready #

brig: sandbox did not become ready; check 'brig logs claude (or the runtime's own, hull logs <sandbox>)'

Cause. The sandbox started, but the guest did not answer in time.

Fix. Read the sandbox's log. It holds the errors of the guest. A virtiofsd::limits warning about open file descriptors is harmless.

brig logs claude

If the guest is slow, set BRIG_READY_TIMEOUT in seconds. The default is 30.

BRIG_READY_TIMEOUT=60 brig run claude
Linux hosts with their own urunc

A Linux host that installed its own urunc (BRIG_INSTALL_RUNTIME=0, or Brig 0.2.0 or earlier) also fails here, and brig doctor still reports ok. Install the runtime bundle. For the whole machine:

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

Without sudo it does a rootless install, which needs host preparation. See Install.

Confirm.

brig run claude

The run reaches the agent.

Images and verification #

cosign is not installed #

The message depends on BRIG_VERIFY.

Under BRIG_VERIFY=warn, the default:

brig: cannot verify image <image>: cosign is not installed (`brew install cosign`)
  ↳ booting it unchecked

Under BRIG_VERIFY=require nothing boots, and the exit code is 5:

brig: refusing to boot image <image>: cosign is
not installed (`brew install cosign`), so nothing could be checked
(BRIG_VERIFY=require). Install cosign, or set BRIG_VERIFY=warn to boot it
unchecked

Under BRIG_VERIFY=off Brig never looks for cosign, and the only line is:

brig: BRIG_VERIFY=off, so the signature and digest checks are skipped: the
guest image and the kernel it boots are not checked

On Linux the parentheses in the first two messages read Brig's install.sh brings one, or see https://docs.sigstore.dev/cosign/system_config/installation/.

Cause. The image is under Brig's registry, and Brig found no cosign to check its signature. Under warn it boots the image unchecked. Under require it refuses every image, Brig's own included.

Fix. Install cosign.

brew install cosign

Run Brig's install.sh again, install your distribution's package, or follow the cosign install page.

To boot without the check and stop the warning, set BRIG_VERIFY=off. It is safer to install cosign.

Confirm.

cosign version

cosign prints its version. The next run under BRIG_VERIFY=warn or require checks the image.

Registry unreachable during verification #

brig: cannot reach the registry to verify image <image>: <detail>
  ↳ the copy on disk could not be checked against what the registry serves
brig: Boot the cached copy unverified? [y/N]

Cause. Brig did not reach the registry, so nothing was checked. The usual cause is an offline host, or a captive portal.

If you answer no, Brig aborts:

brig: aborted: the registry could not be reached, so the image could not be
verified. Try again with the registry reachable, or set BRIG_VERIFY=off to
boot the cached copy unchecked

Under BRIG_VERIFY=require there is no prompt. Brig refuses, with the same exit code, 5.

Fix. Reconnect and run again. If you trust the copy on disk, answer y to boot it once unverified.

Confirm.

brig run claude

The run reaches signature verified with no prompt.

cosign did not answer #

brig: cannot verify image <image>: cosign did
not answer within 30s. It waits on docker-credential-desktop, set by
credsStore in /Users/you/.docker/config.json. Start the app that helper
belongs to, or run brig with DOCKER_CONFIG set to an empty directory (and
restart brigd with it set, if brigd is running)
  ↳ the copy on disk was not checked against what the registry serves
brig: Boot the cached copy unverified? [y/N]

Cause. A Docker credential helper in your Docker config.json did not answer, for example docker-credential-desktop while Docker Desktop is not running. If the message names no helper, see Registry unreachable during verification.

If you answer no, Brig aborts, and the error repeats the detail:

brig: aborted: the image was not verified: cosign did not answer within 30s.
<detail>. Try again once cosign answers, or set BRIG_VERIFY=off to boot it
unchecked

Under BRIG_VERIFY=require there is no prompt. Brig refuses, with exit code 5.

Fix. The images Brig boots are public, so cosign needs no credentials for them. Start Docker Desktop, or point DOCKER_CONFIG at an empty directory for the run:

DOCKER_CONFIG="$(mktemp -d)" brig run claude

If brigd runs your boots, restart brigd with DOCKER_CONFIG set.

Confirm.

brig run claude

Within a few seconds, the run prints brig: image and boot assets verified with no prompt.

Signature did not verify #

brig: image <image> claims to be published by
brig-sh, but its signature DID NOT VERIFY: <detail>
brig: Boot it anyway? [y/N]

Cause. The image is under Brig's registry, and its signature does not match the workflow that builds those images.

With no terminal to ask, Brig refuses:

brig: not a terminal, so there is nobody to ask: refusing
  → to boot it regardless:  BRIG_VERIFY=off

If you answer no, Brig aborts, with exit code 5:

brig: aborted: the image failed verification. Pull it again (BRIG_PULL=always),
or set BRIG_IMAGE to a digest you have checked yourself

For an image with no signature Brig can check, such as one from another publisher, Brig warns and continues under warn. An image under Brig's registry that fails the check, or cannot be checked, stops the run to ask.

Fix. The usual harmless cause is a stale local copy. Pull the image again:

BRIG_PULL=always brig run claude

Warning If it still fails and you do not know why, do not boot it. To get past the check, name a digest that you checked yourself.

Confirm.

brig run claude

The run reaches signature verified and boots.

Boot assets fail verification #

brig: refusing to boot: the boot assets in ~/.hull/store/assets are not the
bundle that verified, ghcr.io/nofireai/hull-assets:darwin-arm64
(sha256:e82a...): container-initrd is sha256:55d2..., not the sha256:05cb...
it lists. Delete both files there and run again to fetch the bundle, or set
BRIG_BOOT_ASSETS to that directory if they are your own build

Cause. The kernel and initrd on disk are not the files that the signed bundle lists. A file changed after the fetch, or an older tool fetched it. Brig refuses under warn as well as require, with exit 5.

Fix. Pick the row that matches your files:

Cause Fix
The files are not your own build Delete the two files the line names, then run again. Brig fetches the signed bundle again.
The files are your own build Point BRIG_BOOT_ASSETS at their directory. warn then states the difference and boots them.

See Security.

Runtime bundle kernel mismatch #

This error occurs on Linux.

brig: refusing to boot: the kernel and initrd in
/var/lib/brig/data/share/guest are not the ones the Linux runtime bundle's
signed record lists: bzImage is sha256:9c1e..., not the sha256:4f0a... it
lists. Re-run brig's install.sh to reinstall the bundle, or point
BRIG_BOOT_ASSETS at a directory of your own build

Cause. A kernel or initrd file in the Linux runtime bundle changed after the install, so it no longer matches the signed release. The same refusal appears when the release's signed checksums do not verify. Brig refuses under warn as well as require, with exit 5.

Fix. Pick the row that matches your host:

Cause Fix
The bundle's files were changed Run Brig's install.sh again, the way you ran it first: under sudo for a node-wide install, as yourself for a per-user one. It installs the bundle release that install.sh pins, which puts the bundle's files back.
The kernel is your own build Keep it in a directory of its own and point BRIG_BOOT_ASSETS there.
The bundle was released from a fork Its signature names the fork's release workflow. Set BRIG_VERIFY_RUNTIME_IDENTITY to it.

See Security.

Credentials #

Secret store could not be read #

brig: the mine sandbox needs gh-token from brig's secret store, which could
not be read: <cause>

Cause. Brig cannot tell whether the value is there. The run exits with code 6, the same code as a missing secret.

Fix. Run brig doctor:

brig doctor

The secrets line names the failure. Fix it, then run again:

Cause Fix
A locked keychain Open the keychain.
A keyring that is not running Start the keyring.
A missing permission Grant the permission.

Confirm.

brig doctor

The secrets line reads ok secrets keychain reachable, or names your platform's store.

Required secret is missing #

brig: missing secret "gh-token" needed by the mine sandbox -- create it
first with: brig secret create gh-token

Cause. A required secret has no value in Brig's secret store. A secret is required unless the profile declares required: false. The run exits with code 6. No built-in profile has a required secret, so the declaration is in your own profile (brig agent edit mine).

If two secrets are missing, the message lists one line for each.

Fix. Create the secret that the message names:

brig secret create gh-token

For a secret that the profile marks importable, the message names brig secret import <profile>. That command copies the value from your host.

Confirm.

brig info mine

The secret does not show as missing, and its name appears in the CREDENTIALS row.

Credential did not arrive #

List what Brig forwards, by name:

brig info claude

The output shows what reaches the guest and whether the guest will be authenticated. If the variable you expected is not listed, one of the causes below applies.

The variable is on the denylist #

brig: not forwarding ANTHROPIC_API_KEY: it is on the <profile> denylist
  ↳ it outranks the subscription credential, and would move this sandbox onto metered billing without saying so
  → to forward it anyway:  BRIG_ALLOW_DENIED=1

Cause. By default, Brig does not forward a key that moves the sandbox from your subscription to metered billing.

Fix. If you want metered billing, set BRIG_ALLOW_DENIED=1.

The value is an unresolved reference #

brig: not forwarding GH_TOKEN: it looks like an unresolved secret reference (op://...), not a credential
  → resolve it on the host before you run brig
  → to forward it as it is:  BRIG_ALLOW_REFS=1

Cause. A tool such as direnv left a secret-manager reference (scheme://...) unresolved. Inside the guest, that value produces "Invalid username or token".

This check does not apply to a stored secret or a profile literal.

Fix. Resolve the reference on the host, then run again.

The variable is empty #

Cause. Brig skips an unset or empty variable, so that it cannot shadow a value in the image.

The stored credential expired #

brig: the imported credential claude-credentials (<profile>) expired 3d ago
  → renew it on the host, then:  brig secret import <profile>

Cause. Brig forwards an expired stored credential as it is, and warns before boot.

Fix. Renew the login on the host. Then import it again:

brig secret import claude

A run reads only Brig's stored copy, so the import is necessary.

For a secret that you stored with --from-command, the second line names that command:

brig: the imported credential <name> (<profile>) expired 3d ago
  → renew it, then store it again:  brig secret import <profile> <name> --from-command '<command>'

Confirm the credential arrives #

brig info claude

The credential appears in the list of what Brig forwards, and the warning is gone.

Agent asks to log in again #

There is no error. The agent shows its login screen on a sandbox where you logged in before.

Cause. claude-code and herdr keep the Claude Code login in memory, never on host disk, so brig stop loses it. The other profiles keep their login in the guest home, where it survives a stop. That includes the app login of claude-desktop.

Fix. Import the login from this Mac into Brig's secret store, once:

brig secret import claude

Brig then delivers the login on every command that reaches the sandbox. See Authentication.

Confirm.

brig stop claude
brig run claude

The agent starts logged in.

Sessions and workspaces #

Sandbox restarted on brig sh #

Cause. Brig warns and recreates the sandbox in the five cases below. The guest home stays on the host. See Sessions.

Note Any other session on that sandbox is disconnected when it restarts.

A different guest home #

brig: the running sandbox is not mounting /Users/alex/work: its share went stale
  ↳ the directory was renamed or replaced, or the workspace changed
  ↳ brig restarts it, and any other session using this sandbox will be disconnected

An explicit --home or BRIG_WORKSPACE does not match the guest home that the running sandbox has.

The WORKSPACE column shows the guest home that a sandbox mounts:

brig ls

If you did not intend to change the guest home, remove the --home flag.

A network policy that changed #

brig: this sandbox is running under a different network policy than the one that applies now
  ↳ rules are fixed when a sandbox boots, so brig restarts it
  ↳ any other session using this sandbox will be disconnected

Egress rules are fixed at boot. A policy that you attach or detach on a running sandbox changes nothing that it can reach until the next brig sh or brig run restarts it.

Show the policy that a profile has bound, and whether Brig can enforce it:

brig policy check claude

A different posture #

brig: this sandbox was started with the isolated posture and --network asks for shared
  ↳ rules are fixed when a sandbox boots, so brig restarts it
  ↳ any other session using this sandbox will be disconnected

--network or BRIG_NETWORK names a posture that differs from the one the sandbox started with. A command that names no posture does not cause a restart. If you did not intend to change the posture, look for an exported BRIG_NETWORK in this shell.

The warning names the posture that the sandbox runs with. For a sandbox that a policy isolated, the name is isolated, even after you detach the policy.

A different project #

brig: the running sandbox has /Users/alex/app mounted as its project and this run names /Users/alex/other-app
  ↳ a share cannot be attached to a live sandbox, so brig restarts it
  ↳ any other session using this sandbox will be disconnected

The run names a different project directory than the one the session last used. A project is fixed at boot, like the guest home.

The PROJECT row, when there is one, names the project that the session last used:

brig info claude

To keep the sandbox up, pass the same directory, or none.

The guest is not answering #

brig: the log of the sandbox ends with
  ↳ exec sleep failed: No such file or directory
brig: the running sandbox is not answering
  ↳ its guest may have failed while booting
  ↳ brig restarts it, and any other session using this sandbox will be disconnected

The guest did not answer within BRIG_READY_TIMEOUT. The lines above the warning are the end of its log, and the restart deletes that log.

Read those lines. If the guest fails again on the restart, see Sandbox never became ready.

Confirm the sandbox stays up #

brig sh claude

brig ls lists the ref as running, and a second brig sh on it prints no restart warning.

Symlinked guest home refused #

brig: refusing to write <guest home>/.claude/.claude.json:
it is a symlink to "/Users/alex/.ssh/authorized_keys", and brig writes only
regular files inside the workspace. The workspace is mounted read-write as the
sandbox's home, so that link was put there from inside the sandbox, to have brig
-- which runs as you, on the host -- reach a file the sandbox cannot. Nothing
was written; inspect <guest home>/.claude/.claude.json and
remove it before running brig again: a symlink leads out of a directory brig is
checking

Cause. Brig writes state files into the guest home as you, on the host. It refuses to follow a symlink in place of one, and writes nothing.

Fix. A retry gives the same refusal. Brig writes only regular files there, so you or the sandbox created the link. Inspect the path that the message names. Then remove the link, or point the guest home at another directory.

Brig refuses a --home that is a symlink in the same way. Name the real directory.

Confirm.

brig run claude

The run reaches the agent. See Security.

brig: refusing to use /Users/alex/work/app as this run's project:
/Users/alex/work on the way to it is a symlink to "/Volumes/data/work", so the
sandbox would be handed a directory other than the one you named. Name the
real directory instead: a symlink leads out of a directory brig is checking

Cause. The sandbox can write the project, so it can replace any directory in it with a link. Brig refuses every link on the path, your own included, and names where it points.

Brig still follows a link in a directory that you cannot write, such as /tmp on macOS.

Fix. Name the real directory:

brig run claude /Volumes/data/work/app

If the message ends with "This session's project was remembered from an earlier run", the project came from an earlier brig run of this session. Replace it in one of two ways:

  • brig run with the real directory after the ref.
  • brig run with --no-project.

Until then, Brig refuses only the verbs that boot or join the sandbox. brig stop, brig rm and brig info still work, and brig info repeats the refusal.

Confirm.

brig info claude

The PROJECT row names the real directory, and the refusal is gone. See Security.

Type a command, a flag or an error message.