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 doctorIt 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 doctormisses verification problems. Read the lines too.
Two verification problems print !!, exit 0, and still stop a real run:
- A
BRIG_VERIFYvalue Brig does not recognize. BRIG_VERIFY=requirewith 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: trustCause. An older Homebrew does not have brew trust.
Fix. Update Homebrew:
brew --version
brew updateConfirm.
brew trust brig-sh/brigThe 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 buildbrig: no runtime found on PATH: install nerdctl, or point BRIG_RUNTIME_BIN at oneThe 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 hullThe cask installs hull:
brew install --cask brigRun 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 shWithout 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 claudeConfirm.
brig doctorThe 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_RUNTIMEConfirm.
brig doctorThe 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 directoryCause. 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 mineConfirm.
brig doctor mineThe 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
itCause. 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_BINConfirm.
brig doctorThe 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 unknownCause. The host lacks a tool that the rules need, or Brig cannot find the network namespace of the sandbox network. Brig exits 7.
Fix.
- Install
nftablesand thensenterof util-linux. - For a rootless install, make sure that rootless containerd runs:
$XDG_RUNTIME_DIR/containerd-rootless/child_pidexists.
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 claudeThe 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 claudeConfirm.
brig plan claudeThe 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 macOSCause. 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 claudevz 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 claudeWith 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 themCause. 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 doctorThe 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.shbrig 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, withexec sleep failed: No such file or directoryin 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 doctorThe 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 claudeRead 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 claudeBrig 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 claudeThe 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 claudeIf the guest is slow, set BRIG_READY_TIMEOUT in seconds. The default is 30.
BRIG_READY_TIMEOUT=60 brig run claudeLinux 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 shWithout sudo it does a rootless install, which needs host preparation. See Install.
Confirm.
brig run claudeThe 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 uncheckedUnder 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
uncheckedUnder 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 checkedOn 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 cosignRun 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 versioncosign 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 uncheckedUnder 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 claudeThe 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
uncheckedUnder 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 claudeIf brigd runs your boots, restart brigd with DOCKER_CONFIG set.
Confirm.
brig run claudeWithin 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=offIf 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 yourselfFor 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 claudeWarning 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 claudeThe 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 buildCause. 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 buildCause. 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 doctorThe 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 doctorThe 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-tokenCause. 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-tokenFor 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 mineThe 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 claudeThe 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=1Cause. 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=1Cause. 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 claudeA 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 claudeThe 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 claudeBrig then delivers the login on every command that reaches the sandbox. See Authentication.
Confirm.
brig stop claude
brig run claudeThe 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 disconnectedAn 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 lsIf 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 disconnectedEgress 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 claudeA 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 disconnectedThe 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 claudeTo 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 disconnectedThe 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 claudebrig 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
checkingCause. 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 claudeThe run reaches the agent. See Security.
Project behind a symlink refused #
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 checkingCause. 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/appIf 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 runwith the real directory after the ref.brig runwith--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 claudeThe PROJECT row names the real directory, and the refusal is gone. See Security.