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 onlyKeep the guest home of a session after brig rm, by naming it:
brig run --home ~/brig-homes/claude claude ~/code/demoBrig 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 #
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/demoBrig 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-projectdrops a project the session had.
Warning The recreate removes everything inside the old guest, including a
claudelogin 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:
- Lowercase the label.
- Replace every character outside
[A-Za-z0-9._-]with a dash. - Collapse runs of dashes.
- 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 asclaude-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" |