brig docs

Reference

Migration

On this page

Every retired Brig spelling, its replacement, and the release that removed it.

Removed spellings #

Brig v0.5.0 removed the retired spellings, with two exceptions:

Spelling Status
brig exec Still works. It stays until brig sh can pipe the output of a command, and its notice says that instead of a release. See The one retired verb left.
The flat form of a policy document Still parses and prints a notice. It is removed in v0.6.0. See Policy documents.

brig run is never removed. Stability has the rule.

Brig refuses a removed command or subcommand as a usage error, with exit code 2. The refusal names the replacement, and nothing runs:

brig: `brig profiles` was removed; use `brig agent ls`

A removed flag is refused the same way before the ref. After the ref, it is the agent's own. A removed profile key fails the profile, and the error names the key that replaced it.

To find removed spellings in a script, run script/check-retired-spellings.sh over it.

Warning Three changes are more than a new spelling. A word on the brig run line changed meaning, and Brig prints no notice. See Project argument. brig sh passes its words to the guest as arguments, so a script typed as one quoted word does not run. See Scripts on brig sh. New sandboxes also use a different network default. See Network defaults.

Verbs #

Removed in Spelling Current
0.3.0 brig shell <ref> brig sh <ref>
0.5.0 brig profiles, brig agents brig agent ls
0.5.0 brig profile <verb> brig agent <verb>
0.5.0 brig template <verb> brig agent <verb>
0.5.0 brig import brig agent import
0.5.0 brig export brig agent export
0.5.0 brig policies brig policy ls
0.5.0 brig create <ref> brig run -d <ref>
0.5.0 brig env <ref> brig info <ref>
0.5.0 brig reset brig rm --all

brig rm --all asks before it removes anything. Without a terminal to answer on, it refuses unless you pass -y. A script that ran brig reset unattended needs brig rm --all -y.

The one retired verb left #

Retired Current
brig exec <ref> -- <cmd> brig sh <ref> <cmd>

brig exec still works, and prints a notice on stderr that names its replacement:

brig: `brig exec` is now `brig sh`
  ↳ the old spelling stays until `brig sh` can pipe a command's output

When stderr is not a terminal, both lines start with brig:.

brig exec runs its command without a guest pty, and brig sh does not yet. Until #335 lands, use brig exec to pipe the output of a command cleanly.

Subverbs #

Removed in Spelling Current
0.5.0 brig agent list brig agent ls
0.5.0 brig agent save brig agent export
0.5.0 brig agent load brig agent import
0.5.0 brig policy list brig policy ls
0.5.0 brig secret list brig secret ls
0.5.0 brig secret rm brig secret delete

Flags #

Removed in Spelling Current
0.5.0 -t IMAGE --image IMAGE
0.5.0 -m MB --mem MB
0.5.0 -n NAME, --name NAME <agent>@<label>
0.5.0 -w PATH, --workspace PATH --home PATH

These letters went back to the agents. -n, -m and -w are flags of Claude Code, Codex, Gemini or opencode. After the ref, each is the agent's own, as is any flag that Brig does not own. brig run claude -w x passes -w x to Claude Code.

Before the ref there is no agent to own the flag. Brig refuses it as a usage error that names its replacement. The inline form (-t=myimage:1) is the same flag:

brig: `-t` was removed; use `--image`

--memory is a current spelling of --mem. The help text does not show it, and completion does not offer it.

Quiet flag position #

-q and --quiet moved to the global position, left of the verb. v0.5.0 removed the run-line spelling:

brig -q run claude      # current
brig run -q claude      # refused
brig run claude -q      # -q goes to the agent

Before the ref, Brig refuses it and names where it went:

brig: `brig <verb> <ref> -q` was removed; use `brig -q <verb> <ref>`

After the ref, it is the agent's, and Brig says that it did not read it:

brig: -q is one of brig's own flags, but here it is the agent's
  ↳ brig stopped reading the line at the argument before it
  → for brig to read it, put -q before the command

--json is accepted on both sides of the verb and prints no notice.

Project argument #

The second bare word on a brig run line is the project directory. Brig mounts it, and the agent starts in it. In older versions, that word went to the agent.

brig run claude ~/code/demo   # mounts ~/code/demo at /work/demo
brig run claude -- src        # passes src to the agent

The old meaning no longer works, and Brig prints no notice. A line written for the old meaning, such as brig run claude src, now does this:

src is What Brig does
a directory mounts it read-write at /work/src and starts the agent there
not a directory refuses the run and tells you to put it after --

At the default verbosity, Brig prints nothing about the mount. brig info claude shows the mounted project without running anything, and brig --verbose run prints it before the boot.

To keep the old meaning, put the word after --. Anything after -- goes to the agent unchanged.

script/check-retired-spellings.sh cannot find these lines, because each line is still valid. Look for brig run lines with a second bare word after the agent.

Scripts on brig sh #

brig sh <ref> <command...> passes each word to the guest as one argument, as brig exec <ref> -- <cmd> does. Older releases joined the words with spaces and ran the result as a script under bash -lc.

A line that passed shell syntax as one quoted word now fails in the guest, and Brig prints a hint that names -c. Put -c in front of the script. -c runs it under the login shell, as the join did:

brig sh claude 'ls /work | wc -l'      # no longer runs
brig sh claude -c 'ls /work | wc -l'   # runs it as a script

A variable assignment in front of the command is shell syntax too. brig sh claude FOO=bar npm test looks for a command named FOO=bar and exits 127. Use env, or write the line as a script:

brig sh claude env FOO=bar npm test
brig sh claude -c 'FOO=bar npm test'

brig run on a kind: shell profile, such as ubuntu, runs its trailing words the same way.

Login profiles that change the command

The words are positional parameters. A login profile that runs a top-level shift or set -- rewrites them, and so rewrites the command. This applies to /etc/profile in the image, and to a .bash_profile in your guest home when the profile mounts that home at the guest user's $HOME. Move the shift or set -- into a function.

Bash stays the parent of the command when the first word is a profile function or the login profile sets a trap. A SIGTERM sent to the session then ends bash and leaves the command running until the sandbox stops.

Profile names #

Renamed in Profile Current
0.5.2 herd herdr

The profile that runs Claude Code with a herdr server takes the tool's name, herdr. So does its image, ghcr.io/brig-sh/herdr-stock. herd stays as an alias. brig run herd starts a herdr sandbox, and brig policy attach <policy> herd attaches to herdr.

These do not carry over:

  • A sandbox made under the old name. Its name on the runtime starts with brig-herd-, which no profile owns any more. brig ls prints - for its ref, and only brig rm --all removes it. Run brig rm herd@<label> for each one before you upgrade, or brig rm --all after.
  • A policy attached to herd. The attachment does not apply to herdr runs. Attach the policy again.
  • A profile made with --from herd. It keeps image: ghcr.io/brig-sh/herd-stock:latest, which no longer updates. Edit it to herdr-stock.
  • An ssh block for Host herd*+*. It still matches herdr+<label>, but its ProxyCommand names herd-sshd, which the new image does not have. herdr has the current block.

Session names #

A session is part of the ref, which replaced the --name flag:

brig run claude@refactor          # current
brig run --name refactor claude   # refused

brig run claude is the agent's default session. claude@refactor is a second session, with a separate sandbox and guest home. See Sessions.

--name is also a Claude Code flag. Since v0.5.0, Brig does not read a --name after the ref. brig run claude --name x sends --name x to Claude Code, as brig run claude -- --name x does.

Profile keys #

v0.5.0 removed shell:, gui:, forward: and statePaths:. Brig refuses a profile that still has one, as it refuses any field that it does not know. The error names the key that replaced it.

Removed in Key Current
0.3.0 hostCredential: declare the credential under secrets: and run brig secret import <agent>
0.5.0 shell:, gui: booleans kind:
0.5.0 forward: env:, with ref: env.<name>
0.5.0 statePaths: volumes:

forward: [GH_TOKEN] becomes this env: entry. It reads the variable from Brig's own environment when it is set:

env:
  - name: GH_TOKEN
    ref: env.GH_TOKEN

statePaths: named what persists and enforced nothing. A profile that drops it persists what it did before. volumes: is the list Brig acts on.

brig agent export claude-code prints a current profile. Its header comment documents every field.

Network defaults #

New sandboxes on hvi and Linux default to isolated. Each has a separate network and still reaches the internet.

This change separates sandbox networks. It adds no egress policy and makes no new claim about access to host services.

Existing sandboxes keep the posture recorded when they started. An upgrade does not restart a sandbox to apply the new profile default. A sandbox that the runtime confirms is absent gets the default for a new sandbox.

Changing a posture #

To change the posture of a sandbox, run:

brig run claude --network isolated

The command restarts the sandbox and disconnects any session that uses it.

If one sandbox must reach another, give both the shared posture in one of these ways:

  • start both with --network shared
  • set BRIG_NETWORK=shared
  • put network: shared in their profiles

Profile postures #

Profile Posture
the seven hvi profiles explicitly isolated
the graphical claude-desktop profile shared, for vz
the unpublished cursor profile unset. It isolates on Linux and hvi, and takes the shared fallback on vz or qemu
any profile without a network choice falls back to shared on vz or qemu, and brig info reports why

An exported profile keeps the network: field that it names. To make a custom profile keep a posture for new sessions, add that field.

Policies covers the precedence, backend exceptions and resource costs.

The vz and qemu backends

Brig refuses an explicit isolated on vz and qemu.

If you override an hvi profile to vz or qemu, also override its explicit isolated posture. For example:

BRIG_HYPERVISOR=vz brig run claude --network shared
Sessions created by older versions

An older session can have no posture record. Brig then reads the posture from the runtime, and a run that reuses the sandbox records it.

When Brig cannot establish the posture, brig info reports it as unknown, and Brig refuses a run that names no posture. Name the posture with --network or BRIG_NETWORK to recreate the sandbox. That disconnects any session that uses it.

Policies describes the other rare cases.

Policy documents #

A policy document uses the Kubernetes envelope: kind: Policy, metadata: and spec:. The flat form, with name:, desc: and egress: at the top level, still parses until v0.6.0. Brig converts it into the envelope as it loads it.

brig policy check prints a notice for each bound policy that a file still writes in the flat form:

brig: /home/you/.config/brig/policies/locked-down.yaml uses the flat policy form, which is now `kind: Policy` with `metadata:` and `spec:`
  ↳ the old spelling is removed in v0.6.0
  → to print it in the new form:  brig policy show locked-down
Flat form Envelope
no kind: kind: Policy
name: metadata.name:
desc: metadata.description:, which is one line. Brig joins the lines of a longer desc: with spaces.
egress: spec.egress:

apiVersion: does not change. For instance, this flat document:

apiVersion: brig.sh/v1alpha1
name: locked-down
desc: only Anthropic's API
egress:
  default: deny
  allow:
    - host: api.anthropic.com

is this envelope:

apiVersion: brig.sh/v1alpha1
kind: Policy
metadata:
  name: locked-down
  description: only Anthropic's API
spec:
  egress:
    default: deny
    allow:
      - host: api.anthropic.com

brig policy show <name> prints any policy in the envelope form. For a policy in the flat form, its output is a valid policy file.

The flat form stays one release longer than the spellings v0.5.0 removed, because v0.5.0 is the first release that prints its notice.

Settings #

Removed in Setting Current
0.2.0 BRIG_CREDENTIALS_CMD declare the credential under secrets:, then run brig secret import <agent> <name> --from-command '<command>'
0.5.0 BRIG_TEMPLATE_DIR BRIG_PROFILE_DIR

Brig refuses to start while BRIG_TEMPLATE_DIR is set and BRIG_PROFILE_DIR is not. It does not read the built-in profiles in place of the directory the old setting named. Set BRIG_PROFILE_DIR to the same directory. When BRIG_PROFILE_DIR is also set, Brig ignores BRIG_TEMPLATE_DIR.

Brig refuses a run that still sets BRIG_CREDENTIALS_CMD.

Agent and profile #

Both words are current, and they name different things. The rename applies to the command surface only.

Word What it names
agent the CLI noun: brig agent ls, brig agent edit, and the <ref> every verb takes
profile the file format, the directory and the environment variable. A profile is a YAML file in $XDG_CONFIG_HOME/brig, and BRIG_PROFILE_DIR points somewhere else

To change an agent, edit its profile file. See Profiles for the file format.

Type a command, a flag or an error message.