brig docs

Reference

CLI reference

On this page

The syntax of every Brig verb and flag, the environment variables, the JSON output and the exit codes. For a first run, see Quickstart. v0.5.0 removed the retired spellings, with two exceptions. Migration has the old-to-new table and the exceptions.

Everyday commands #

Command What it does
brig run claude ~/code/demo starts the sandbox and runs the agent against that project
brig run claude reruns the agent, remounting the project this session used last
brig run claude@refactor ~/code/demo starts a second, independent session of the same agent
brig sh claude opens a login shell inside the sandbox
brig ls lists every sandbox, with its ref, state and guest home
brig info claude prints the execution envelope, without booting anything
brig stop claude stops the sandbox and keeps its state on disk
brig rm claude stops the sandbox and removes it
brig network publish claude 3000 opens the agent's port 3000 on localhost:3000

Help #

Every verb answers --help, -h and brig help <verb> with its own usage, printed to stdout with a zero exit. These two lines print the same text:

brig run --help
brig help run

brig help alone prints the command list and the flags the verbs share. A word after the ref is the agent's, so brig run claude --help passes --help to the agent.

Verbs #

brig run #

Starts the sandbox if it is not already running, then runs the agent inside it.

brig run <ref> [project] [args...]
Operand Meaning
<ref> names the agent. With @<label>, it names one session of the agent. See Refs
[project] a host directory to mount. See Run line
[args...] go to the agent unchanged
Flag Meaning
--image IMAGE guest image to boot
--home PATH host directory mounted as the agent's home
--mem MB guest memory
--cpus N guest vCPUs
--no-project mount no project this run
-d, --detach start the sandbox and exit, without attaching
--skills copy your own ~/.claude skills and plugins into the guest home
--network MODE the sandbox's network posture
--offline shorthand for --network offline
--publish PORT open a guest port on the host

Run-line flags has the values and defaults for each flag.

Run the agent against a project:

brig run claude ~/code/demo

If you name no project, Brig remounts the project that this session used last:

brig run claude

Start a second session of the same agent, with a separate sandbox and guest home:

brig run claude@refactor ~/code/demo

Start the sandbox detached:

brig run -d claude ~/code/demo

Run with no project mounted, even one that this session ran with before:

brig run --no-project claude

Pass an argument to the agent after --:

brig run claude ~/code/demo -- --version

brig sh #

Opens a login shell inside the sandbox. If the sandbox is not running, sh starts it first.

brig sh <ref> [command...]
brig sh <ref> -c '<script>' [args...]

sh takes no project argument. The first bare word after the ref starts the guest command.

brig sh claude
brig sh claude ls /work

Each word after the ref is one argument to the guest command, as you typed it. The command runs under a login shell, which sets its environment. The guest does not parse the words again, so a pipe, a ; or a glob is not shell syntax there.

To run a script, put -c in front of it, as with sh -c. The login shell parses the script in the guest, so ~ and $HOME are the guest home:

brig sh claude -c 'ls /work | wc -l'
brig sh claude -c 'cat ~/.claude/settings.json'

Words after the script become its $0, $1 and so on. -ec, -xc and -uc work as with sh -c, and apply to the script, not to the login profile. Brig refuses -c with no script or an empty script before the sandbox starts.

Without -c, your own shell expands an unquoted ~, so it names your home on the host.

A single word with a space or a shell operator in it, such as brig sh claude 'ls | wc -l', is the name of a command. Brig prints a hint that names -c before the command runs.

brig stop #

Stops the sandbox and keeps its name and its state on disk.

brig stop <ref>

stop takes one ref and no list. If the sandbox is not running, stop reports no error.

brig stop claude

brig rm #

Stops the sandbox and removes it.

brig rm <ref> [--dry-run]
brig rm --all [-y] [--dry-run]
Flag Meaning
--all stop and remove every sandbox Brig has
-y, --yes confirm rm --all in advance, for example in a script. brig rm <ref> asks no question, so it refuses -y
--dry-run print what a real run removes, and exit 0 without removing anything

rm takes one ref and no list.

brig rm claude
brig rm --all
brig rm --all --dry-run
brig rm claude --dry-run

What rm <ref> deletes

Directory What rm does
A guest home Brig created, because the run named no --home or BRIG_WORKSPACE deletes it and prints its path
A guest home you named leaves it and prints its path
Your project leaves it and prints its path

Sessions lists what survives each command.

Case Exit Result
The ref has no sandbox 3 rm says so and forgets the session. The next run of that ref starts a new session. A guest home that Brig created stays until that run deletes it, and rm prints its path
Brig cannot update its record of sessions 1 rm keeps the session as it was
rm removes the sandbox and cannot delete its guest home 1 rm names the home. The next run of the session deletes what is left of the home before it boots

What rm --all does

Before it removes anything, rm --all lists each sandbox as its ref, sandbox name and state, one per line.

Case Result
stdin is a terminal asks for confirmation
stdin is not a terminal refuses, removes nothing, and exits 1
-y or --yes is passed removes without asking
there is nothing to remove asks nothing and exits 0

What --dry-run prints

Command Output
brig rm --all --dry-run the same list the prompt shows
brig rm <ref> --dry-run the one sandbox, and whether a real run deletes or leaves its guest home

A ref with no sandbox still exits 3 under --dry-run.

brig ls #

Lists every sandbox Brig knows about, one row each.

brig ls [-q]
Flag Meaning
-q print refs only, one per line, and skip a row with no derivable ref

The columns are REF, SANDBOX (the name the runtime uses), STATE and WORKSPACE (the guest home). Each line that -q prints is a ref that another verb accepts.

brig ls
brig ls -q

brig logs #

Streams the sandbox's log.

brig logs <ref> [--follow] [--tail N] [--raw]
brig logs --gateway [<ref>]
Flag Meaning
--follow keep streaming as new lines arrive
--tail N show the last N lines. Default: -1, meaning every line
--raw skip the formatting that Brig adds
--gateway read the log of the network gateway instead of the sandbox log
brig logs claude --follow
brig logs --gateway
brig logs --gateway claude
--gateway form Log it reads
no ref the gateway for sandboxes using shared
with a ref the gateway log of that sandbox

Only an isolated sandbox has a gateway log of its own: a new default hvi sandbox, or one with a policy. For any other sandbox, --gateway with a ref exits 3.

brig info #

Prints the execution envelope without booting anything.

brig info <ref>

The envelope has the sandbox name, the isolation, the guest home, the image and the verification mode. It also has the network, every published port and the credentials by name.

The isolation row names the backend and the guest root. The network row shows the posture of the running sandbox, and that of the next boot when it differs.

brig --verbose run prints the same envelope before it boots.

brig info claude

info fails only when it cannot resolve a required secret. See Optional secrets.

brig plan #

Prints the permissions of a run: the mounts, the network, the policies, the limits, the image, the runtime and the credentials. It boots nothing and opens no secret.

brig plan <ref> [project] [--json]

plan reads the run line as brig run does, --no-project included, so you can plan a first run before you start it. If brig run refuses to mount a project directory, the plan fails the same way.

brig plan claude
brig plan claude ~/code/demo
brig plan claude@refactor --json

With no policy bound, POLICY reads (none). The last row is a sha256: digest of the plan. The digest is the same for the same run and changes when any field changes. A release that rewords a sentence in the plan also changes it.

Refusals. When brig run would refuse the run before it starts anything, the plan opens with a REFUSED row that carries the message of the run. --json carries it as refused.reason. brig plan still exits 0, so a script must read refused, not the exit code.

The plan reports The plan does not report
A remembered project reached through a symlink A session name that another session already owns
A sandbox whose network Brig cannot determine An image that fails verification at boot
A hypervisor this host cannot boot On hvi under a policy, a gateway that does not confirm it can enforce the policy
What the backend cannot honor: a policy or a published port it cannot enforce, an isolated network on vz or qemu, a graphical profile on a backend with no display
A route whose secret is not in the store, or a store that does not open. The run stops with exit 6

Credentials. plan reads the secret store by name, as brig secret ls does, and never reads a value.

State When
resolved The store lists the name
unresolved The secret is missing from the store. A missing required secret stops the run with exit 6, and plan still exits 0
unknown plan cannot list the store, and nothing later in the chain has a value
withheld The run drops the credential at the denylist, or it is an unresolved secret-manager reference in the shell

A credential marked resolved can still fail at run time: another tool emptied the value, the stored item is damaged, you deny a keychain or keyring prompt, or a Linux keyring collection is locked. A missing required secret also stops the run with exit 6. The plan marks it unresolved and required, and does not set refused.

brig plan --json prints kind: Plan. Brig's CLI reference lists every field and how to verify the digest.

brig network #

Publishes guest ports on the host, lists them and closes them.

brig network publish <ref> <port>
brig network ls <ref>
brig network unpublish <ref> <port>
brig network unpublish <ref> --all
Subcommand What it does
publish opens a guest port on the host if the sandbox is running. If it is not, records the port for the next boot
ls lists the ports and whether each is open now, even when a required secret is missing
unpublish removes a publication
Flag Meaning
--all with unpublish, close every port the sandbox publishes
brig network publish claude 3000      # the agent's dev server, on localhost:3000
brig network publish claude 8080:80   # host 8080 carries guest 80
brig network ls claude                # what this sandbox publishes
brig network unpublish claude 8080    # close it again
brig network unpublish claude --all

--publish on brig run does the same as publish, at boot.

brig info also prints the ports, as the PORTS row of the execution envelope.

Port syntax

Ports use the docker syntax.

Written Means
3000 host 127.0.0.1:3000 carries guest 3000
8080:80 host 127.0.0.1:8080 carries guest 80
127.0.0.1:8080:80 the same, with the address written out
0.0.0.0:8080:80 offered to the network this host is on
5353:53/udp UDP instead of TCP

The host address defaults to 127.0.0.1, so the port is reachable from this machine only. To offer the port to the network this machine is on, write 0.0.0.0. The execution envelope shows the address of each port.

Lifetime of a publication

A publication belongs to the sandbox and outlasts a run.

Command Effect on publications
brig stop releases the host port and keeps the publication. The next brig run opens the same ports again
brig network unpublish removes one publication
brig rm removes all of them with the sandbox

Unpublishing

unpublish names a port by its host side only. brig network unpublish claude 8080 closes host port 8080, whatever guest port it carried. unpublish also accepts a value from the HOST column of brig network ls: brig network unpublish claude 0.0.0.0:8080 closes the port on that address only.

Platform support

Publishing needs the hvi backend. Both brig network publish and brig run --publish work there.

On vz and qemu, Brig refuses a run that publishes a port.

Ports are set only when the sandbox is created. brig run --publish works. brig network publish does not work on a running sandbox. It fails and tells you to remove the sandbox and run again with --publish.

brig doctor #

Checks your installation and prints one line per check.

brig doctor [agent] [--json]
Flag Meaning
--json print the same checks as a JSON array, each with name, state, finding and, when the check failed, fix

The checks are: the brig build, the host, the hypervisor, the runtime, the credential broker (broker), the boot assets, the overlay root (rootfs), cosign, the profile directory, the secret store, brigd and the image of an agent.

brig doctor
brig doctor claude
brig doctor --json

The first line is the build that brig version prints.

If a running brigd reports a different build, doctor marks it !! and tells you to restart brigd.

If you name an agent, the image line checks that agent's image. Without one, the line is -- and says how to name an agent. If the profile of the agent names a runtimeBin, the runtime and boot lines report on that binary instead of the one on PATH. An unknown agent exits 3.

Doctor checks the image against the trust policy a run of that agent uses, with the BRIG_VERIFY_* variables applied, the per-agent spelling first. The verify line names the variable its mode came from. When a variable replaces the shipped policy, a trust line names the registry, identity and issuer in use. With no agent named, only the global variables count.

The rootfs line says whether this host can build the overlay root that a genericBoot profile boots by default. When it cannot, the line names what is missing, and a run keeps the runtime's own root. The line is marked !! only when BRIG_ROOTFS_MODE=overlay-block asks for an overlay the host cannot build, or when BRIG_ROOTFS_MODE is not a mode.

A bundle line appears when brig runs from the bin directory of the runtime bundle without its launcher. See Troubleshooting.

Linux host checks. On Linux with nerdctl, or with no runtime yet, doctor adds what a run needs from the host:

Line Who gets it What it checks
subids, userns, uidmap a user other than root what a rootless run needs. Where AppArmor restricts user namespaces, as on Ubuntu 24.04 and later, userns looks for a loaded profile that allows a rootless run
devices every user /dev/vhost-vsock
cni every user the CNI plugins
tools a nerdctl from outside the runtime bundle, or no runtime found the hypervisor a run boots on, and oras when the boot assets are missing

For a user other than root, devices and virtual read !! when the user reaches the device only through the kvm group. A rootless run drops that group. The device has to be this user's, carry an ACL entry for this user, or be open to everyone.

For a nerdctl from outside the bundle, the runtime line ends with (not the runtime bundle; see install.sh). Doctor cannot tell whether that runtime boots a sandbox.

These host lines do not change the exit status.

Two checks set a nonzero exit status: a missing or broken runtime exits 4, and a secret store that does not open exits 6. Every other finding, including one marked !!, prints its fix and exits 0.

brig version #

Prints the version and the build it came from.

brig version [--json]
brig --version
Flag Meaning
--json print the same build under the envelope, with the commit in full

--version is the same command. The parentheses hold the build: the short commit, the commit date, the Go version and the platform.

$ brig version
brig v0.2.0 (131e3bc, 2026-09-15, go1.26.0, darwin/arm64)

The version comes from the nearest tag.

Build Version printed
a release its tag
a commit after a tag a pseudo-version naming that commit, such as v0.2.1-0.20260915210404-ef4aa8b0efb6
a tree with uncommitted changes the same, with +dirty appended
no git history, such as a source tarball dev and no commit
brig version --json
{
  "apiVersion": "brig.sh/v1alpha1",
  "kind": "Version",
  "data": {
    "version": "v0.2.0",
    "commit": "131e3bc5615df5ff74e6b5af9a5bcf2ed42b1d57",
    "commitTime": "2026-09-15T09:36:19Z",
    "modified": false,
    "goVersion": "go1.26.0",
    "os": "darwin",
    "arch": "arm64"
  }
}

If the build had no git history, commit and commitTime are absent.

brig completion #

Prints a completion script for bash, zsh or fish to stdout.

brig completion <shell>

The command installs nothing. See Completions for where each shell reads its script, and what completes where.

brig completion zsh > "${fpath[1]}/_brig"

brig agent #

Lists, creates, edits and removes the agents you can run.

brig agent ls
brig agent show <agent>
brig agent new <name> --from <agent> [--force]
brig agent edit <name>
brig agent rm <name>
brig agent import <file>
brig agent export <agent> [name] [--force]
Subcommand What it does
ls lists the agents you can run
show prints an agent, to read it or pipe it
new copies an agent under a name you choose
edit edits your copy
rm deletes a file-backed agent, after asking
import adds a file you wrote or received
export saves a copy of an agent you did not create, under a name you choose
Flag Meaning
--from <agent> with new, the agent to copy
-f, --force with new or export, overwrite a destination file that already exists. Without it, Brig refuses and names the file
--json with show, new or export, print the document as JSON instead of YAML, with no envelope. See JSON output

To change a built-in agent, copy it under a new name and edit the copy. A built-in agent has no file until new creates one.

brig agent new mine --from claude
brig agent edit mine

export gives the same result as new --from.

brig agent show claude
brig agent export claude mine
brig agent import mine.yaml
brig agent rm mine

rm refuses while a sandbox of the agent exists, running or stopped. For each one, it names the brig rm <ref> to run first. It also refuses when Brig cannot reach the agent's runtime, for example with an unknown BRIG_RUNTIME.

See Profiles for the file format.

brig policy #

Manages policies and what binds them.

brig policy ls
brig policy create <name> [--force]
brig policy edit <name> [--force]
brig policy show <name> [--json]
brig policy show --preset <preset> [--json]
brig policy rm <name> [--force]
brig policy attach <policy> <agent> [-n <label>]
brig policy detach <policy> <agent> [-n <label>]
brig policy check <agent> [-n <label>]
Flag Meaning
-n <label> names one session of the agent. With attach, it binds the policy to that session instead of every run

List every policy, and what binds it:

brig policy ls

Write a starter policy, then open it:

brig policy create locked-down

Bind it to every run of an agent:

brig policy attach locked-down claude

Bind it to one session instead of every run:

brig policy attach locked-down claude -n refactor

Check what is bound to a run, and whether Brig can enforce it:

brig policy check claude

See Policies for the document format and what each network posture means.

brig secret #

Stores and manages secrets in your keyring.

brig secret create <name> [-f FILE] [--type tls|ca]
brig secret update <name> [-f FILE] [--type tls|ca]
brig secret read <name>
brig secret delete <name> [-y]
brig secret ls
brig secret import <agent>
brig secret import <agent> <name>

Read the value from stdin and store it under that name in your keyring:

brig secret create gh-token

--type tls checks the value as a client certificate with its key, and --type ca as a bundle of CA certificates. See Secrets.

Fill every secret that the profile of an agent declares, from your host:

brig secret import claude

Fill one of them:

brig secret import claude gh-token

The value is never a command-line argument, so it does not appear in ps or in your shell history. See Secrets for the store, provenance and the sources a profile can declare.

brig telemetry #

Reports or changes whether usage data is sent.

brig telemetry [status]
brig telemetry on
brig telemetry off
Subcommand What it does
status reports whether usage data is sent, what decided the answer, and the install identifier the events of this machine carry. This is the default with no subcommand
on turns it on on this machine and records the answer
off turns it off on this machine and records the answer
brig telemetry status
brig telemetry off

See Telemetry for what is counted and what is never collected.

Refs #

A ref is <agent> or <agent>@<label>. An empty label is the default session of the agent. claude and claude@refactor are two sessions of one agent. See Sessions for what a session keeps separate, and what survives which command.

The separator is one @. Brig does not rewrite a ref. It refuses these:

Written Refused because
claude@@x more than one @
@refactor no agent named before the @
claude@ a trailing @ names no session. Drop it for the default session, or name one
claude@Refactor the label has a character that Brig must change. Labels use lowercase letters, digits, dot, dash and underscore

Run line #

brig run <ref> [project] [args...] has three kinds of token. Brig tells them apart by position.

  1. The first bare word is the ref.
  2. On run and plan, the second bare word is a project directory. Brig mounts it read-write at /work/<basename> and starts the agent there. Every process you start in that sandbox, brig sh included, gets BRIG_PROJECT set to that path. Without a project the variable is unset. plan shows that run and does not start it.
  3. The next bare word, or anything after --, is an argument for the agent.

The second bare word is the project even when it names no existing directory. Brig then refuses the run and tells you to put the word after --.

-- ends the parsing that Brig does. Brig reads no word after -- as a project. A project read before -- stays.

brig run claude ~/code/demo -- --version

Flag placement #

Put Brig's flags before the ref. There Brig refuses a flag it does not know, so a mistyped flag never reaches the agent. The examples on these pages use that form.

Brig also reads its own flags after the ref and after the project, up to the first argument for the agent. These two lines do the same:

brig run --mem 4096 -d claude ~/code/demo
brig run claude ~/code/demo --mem 4096 -d

Brig flags have two positions. Global flags stand left of the verb. Run-line flags stand between the verb and the first argument for the agent.

Position Flags
Global --verbose, -q/--quiet, --json
Run-line --image, --home, --mem, --cpus, --no-project, -d/--detach, --skills, --network, --offline, --publish and --json

Global position #

Brig refuses by name a token in the global position that is not one of the three global flags. It does not forward the token to an agent.

brig: unknown flag "--nope" before the command. brig takes a command first:
`brig run claude`, `brig ls`. If "--nope" is the agent's, it goes after the
profile

Flags in both positions #

Brig accepts --json in both positions. -q/--quiet works only before the verb. Between the verb and the ref Brig refuses it, and after the ref it is the agent's. See Migration.

brig info claude --json
brig --json info claude

Both lines print the same report.

Flags around the ref #

Brig refuses by name an unrecognized flag before the ref. A help flag there is a help request, not a mistake. See Help.

brig: unknown flag "--nope" before the profile name. brig's own flags come
before the profile and the agent's after it; put "--nope" after the profile
to pass it through, or -- to end brig's flags

The same flag after the ref goes to the agent unchanged.

After the arguments for the agent begin, Brig takes none of its flags. If one of them stands there, Brig warns about it and passes it to the agent.

brig run claude -p hi --quiet

This line runs the agent with -p hi --quiet, and Brig warns about --quiet.

Run-line flags #

Flag Value Default Notes
--image IMAGE image ref the agent's own guest image to boot
--home PATH host directory ~/.brig/homes/<sandbox> mounted as the agent's home. The environment variable is BRIG_WORKSPACE. There is no BRIG_HOME
--mem MB number the agent's own (4096 for most shipped agents) guest memory
--cpus N number the agent's own (4 for most shipped agents) guest vCPUs
--no-project (none) off mount no project this run, even one this session ran with before. On any verb but run and plan, refused by name as a usage error
-d, --detach (none) off start the sandbox, print its name and exit, without attaching. Only run acts on it. sh, stop, rm, info and plan accept it and ignore it
--skills (none) off copy your own ~/.claude skills and plugins into the guest home. The host copy is never written. Same as BRIG_SKILLS=1
--network MODE shared, isolated or offline see Network posture the sandbox's network posture. See Policies
--offline (none) off shorthand for --network offline: the agent runs with its guest home, and nothing leaves the sandbox. Refused together with a different --network value
--publish PORT 3000, 8080:80, 127.0.0.1:8080:80, 5353:53/udp nothing published open a guest port on the host. Repeatable. Binds to 127.0.0.1 unless the address says otherwise. There is no -p: that is the agent's. See brig network

A flag beats an environment variable, and an environment variable beats the profile field. This holds for every value above with a counterpart in Environment variables.

--mem and --cpus take a positive whole number. Brig refuses anything else, including 0.

Network posture #

A sandbox keeps its posture, so a verb without the flag does not change it. Brig uses the first of these that applies:

  1. --network or --offline
  2. BRIG_NETWORK
  3. the posture of the existing sandbox, recorded or inspected from the runtime
  4. the profile's network: field
  5. isolated

An egress policy or a route bound to the sandbox forces isolated, whatever --network asks for. An offline run stays offline under a policy. Brig refuses a route on an offline run. See Policies.

The vz and qemu backends, and sandboxes with no known posture

On vz or qemu, the last step falls back to shared instead of isolated. The fallback applies only when no posture is named, and brig info reports it.

If Brig cannot establish the posture of an existing sandbox, pass --network to choose one.

JSON output #

More verbs accept --json than the summary line of brig --help lists. Acceptance also depends on the position of the flag.

Verb Where --json is accepted Shape
ls global, or local after ls envelope
info global, or local on the run line envelope
plan global, or local on the run line envelope, kind: Plan
doctor global, or local after doctor envelope
version global, or local after version envelope
network ls, network publish, network unpublish global, or local after the ref envelope, kind: Ports
run, sh global, or local on the run line one compact line, see Run output
agent ls global, or local after ls envelope
secret ls global, or local after ls envelope
agent show, agent export, agent new local only, after the subcommand bare document, no envelope
policy show local only, after the subcommand bare document, no envelope

"Global" means left of the verb: brig --json ls.

"Local" means after the subcommand, on either side of its operand. brig agent show claude --json and brig agent show --json claude both work.

Every verb that is not in the table refuses --json in both positions, and names the verbs that accept it.

Global position limits #

Group Global --json
agent accepted only when the subverb is ls
policy never accepted, on any subverb

The global position therefore refuses agent show and policy show:

$ brig --json agent show claude
brig: `brig agent` has no --json output. --json is for the read verbs: ls,
info, plan, agent ls, secret ls, doctor, version and the network verbs, and
for run and sh

Envelope shape #

A list or report verb prints this shape:

{"apiVersion": "brig.sh/v1alpha1", "kind": "...", "data": ...}

Within one apiVersion, Brig only adds fields. It does not rename or remove a field. No field carries a credential value. Fields carry names only.

Bare shape #

agent show, agent export, agent new and policy show print the document with no envelope. You can save each document as a file that Brig reads back.

brig agent show codex --json
{
  "name": "codex",
  "desc": "Codex (OpenAI)",
  "binary": "codex",
  ...
}

Ports output #

Each of the three network verbs prints what the sandbox publishes after the command, as kind: Ports.

{
  "apiVersion": "brig.sh/v1alpha1",
  "kind": "Ports",
  "data": {
    "sandbox": "brig-codex",
    "ports": [
      {"host": "127.0.0.1:8080", "guest": 80, "protocol": "tcp", "live": true}
    ]
  }
}
live Meaning
true the gateway forwards the port now
false the port is recorded but not live. Its sandbox is not running, and Brig publishes the port again when that sandbox starts
null Brig cannot tell. STATE reads unknown

On Linux a port always reports unknown.

Run output #

Under --json, after the agent exits, run and sh print the outcome as one compact JSON line. It is the last line of stdout.

{"apiVersion":"brig.sh/v1alpha1","kind":"Run","data":{"ref":"codex","sandbox":"brig-codex","stage":"agent","exit":0}}
data.stage Meaning data.exit
"brig" a refusal before the agent ran a Brig exit code
"agent" an agent that ran the exit status of the agent
"gui" a windowed agent a Brig exit code
"detached" a run under -d a Brig exit code

See Exit codes for how a script must read the status.

Exit codes #

Code Meaning
0 success
1 a general failure
2 a usage error: an unknown flag, a stray argument, or a value in the wrong place, as the parser of the verb reports it
3 no such thing: an unknown agent, or a sandbox that is not there
4 no usable runtime: none installed, an unknown BRIG_RUNTIME, or BRIG_RUNTIME_BIN (or the runtimeBin of a profile) that points at nothing. The refusal names the setting that caused it
5 a boot refused over image verification
6 a required secret was not resolved, or the secret store did not open
7 the runtime and backend cannot enforce a property bound to the sandbox, or cannot confirm they do. The refusal names the property, the runtime and the backend. See Exit 7

Stability calls this table stable enough to script against.

Exit 7 #

An egress policy is one such property. brig run and brig sh, and the retired spelling of brig sh, refuse a policy with 7:

  • on vz or qemu
  • on docker
  • on hvi, when the runtime is too old to enforce it or Brig cannot check
  • on Linux, when Brig cannot check that the host enforces it
  • on a macOS backend that Brig does not know

The code is 7 whether a flag, BRIG_NETWORK or the network: field of the profile chose the posture.

A route is also refused with 7 where the run cannot serve it: on vz or qemu, on docker, with no network, and on an hvi runtime too old to serve routes. A route in a mode that this build of Brig does not serve is refused the same way. See Credential broker.

brig network publish refuses with 7 on vz, qemu, docker and a macOS backend that Brig does not know. On hvi it records the port, and the next run refuses with 7 if Brig cannot check the gateway.

A refusal that Brig reaches first keeps its own code. With no policy bound, an isolated network on vz or qemu exits 1. A graphical profile on a backend with no window exits 1, under a policy or not.

Optional secrets #

Exit 6 is for required secrets only. A declared secret marked required: false prints a warning, and the command still exits 0. Both secrets of claude are optional, so brig info claude with neither one set exits 0.

Agent exit status #

Under run --json and sh --json, two rules differ.

The exit status of the agent becomes the exit status of Brig. Brig reads that status ahead of every class in the table. An exit 3 from brig --json run claude can come from the agent and not mean "no such agent".

Branch on the data.stage field of the Run object, not on the number alone. If the stage is "agent", the code is from the agent. Any other stage means the code is one of the classes in the table.

When Brig refuses under --json, it prints the Run object on stdout, as on success, and the usual error line on stderr.

Usage errors that exit 1 #

These usage mistakes currently exit 1 instead of 2:

  • an unknown top-level command
  • a run-line verb given no ref
  • a missing subcommand on agent, policy or secret
  • secret import or policy check given no agent
$ brig nosuchverb
brig: unknown command "nosuchverb" (try `brig help`)
$ brig run
brig: run needs a profile, for example `brig run claude`. `brig agent ls`
lists them

Both exit 1. The same kind of mistake on brig ls extra or brig completion bogus exits 2. A script that looks for a usage mistake must test for a nonzero status, not for 2.

A bare brig telemetry exits 0, because telemetry defaults to status.

Environment variables #

Brig reads most settings from BRIG_<KEY> and from BRIG_<AGENT>_<KEY>. If both are set, the agent-specific form wins.

In the agent-specific form, <AGENT> is the name: of the profile in upper case, with each dash replaced by an underscore. codex reads BRIG_CODEX_MEM ahead of BRIG_MEM. For claude, the form is BRIG_CLAUDE_CODE_MEM.

A setting marked "global only" has no per-agent form. Brig reads it once for the invocation, not per run.

Sandbox and profile locations #

Variable Default Meaning
BRIG_WORKSPACE ~/.brig/homes/<sandbox> host directory mounted as the guest home. A named session appends -<slug> to one you set. Brig deletes the default one on brig rm, and never deletes one you set
BRIG_NAME brig-<agent> the name of the sandbox. Must begin with brig-, or brig ls and brig rm --all cannot find it. A named session appends -<slug>
BRIG_PROFILE_DIR (global only) $XDG_CONFIG_HOME/brig where your agent files live. Brig refuses to start while BRIG_TEMPLATE_DIR, removed in v0.5.0, is set and this is not
BRIG_POLICY_DIR (global only) $XDG_CONFIG_HOME/brig/policies where policy files live
BRIG_STATE_DIR (global only) ~/.brig where Brig keeps state that outlives one command, including the project each sandbox last ran with

Guest resources and network #

Variable Default Meaning
BRIG_IMAGE the agent's own guest image to boot
BRIG_PULL missing missing pulls only when the image is not already on the host. always re-pulls every run. never refuses to boot an image that is not already there
BRIG_MEM the agent's own guest memory, MB
BRIG_CPUS the agent's own guest vCPUs
BRIG_READY_TIMEOUT 30 seconds to wait for the in-guest agent after the runtime reports the sandbox running
BRIG_NETWORK see Network posture shared, isolated or offline. Beats the retained posture of an existing sandbox. An unrecognized value refuses the run. See Policies
BRIG_SKILLS 0 1 copies your ~/.claude skills and plugins into the guest home. Same as --skills
BRIG_FORWARD_ENV (unset) a space-separated list of environment variable names to carry into the guest, read live on every run
BRIG_TITLE the agent's own window title for a graphical agent

BRIG_FORWARD_ENV interacts with the env: bindings of a profile. The profile binding wins.

Profile binding Effect of BRIG_FORWARD_ENV
the singular ref: env.<name> form replaced
a refs: chain, even one that includes an env. entry left untouched
a name bound from secrets. or a literal value: the name is dropped from the override, and Brig warns about each one it drops

Credentials and Git #

Variable Default Meaning
BRIG_ALLOW_REFS 0 1 forwards a value that still looks like an unresolved scheme:// secret reference
BRIG_ALLOW_DENIED 0 1 forwards a variable on the billing denylist of the agent
BRIG_GIT_CONFIG 0 1 writes a credential helper and gitconfig into the guest, routing an SSH GitHub remote over HTTPS
BRIG_GIT_HOSTS github.com space-separated hosts the forwarded token applies to
BRIG_GIT_USER resolved on the host username paired with the forwarded token
BRIG_GIT_IDENTITY 1 0 stops Brig from forwarding the host commit identity resolved from the invoking directory
BRIG_GIT_NAME, BRIG_GIT_EMAIL the host's git config override that identity
BRIG_TRUST_WORKSPACE 1 pre-answers the "do you trust this folder" question of the agent for the directory a run starts in
BRIG_ENV_ARGV (global only) (unset) only the value 1 puts a forwarded value on the command line of the runtime, where ps can read it. Never applies to a value that Brig resolved, such as a stored secret. Those values always stay off the command line

See Authentication and Secrets for what each variable does with the credential in the guest.

Image verification #

Variable Default Meaning
BRIG_VERIFY warn warn, require or off. strict is an alias for require, and none and 0 both alias off. An unrecognized value refuses the run. It does not fall back to warn
BRIG_VERIFY_REGISTRY ghcr.io/brig-sh/ image prefix that Brig treats as a Brig image, so it expects a signature
BRIG_VERIFY_IDENTITY the Brig community-images build workflow certificate identity regexp cosign must match
BRIG_VERIFY_ISSUER GitHub Actions OIDC certificate OIDC issuer
BRIG_VERIFY_RUNTIME_IDENTITY the Linux runtime bundle's release workflow, on a tag certificate identity regexp the runtime bundle's signed record must match. Set it for a bundle released from a fork, as INSTALL_BRIG_SIG_IDENTITY is set for its installer
BRIG_VERIFY_RUNTIME_ISSUER GitHub Actions OIDC certificate OIDC issuer for that record
BRIG_COSIGN_BIN cosign on PATH path to the cosign binary
BRIG_VERIFY mode Behaviour
warn reports an image that has no signature Brig can check, and boots it. It stops to ask about an image under ghcr.io/brig-sh/ that fails the check or cannot be checked. It refuses boot assets whose signature fails
require refuses to boot anything it cannot positively verify, including when cosign is missing

See Security for what verification does and does not catch.

Runtime and hypervisor #

Variable Default Meaning
BRIG_RUNTIME (global only) hull on macOS, nerdctl on Linux which runtime to drive
BRIG_RUNTIME_BIN (global only) the binary of that runtime, found on PATH. See Runtime discovery path to that binary. BRIG_RUNTIME picks the runtime first, and this only overrides its executable
BRIG_HYPERVISOR the hypervisor: field of the agent, else vz on macOS and hvi on Linux vz, hvi or qemu on macOS. On Linux, for a genericBoot profile: hvi, cloud-hypervisor, qemu or firecracker, with vz and an empty value meaning hvi. Wins over the field of the agent when set
BRIG_ROOTFS_MODE unset: overlay-block where the host can build it, else the runtime's own root the root of a genericBoot profile whose rootfsType is unset or virtiofs. See Guest root modes
BRIG_ROOTFS_TYPE the rootfsType: field of the agent block, virtiofs or 9pfs, how the guest root reaches the microVM on macOS. block and 9pfs keep the runtime's own root, and unset or virtiofs takes the overlay root where BRIG_ROOTFS_MODE allows it. Brig refuses a profile's rootfsType: outside that set, but does not check this variable
BRIG_CONTAINERD_RUNTIME (global only) io.containerd.urunc.v2 Linux only: the containerd shim that boots the sandbox as a microVM. Another microVM shim is accepted. A shim that Brig knows shares the host kernel, such as runc, crun, containerd-shim-runc-v2 or io.containerd.runc.v2, is refused, by name or by path. The ISOLATION row names the variable when it is set

hvi is the only backend that enforces an attached egress policy or --network isolated. It needs macOS 15 or newer.

vz is the only backend with a graphical console.

Linux supports the isolated posture, and enforces egress policies with nerdctl. Brig refuses a policy on docker.

See Runtimes.

Guest root modes #

overlay-block boots the image of a genericBoot profile read-only, with a sparse 16 GiB writable disk per sandbox.

BRIG_ROOTFS_MODE Result
unset overlay-block where the host can build it. Elsewhere Brig keeps the runtime's own root, without a message
overlay-block a host that cannot build it refuses the run and says why
virtiofs keeps the runtime's own root
any other value refused

Brig also refuses overlay-block on another profile, or next to a block or 9pfs rootfs type.

Host What the overlay needs
macOS (vz and hvi) brew install e2fsprogs
Linux (hvi, cloud-hypervisor and qemu) the overlayfs snapshotter and mke2fs

The ISOLATION row names the root that boots, and brig doctor says whether the overlay is available. See Runtimes.

Boot assets and gateway #

Variable Default Meaning
BRIG_BOOT_ASSETS (global only) on macOS, hull's assets directory, usually ~/.hull/assets. On Linux, $XDG_DATA_HOME/brig/assets (~/.local/share/brig/assets when that is unset) directory holding the host kernel and initrd a genericBoot agent needs
BRIG_BOOT_ASSETS_REF (global only) ghcr.io/nofireai/hull-assets:<os>-<arch> the bundle Brig fetches when the boot assets are missing
BRIG_GATEWAY_SOCK (global only) <gateway dir>/gateway-<subnet>.sock control socket of the shared network gateway. Names matching sandbox-*.sock are reserved for isolated gateways and refused here
BRIG_GATEWAY_DIR (global only) the directory of BRIG_GATEWAY_SOCK, else ~/.brig where gateway sockets, logs and network records live, shared and per-sandbox alike
BRIG_BROKER_BIN (global only) brig-broker beside brig, else on PATH the credential broker that a run with a route starts. See Credential broker

Type a command, a flag or an error message.