brig docs

Concepts

Sessions

On this page

A ref names a session. A session has a sandbox, a guest home and, optionally, a project.

Run a second session of the same agent, next to the default one:

brig run claude@refactor ~/code/demo
brig ls                    # lists claude-code and claude-code@refactor
brig rm claude@refactor    # removes that session only

Keep the guest home of a session after brig rm, by naming it:

brig run --home ~/brig-homes/claude claude ~/code/demo

Brig creates the directory if it is missing, and never deletes it.

Refs #

Every ref is <agent> or <agent>@<label>. An empty label means the agent's default session. claude and claude@refactor are two independent sessions of one agent.

Aliases #

Alias Agent
claude claude-code
desktop claude-desktop
herd herdr, its name in v0.5.0 and v0.5.1. See Migration

A profile of your own takes precedence over an alias. If you have a profile named claude, that name runs your profile, and the built-in is reachable as claude-code.

Labels #

For every agent, a label selects the guest home and the sandbox name.

Brig also passes the label to the agent as a display name in one case only:

Case Label passed to the agent
claude on brig run Yes
claude on brig sh No
Any other profile, including claude-desktop No

Guest home #

What a sandbox mounts Two host directories reach the sandbox: the project you name, mounted read-write at /work/demo, and the guest home, mounted as the agent’s home. Other projects, your documents, your keychain and your SSH agent do not. Your machine Sandbox microVM, own kernel ~/code/demo the project you name ~/.brig/homes/<sandbox> guest home ~/code/other-project ~/Documents Keychain SSH agent /work/demo read-write /root the agent’s home: settings and history claude starts in /work/demo Nothing else from your machine is mounted.
A session mounts its guest home and, when you name one, a project.

The guest home is a host directory mounted as the agent's home. By default, Brig creates one under its state directory:

~/.brig/homes/<sandbox name>

The sandbox name is brig-<agent>[-<label>].

Ref Guest home
codex ~/.brig/homes/brig-codex
codex@refactor ~/.brig/homes/brig-codex-refactor

brig ls and brig info print the guest home as WORKSPACE. The BRIG_WORKSPACE environment variable also names it.

Default home lifetime #

A guest home that Brig created survives brig stop and a host reboot. brig rm deletes it.

After brig rm, the next brig run of the same session starts from an empty home. The first run of such a session reports this on stderr.

Your own home #

To keep the guest home, name it with --home <dir> or BRIG_WORKSPACE. Brig creates the directory if it is missing, and never deletes it. A session with a label appends it: --home ~/brig-homes/claude on claude@refactor uses ~/brig-homes/claude-refactor.

Leftover homes and homes from older releases

A failed first boot. A first run whose boot fails deletes the home it created. It does so once the runtime confirms that no sandbox of that name exists.

A home left behind. A sandbox removed outside Brig can leave a home behind. So can a run killed before its sandbox booted. Brig deletes the home before the next run of that session boots. It does so once the runtime confirms that the sandbox does not exist, stopped or running. Brig reports this on stderr.

Sessions created before 0.3.0. Releases before 0.3.0 created the default guest home in ~/brig/<resolved agent name>[-<label>], and kept it on brig rm. A session started by one of those releases keeps that home while its sandbox exists. After you remove the sandbox, pass --home ~/brig/<resolved agent name> to go on using that home.

Project #

Name a directory on the run line:

brig run claude ~/code/demo

Brig mounts ~/code/demo read-write at /work/demo, and the agent starts there.

Run line What Brig mounts
A project directory That directory, read-write, under /work
No project Whatever this session last ran with, read back from its session index
--no-project Nothing

Brig refuses --no-project with a project named on the same line. Only run and plan accept it.

Project changes #

A change of project recreates the sandbox. Brig warns you, stops and removes the sandbox, and starts a new one with the new mount.

Three changes trigger the recreate:

  • You run the session against a different project than it last used.
  • You name a project for the first time on a session that had none.
  • --no-project drops a project the session had.

Warning The recreate removes everything inside the old guest, including a claude login on the memory-backed mount.

Missing projects #

If a remembered project is no longer on disk, the run proceeds with no project. The restart warning names the missing directory.

What survives #

Four things can hold state for a session. The guest home is on host disk. The memory-backed mount is inside the guest.

Event Guest home Memory-backed mount The sandbox What Brig recorded
The agent exits kept kept, the sandbox is still up still running unchanged
brig stop kept gone with the sandbox stopped, still named in brig ls kept
brig rm deleted if Brig created it, kept if you named it gone removed dropped
brig rm --all as brig rm, every session gone every sandbox removed dropped, every session
A host reboot kept, an ordinary host directory gone, guest memory cannot survive a reboot depends on the runtime kept as host files

Neither brig stop nor brig rm touches a project or a guest home you named.

In-guest logins #

Agents Where an in-guest login lands When it goes
claude-code, herdr A memory-backed mount inside the guest With the sandbox: on brig stop, brig rm, a recreate, or a host reboot
claude-desktop, codex, cursor, gemini, grok, opencode, ubuntu The guest home, on host disk On brig rm, when Brig created the guest home. It survives every stop.

Host reboots #

The runtime decides whether the sandbox is still listed after a host reboot. If the sandbox is gone, the next brig ls forgets it, and the next run boots a new one.

State directory #

Brig keeps its state under ~/.brig, including the session index. That layout is not a stable interface: see Stability. Do not write a script against its files.

Label rules #

Brig turns a label into a slug in four steps:

  1. Lowercase the label.
  2. Replace every character outside [A-Za-z0-9._-] with a dash.
  3. Collapse runs of dashes.
  4. Trim leading and trailing dots and dashes.

Brig does not shorten the slug.

In the <agent>@<label> form, Brig refuses each of these:

  • A label that is not already its own slug. Brig names the slug it maps to, and does not rewrite the label.
  • More than one @
  • A ref that names no agent
  • A trailing @ with no label
  • A label with no usable characters
  • An agent and a label that join, with a dash, into the name of a profile marked reserved: true, such as claude-desktop

Printed refs #

Two commands print the same session with two different strings. A script that reads both must expect that.

Command What it prints
brig ls The profile name of the agent plus the label, which can differ from the ref you typed
run --json (the Run object) The ref as typed. brig --json run claude reports "ref": "claude"

Type a command, a flag or an error message.