Reference

Migration

Every retired Brig spelling and its replacement. A script written for an older spelling needs no change other than these.

Deprecation window #

Every old spelling works today, except the ones under Removed. Each prints a notice on stderr that names the replacement and the removal release:

brig: `brig profiles` is now `brig agent ls`
  ↳ the old spelling is removed in v0.4.0

Stability has the rule.

To find old spellings in a script, run script/check-retired-spellings.sh over your files, or watch stderr for the notice.

Warning Two changes are more than a new spelling. A word on the brig run line changed meaning, and Brig prints no notice. See Project argument. New sandboxes also use a different network default. See Network defaults.

Verbs #

brig reset. brig rm --all asks for confirmation. A script that ran brig reset unattended needs brig rm --all -y. Without a terminal, brig reset also refuses unless you pass -y.

brig exec. 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.

brig template. There is no brig template edit. The retired group keeps only the verbs it had. brig template edit is an error and prints no deprecation notice.

Removed #

These spellings do not run. Brig refuses each as a usage error, exit code 2, and names its replacement:

brig: `brig shell` was removed; use `brig sh <ref> [command...]`

Subverbs #

Flags #

Each retired flag writes the same value as its replacement. The inline form (-t=myimage:1) warns too.

Brig does not warn about a value that looks like a retired flag. brig run claude --name -t warns about --name and not about -t.

--memory is a current spelling of --mem and is not retired. 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:

brig -q run claude      # current
brig run claude -q      # still works, prints a notice

The notice names the move:

brig: `brig <verb> <ref> -q` is now `brig -q <verb> <ref>`
  ↳ the old spelling is removed in v0.4.0

--json is accepted on both sides of the verb permanently 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:

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.

Session names #

A session is part of the ref. It replaces the --name flag:

brig run claude@refactor          # current
brig run claude --name refactor   # still works, prints a notice

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

--name is also a Claude Code flag. brig run claude -- --name x sends --name x to Claude Code, and Brig does not read it.

Profile keys #

These keys parse in a profile file until v0.4.0. They print no notice at run time.

To see the current spelling, run brig agent edit on an old file. The header comment documents every field.

If a profile declares a retired key beside its replacement, Brig refuses the profile:

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 #

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.

BRIG_HYPERVISOR=vz brig run claude --network shared

Settings #

BRIG_TEMPLATE_DIR works until v0.4.0 and prints no notice. If both are set, BRIG_PROFILE_DIR wins.

Agent and profile #

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

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