Reference

CLI reference

The syntax of every Brig verb and flag, the environment variables, the JSON output and the exit codes. For a first run, see Quickstart. For older spellings and their replacements, see Migration.

Everyday commands #

Verbs #

brig run #

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

brig run <ref> [project] [args...]

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 claude ~/code/demo -d

Run with no project mounted:

brig run claude --no-project

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...]

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

brig sh claude
brig sh claude ls /work

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]

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

If the sandbox is removed but its guest home cannot be deleted, rm exits 1 and names the home. The sandbox stays removed. 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.

rm --all also stops the shared network gateway that hvi sandboxes use, when no sandbox on the host uses it. A sandbox of another session, or one that still boots, keeps the gateway running.

What --dry-run prints

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]

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>]

brig logs claude --follow
brig logs --gateway
brig logs --gateway claude

An isolated sandbox has a separate gateway log. That includes a new default hvi sandbox and a sandbox with a policy.

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 network row shows the posture of the running sandbox. If the posture of the next boot differs, the row shows that too.

brig run -v prints the same envelope before it boots. There the row can name the posture that the same command then restarts the sandbox onto.

brig info claude

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

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

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. brig network ls resolves no credentials, so it works when a declared secret is missing.

Port syntax

Ports use the docker syntax.

The host address defaults to 127.0.0.1. Then 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 says so on the row for that port.

Lifetime of a publication

A publication belongs to the sandbox and outlasts a run.

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

brig doctor #

Checks your installation and prints one line per check.

brig doctor [agent] [--json]

The checks are: the brig build, the host, the hypervisor, the runtime, the boot assets, cosign, the profile directory, the secret store and brigd.

brig doctor
brig doctor claude
brig doctor --json

The first line is the build that brig version prints.

Doctor asks a running brigd for its build. If that build differs from the brig binary, doctor marks it !!, with a restart as the fix. A daemon that stays up across an upgrade serves the old code with no other sign.

If you name an agent, doctor also fills in the image line. If the profile of the agent names a runtimeBin, the runtime and boot lines report on that binary instead of the one on PATH. A run of the agent uses that binary.

Two checks set a nonzero exit status: a missing or broken runtime, and a secret store that does not open. 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

--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)

Go derives the version from the nearest tag at build time.

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]

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-code
brig agent export claude-code 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 ask the runtime of the agent, 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>
brig policy edit <name>
brig policy show <name>
brig policy rm <name>
brig policy attach <policy> <agent> [-n <label>]
brig policy detach <policy> <agent> [-n <label>]
brig policy check <agent> [-n <label>]

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]
brig secret update <name> [-f FILE]
brig secret read <name>
brig secret delete <name>
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

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

brig secret import claude-code

Fill one of them:

brig secret import claude-code 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 off

brig telemetry status
brig telemetry off

See Telemetry for what is counted, what is never collected, and how the answer is stored.

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:

The sandbox name and the guest home directory both use the label, and they must agree on it.

Run line #

brig run <ref> [project] [args...] has three kinds of token. Brig tells them apart by position and count. It does not look at the filesystem.

1. The first bare word is the ref.
2. On run only, the second bare word is a project directory. Brig mounts it read-write at /work/<basename> and starts the agent there.
3. The next bare word, or anything after --, is an argument for the agent.

The project directory must exist. If it does not, Brig reports an error and does not pass the word to the agent.

-- 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

Brig continues to read its flags after the ref and after the project.

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

Flag placement #

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.

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 two flags in both positions.

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.

brig: unknown flag "--help" before the profile name. brig's own flags come
before the profile and the agent's after it; put "--help" 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 #

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 by name, including 0. It does not round or ignore the value.

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

JSON output #

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

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

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

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

env is the deprecated spelling of info. Use info.

Global position limits #

The global position therefore refuses agent show and policy show:

$ brig --json agent show claude-code
brig: `brig agent` has no --json output. --json is for the read verbs: ls,
info, agent ls, secret ls, doctor, version and the network verbs (env takes
it too, but env is deprecated; prefer info), 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 claude-code --json

{
  "name": "claude-code",
  "desc": "Claude Code (Anthropic)",
  "binary": "claude",
  ...
}

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-claude-code",
    "ports": [
      {"host": "127.0.0.1:8080", "guest": 80, "protocol": "tcp", "live": true}
    ]
  }
}

The Linux runtime does not report this. A port that it forwards shows neither open nor pending.

Run output #

Under --json, run and sh run the agent as a child of Brig. After the agent exits, Brig prints one compact JSON line with the outcome. It is the last line of stdout.

{"apiVersion":"brig.sh/v1alpha1","kind":"Run","data":{"ref":"claude","sandbox":"brig-claude-code","stage":"agent","exit":0}}

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

Exit codes #

script/smoke.sh and cmd/brig/exit_test.go test this table end to end. Stability calls it stable enough to script against.

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-code 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.

Brig writes a refusal under --json to stdout as the Run object, as it does for every success. It does not write the refusal to 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, the agent name is in upper case with each dash replaced by an underscore. claude-code reads BRIG_CLAUDE_CODE_MEM ahead of BRIG_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 #

Guest resources and network #

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

Credentials and Git #

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

Image verification #

See Security for what verification does and does not catch.

Runtime and hypervisor #

See Runtimes.

Boot assets and gateway #