brig docs

Concepts

Sessions

On this page

A ref names a session. A session has a sandbox, a guest home and, optionally, a project. For a walkthrough, see Quickstart.

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 #

Brig resolves only two aliases:

Alias Built-in agent
claude claude-code
desktop claude-desktop

An agent name takes precedence over an alias. If you have a profile named claude, claude means that profile. The built-in claude-code is then reachable only by its full name.

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-code on brig run Yes
claude-code 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/brig-claude-code 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-<resolved agent name>[-<label>]. The resolved name is the name of the agent, and not the alias that you typed.

Ref Guest home
claude ~/.brig/homes/brig-claude-code
claude@refactor ~/.brig/homes/brig-claude-code-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 never deletes a guest home that you named. A named session appends -<label> to it.

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. Brig also refuses it on every verb except run.

Project changes #

A mount cannot be attached to a live guest, so a change of project recreates the sandbox. Brig warns you, stops the running sandbox, removes it, 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-code 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 (claude-code, claude-desktop) 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 #

Only two of the eight built-in agents declare a memory-backed mount.

Agents Where an in-guest login lands When it goes
claude-code, claude-desktop A memory-backed mount inside the guest With the sandbox: on brig stop, brig rm, a recreate, or a host reboot
codex, cursor, gemini, grok, opencode, ubuntu Host disk. The whole guest home is the host-backed share. 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
  • A label that names the default session of another agent
The retiring --name flag

The retiring --name flag accepts a name that is not a slug. It converts the name and warns which directory it used. --name "Refactor Sprint" becomes refactor-sprint with a warning.

Printed refs #

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

Command What it prints Example for a session started with the claude alias
brig ls The canonical agent name plus the label claude@refactor shows as claude-code@refactor
run --json (the Run object) The ref as typed brig --json run claude reports "ref": "claude", not "claude-code"

Type a command, a flag or an error message.