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 runbrig 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/demoIf you name no project, Brig remounts the project that this session used last:
brig run claudeStart a second session of the same agent, with a separate sandbox and guest home:
brig run claude@refactor ~/code/demoStart the sandbox detached:
brig run -d claude ~/code/demoRun with no project mounted, even one that this session ran with before:
brig run --no-project claudePass an argument to the agent after --:
brig run claude ~/code/demo -- --versionbrig 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 /workEach 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 claudebrig 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-runWhat 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 -qbrig 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 claudeinfo 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 --jsonWith 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 --jsonThe 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 mineexport gives the same result as new --from.
brig agent show claude
brig agent export claude mine
brig agent import mine.yaml
brig agent rm minerm 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 lsWrite a starter policy, then open it:
brig policy create locked-downBind it to every run of an agent:
brig policy attach locked-down claudeBind it to one session instead of every run:
brig policy attach locked-down claude -n refactorCheck what is bound to a run, and whether Brig can enforce it:
brig policy check claudeSee 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 claudeFill one of them:
brig secret import claude gh-tokenThe 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 offSee 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.
- The first bare word is the ref.
- On
runandplan, 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 shincluded, getsBRIG_PROJECTset to that path. Without a project the variable is unset.planshows that run and does not start it. - 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 -- --versionFlag 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 -dBrig 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
profileFlags 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 claudeBoth 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 flagsThe 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 --quietThis 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:
--networkor--offlineBRIG_NETWORK- the posture of the existing sandbox, recorded or inspected from the runtime
- the profile's
network:field 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 shEnvelope 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
vzorqemu - 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,policyorsecret secret importorpolicy checkgiven 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 themBoth 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 |