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 runline changed meaning, and Brig prints no notice. See Project argument.brig shpasses 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 outputWhen 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 agentBefore 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 agentThe 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 scriptA 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 lsprints-for its ref, and onlybrig rm --allremoves it. Runbrig rm herd@<label>for each one before you upgrade, orbrig rm --allafter. - A policy attached to
herd. The attachment does not apply toherdrruns. Attach the policy again. - A profile made with
--from herd. It keepsimage: ghcr.io/brig-sh/herd-stock:latest, which no longer updates. Edit it toherdr-stock. - An ssh block for
Host herd*+*. It still matchesherdr+<label>, but itsProxyCommandnamesherd-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 # refusedbrig 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_TOKENstatePaths: 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 isolatedThe 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: sharedin 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 sharedSessions 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.comis 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.combrig 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.