Guides
Agent profiles
On this page
A profile is a YAML file that tells Brig which image to boot, where the guest home is, and which credentials the guest receives.
The command and its <ref> argument say "agent": brig agent ls, brig agent edit. The file format, the profile directory and BRIG_PROFILE_DIR say "profile".
A profile is optional. Brig boots an agent from an OCI image, and any Linux CLI that runs in one works. A profile saves you from typing the image, the guest home and the credential variables on every run.
Create a profile #
Copy the closest built-in profile, change one field, and check the result before you run it. This example gives the ubuntu shell more memory:
brig agent new mine --from ubuntu # writes ~/.config/brig/mine.yaml
brig agent edit mine # change mem: 2048 to mem: 4096
brig plan mine # boots nothingbrig plan prints what a run of mine gets. Its LIMITS row shows the change:
LIMITS 4096 MB, 2 vCPUsThen run it with brig run mine ~/code/demo. To undo, run brig agent rm mine, which deletes the file.
new takes a name, not a path, and writes the file into your profile directory. It sets the name: field, which is how Brig identifies the profile. Everything else, comments included, still describes the profile you copied. A header comment in the file explains every field.
brig agent edit opens the profile's file in $VISUAL, then $EDITOR, then vi. A built-in profile has no file. For a built-in profile, edit prints the commands that create a copy, and it creates nothing.
To import a file that you wrote by hand, use brig agent import:
brig agent import mytool.yamlMinimal profile #
name: mine
image: ghcr.io/brig-sh/codex-stock:root
guestHome: /root
binary: codex
mem: 4096
cpus: 4The default kind: agent requires these six fields. All other fields are optional.
Fields #
| Field | Required | Purpose |
|---|---|---|
name |
yes | Profile name |
image |
yes | Guest image to boot |
guestHome |
yes | Where the guest home is mounted |
kind |
no | agent, shell or gui |
binary |
yes, for kind: agent |
Agent CLI inside the guest |
mem |
yes | Guest memory |
cpus |
yes | Guest CPU count |
desc |
no | One-line description |
secrets |
no | Secrets the profile wants from the store |
env |
no | Variables the guest sees |
files |
no | Credential files the guest sees |
volumes |
no | Mounts inside guestHome |
deny |
no | Variables never bound |
staleCredentialFiles |
no | Old credential paths to warn about |
headless |
no | Agent supports a non-interactive run |
guiTitle |
no | Window title for a kind: gui profile |
network |
no | Network posture |
hypervisor |
no | Backend to boot on |
runtimeBin |
no | Runtime binary to drive |
rootfsType |
no | How the guest root reaches the microVM |
genericBoot |
no | Boot a plain OCI image |
hostConfigDir |
no | Host agent configuration directory |
projectPaths |
no | Subdirectories to seed with --skills |
onboarding |
no | First-run state file to seed |
reserved |
no | Protects a guest home from session names |
unpublished |
no | No published image |
policy |
no | Policies attached inline |
Brig refuses a misspelled field, such as volume: in place of volumes:. It refuses a key that v0.5.0 removed in the same way, and the error names the key that replaced it. See Migration.
name #
The profile name. It becomes the guest home directory and the sandbox name.
name: mineLimits:
- Lowercase letters, digits, dot, dash and underscore only.
image #
The guest image to boot.
image: ghcr.io/brig-sh/codex-stock:rootLimits:
- Brig cannot check the signature of an image outside
ghcr.io/brig-sh. It warns on every boot and still boots. See Security.
guestHome #
The absolute path where the guest home is mounted. The state of the agent lands here, so the guest home is the unit that persists.
guestHome: /rootkind #
Sets what brig run does when the guest is up. Default: agent.
kind: shell| Value | What brig run does |
Trailing arguments |
|---|---|---|
agent |
Execs binary: |
Passed to binary: |
shell |
Opens a login shell | Run as one command, each word one argument to it, or as a script after -c |
gui |
Boots the sandbox with a graphical console | Refused |
brig sh always execs bash -l, or runs the command or script under bash -lc. It never execs binary:.
For kind: gui, brig run starts the sandbox and attaches to nothing. guiTitle names the window.
Limits:
- Brig refuses a
kind: shellorkind: guiprofile that carriespolicy:. - Only the
vzhypervisor backend shows a console. Brig refuses to boot akind: guiprofile onhviorqemu. - v0.5.0 removed the older
shell:andgui:booleans. A profile that still has one fails to parse, and the error nameskind:. See Migration.
binary #
The agent CLI inside the guest, which brig run execs.
binary: claudeLimits:
- For
kind: shell, Brig does not require or read the field.
mem #
Guest memory size.
mem: 4096Limits:
- Must be greater than zero.
cpus #
Guest CPU count.
cpus: 4Limits:
- Must be greater than zero.
desc #
One line that brig agent ls shows.
desc: our internal agentsecrets #
The names of the secrets that this profile wants from Brig's secret store. secrets: is the list of requirements, and env and files are the bindings.
secrets:
- gh_token
env:
- name: GH_TOKEN
ref: secrets.gh_tokenA bare string is the short form of a required secret that you create by hand. secrets: [gh_token] means {name: gh_token, required: true}.
Object form #
secrets:
- name: claude-credentials
required: false # warn and boot, instead of refusing
expiryField: expiresAt # found at any depth; drives the stale warning
sources: # where `brig secret import` looks
- from: keychain
service: Claude Code-credentials
- from: file
path: ~/.claude/.credentials.json
hint: run `claude` on the host once to log in| Key | What it does |
|---|---|
name |
The name of the secret in the store |
required |
Decides whether the run stops. Absent means required. required: false warns and boots |
sources |
Where brig secret import looks. Also decides which command the error names |
field |
How to read the value of the secret from what a source yields. If absent, Brig stores the value verbatim |
expiryField |
How to read the expiry of the secret from what a source yields |
The built-in claude-code profile uses required: false, because the agent can log in inside the sandbox.
field: and expiryField: belong to the secret, not to a source. Every source for one secret must yield the same document shape.
Leave field: out for a secret that is a file.
Sources #
Brig tries the sources in order, and the first that exists wins. One secret can name the macOS keychain and the Linux file, so one profile works on both platforms.
A secret with no sources: is one that you create by hand.
Four from: values exist. keychain, file and env each take one locator and no other. aws takes none.
from: |
Locator | What it reads |
|---|---|---|
keychain |
service: |
A macOS keychain generic-password item. macOS only. The Linux store is a Secret Service keyring, and no source reads from it. See Secrets |
file |
path: |
A host file, verbatim. Brig expands a leading ~ when it reads the file, so a profile holds no home directory of one host |
env |
var: |
A host environment variable, copied once at import |
aws |
none | No file or keychain item. brig secret import checks the AWS profile you name with --aws-profile and stores a pointer to it, for a route on the aws preset. Each machine names its own AWS profile, so a shared profile carries none. See Secrets and Credential broker |
A source with the wrong locator is a parse error, for example a keychain source with a path:.
Warning
from: envandref: env.<name>behave differently. Brig reads aref:on every run. Afrom: envsource copies the value into the store when you runbrig secret import, and never reads it again. For a value that expires, use arefs:chain.
On macOS, import reads the keychain source first. It reads path: ~/.claude/.credentials.json only when the keychain item does not exist. That path is the documented Linux location. On a Linux host with a keyring, import reads that file and stores it in the Secret Service backend.
Limits:
- A credential whose two host locations differ in shape needs two secrets.
- A
files:binding names one secret, and onepath:takes one binding. One portable profile cannot express an agent whose credential file differs per platform. Claude's two locations share a shape.
Missing secrets #
A missing required secret fails the run before Brig creates a sandbox. The error names the secret, the sandbox and the command that creates the secret:
$ brig run mine
brig: missing secret "gh_token" needed by the brig-mine sandbox -- create it first with: brig secret create gh_tokenIf more than one secret is missing, one error names all of them:
brig: missing 2 secrets needed by the brig-mine sandbox:
gh_token: create it first with: brig secret create gh_token
npm_token: create it first with: brig secret create npm_tokenA missing optional secret gives a warning, and the run boots. The warning names the secret and the command that supplies it:
brig: <profile> runs without 1 secret
○ <name> → brig secret import <profile>For a secret with no sources:, the message names brig secret create, because import cannot fill it:
brig: <profile> runs without 1 secret
○ <name> → brig secret create <name>Missing secret warnings shows the full warning for claude-code.
Linux hosts without a keyring
On Linux, the store is a Secret Service keyring. A host with no session bus, or with nothing that answers on it, has no store.
| Secret | Result on a host with no store |
|---|---|
| Required | Every run fails, in the same way as any missing required secret |
| Optional | No warning. The run boots |
To change the result, install a keyring. The built-in claude-code profile still boots on a host with no store, because its secret is optional.
env #
The variables that the guest sees, and the source of each value: a literal, a stored secret, or Brig's environment.
env:
- name: GH_TOKEN
ref: secrets.gh_token
- name: CI
ref: env.CI
- name: EDITOR
value: viEach entry has a name: and one source:
| Key | Source |
|---|---|
value: |
A literal, for configuration that is not a credential |
ref: secrets.<name> |
The named secret in Brig's store |
ref: env.<name> |
The named variable in Brig's environment |
refs: |
A list of refs. The first that resolves wins |
A binding carries ref: or refs:, never both.
env:
- name: GH_TOKEN
refs: [env.GH_TOKEN, secrets.gh-token] # shell override first, store secondA name that a profile binds is no longer forwarded from your shell. With a bare ref: secrets.gh-token, the value from GH_TOKEN=$(gh auth token) brig run claude does not reach the guest, and BRIG_FORWARD_ENV cannot restore it. The chain above keeps the shell override and adds the store as a fallback. The built-in claude-code profile binds GH_TOKEN this way.
If an earlier env. element resolves, the run does not need the later secrets. element.
Limits:
- An entry has one of
value:,ref:orrefs:. Brig refuses any other combination. - A ref namespace other than
secrets.orenv.is a parse error. - A
secrets.<name>ref whose name is absent fromsecretsis a parse error.
Runtime variables #
Brig passes HOME, PATH, TMPDIR and XDG_* on the runtime's command line. A binding for one of these names takes value: or ref: env.<name>. Brig refuses one that resolves from the secret store, because a stored secret never goes on the command line. See Security.
BRIG_PROJECT #
Brig sets BRIG_PROJECT itself, to the guest path of the run's project. Without a project, the variable is unset. Brig ignores a binding of that name, including one from BRIG_FORWARD_ENV, and prints a warning. The CREDENTIALS row does not name the binding.
BRIG_FORWARD_ENV #
BRIG_FORWARD_ENV overrides which variables Brig carries in from its environment. It replaces the profile's ref: env.<name> bindings, and only those. A ref: secrets.<name> binding survives the override.
Sandboxes served by brigd #
For a sandbox that brigd serves, an env.<name> ref resolves against the environment of the daemon, not of the shell that sent the request. See brigd.
files #
Credential files that the guest sees. Each entry names a stored secret and the path under guestHome where Brig writes it.
files:
- ref: secrets.claude-credentials
path: .claude/.credentials.json # relative to guestHome
mode: "0600" # default "0600"; quoted, see below| Key | What it is |
|---|---|
ref |
The stored secret, as secrets.<name> |
path |
Target path, relative to guestHome |
mode |
File mode, as a quoted string. Default "0600" |
Use files: where the agent can read a credential from a file, and env: where it cannot. A file stays out of /proc/<pid>/environ. The processes that the agent spawns do not inherit it. Brig can rewrite it under a running agent, so a rotated secret can reach a live session.
The agents that use GEMINI_API_KEY, XAI_API_KEY, OPENROUTER_API_KEY and CURSOR_API_KEY read them only from the environment. You can bind one secret through both channels. The exposure is then the union of the two, so do it only when something reads both.
Limits that the parser enforces:
ref:only. Brig refusesrefs:andenv.<name>.mode:is a quoted string. YAML reads an unquoted0644as the number 420, so Brig refuses a mode that is not quoted. A profile file with an unquoted mode does not load. If that file overrides a built-in profile, Brig warns, ignores the file and runs the built-in.- The target must be inside a
tmpfsvolume. Ahostmountunder that volume must not bind the target back out. Brig refuses this at parse time. Seevolumes. - One binding per
path:.
Other limits:
field:on a file-bound secret writes a bare token where the agent expects a document. The agent then tries a refresh, fails, and prompts. Usefield:only when the agent reads a one-line file.- An unresolved binding leaves no file, no mount and no empty target.
brig secret push, for rotating a file binding in a running sandbox, is not implemented yet. A re-run rewrites the file under a live agent.
volumes #
The mounts inside guestHome, one primitive per entry. A tmpfs can instead be mounted at a fixed guest path with at:.
volumes:
- kind: tmpfs
path: .claude # memory-only: nothing written here reaches the host
at: /brig/claude # optional: mount it here, off the home share
size: 512m # optional, default 64m
- kind: hostmount
path: .claude/sessions # ... except these, kept across boots
- kind: hostmount
path: .claude/projects
- kind: hostmount
path: .claude/history.jsonl
file: true # the target is a file, not a directorykind: |
What it does |
|---|---|
tmpfs |
Covers a directory so that nothing written under it can reach your disk |
hostmount |
An exception: one path bound back out to the same path in the guest home |
volume |
Reserved for a named volume that several sandboxes share. Parsed and refused as not yet supported |
| Key | Applies to | What it is |
|---|---|---|
path |
both | Path inside guestHome |
at |
tmpfs |
An absolute guest path to mount the tmpfs at, in place of guestHome/path |
size |
tmpfs |
How big the tmpfs can grow. Default 64m |
file |
hostmount |
true when the target is a file, not a directory |
A tmpfs leaves a files binding no path from the credential to the host. Before it hands over a credential, Brig checks that the path reads as tmpfs and that the guest has no swap. Otherwise the run stops.
Order in the file does not matter.
size: is a ceiling. At the ceiling, tools in the guest get ENOSPC, and nothing on the host watches for it. A directory of configuration needs less than the home of an agent, where edit history and per-job scratch accumulate.
Limits:
- A
hostmountmust be nested under atmpfs. Otherwise it is a parse error. - Brig refuses
source:,size:andat:on ahostmount. size:must be a number optionally followed byk,morg. Brig refuses anything else at parse time.
Warning State that an agent writes under a
tmpfs-covered path with no matchinghostmountdoes not survivebrig stop.
The built-in profiles differ here:
| Profile | Hostmounts under .claude |
Result |
|---|---|---|
claude-code, herdr |
Include .claude/skills, .claude/plugins and .claude/.claude.json |
A --skills copy there survives a stop, and so does the agent's global state |
claude-desktop |
settings.json, CLAUDE.md, sessions, projects, plugins and history.jsonl |
.claude/skills is not kept. Anything the bundled desktop app writes there is lost at shutdown |
claude-code, claude-desktop and herdr are the only built-in profiles that declare volumes:. The other six, codex, cursor, gemini, grok, opencode and ubuntu, persist everything under guestHome to host disk, with nothing memory-only.
at #
The guest home is a share from the host. If the host renames or replaces a directory on it, for example with git clean -fdx, the guest can drop a mount there. The path then leads back to host disk, and the next credential the agent writes lands there. Put memory-only state at a path of Brig's own, such as /brig/<name>, and point the agent there with env:.
- Keep writing
path:,hostmountentries andfiles:bindings relative toguestHome. Brig maps them to the same relative path underat:. - A host-side rename of the home cannot move a
hostmountunder a relocatedtmpfseither. - On the
hvibackend,/brigsits on a per-sandbox root that only the host user writes. claude-codeandherdrmount their.claudetmpfsat/brig/claudeand setCLAUDE_CONFIG_DIRto it.claude-desktopstill covers.claudeinside the guest home.
Only kind: tmpfs takes at:. Brig refuses, at parse time, an at: that:
- is not absolute and clean, or is
/ - is
guestHomeor overlaps it - sits in a system directory (
/proc,/sys,/dev,/run,/tmp,/etc,/usr,/bin,/sbin,/lib*,/boot,/var) or in/work, where a project is mounted - overlaps the
at:of anothertmpfs
It also refuses two tmpfs volumes whose path: values nest when either one sets at:.
deny #
Variables that Brig never binds, whatever env says.
deny:
- MYTOOL_ADMIN_KEY # lets the agent reconfigure the accountSome provider variables outrank the credential that you want the sandbox to use. For example, Claude Code prefers ANTHROPIC_API_KEY to its subscription credential. If Brig forwards it, the sandbox moves from your subscription to metered API billing and does not tell you. Put each variable of this type in deny.
Brig says why when it holds a denied variable back. BRIG_ALLOW_DENIED=1 overrides the refusal, for a user who wants metered billing.
Limits:
denyapplies in the same way to a value that arrives byref:.denyguards the environment channel only. Brig does not check afiles:binding against it, so a profile can deliver a metered key inside asettings.jsonand nothing detects it.
staleCredentialFiles #
Paths where an older wrapper wrote a credential. If Brig finds one, it warns and does not delete it.
staleCredentialFiles: [.claude/.credentials.json]headless #
States that the agent supports a non-interactive run.
headless: trueguiTitle #
The window title for a kind: gui profile.
kind: gui
guiTitle: Claude Desktopnetwork #
The network posture of the sandbox. A new sandbox defaults to isolated.
network: isolated| Value | Meaning |
|---|---|
shared |
One network for the sandboxes that use it |
isolated |
A network for this sandbox only |
offline |
No route out |
See Policies for the postures.
An existing sandbox keeps its posture. BRIG_NETWORK, --network and --offline override the profile and a recorded posture.
The vz and qemu backends
| Case | Result |
|---|---|
No posture named, on the vz or qemu backend |
Falls back to shared, and Brig reports it |
Explicit isolated on vz or qemu |
Refused |
If you copy a profile that names isolated and change its backend to vz or qemu, change the network to shared too.
hypervisor #
The macOS backend to boot on. On Linux it applies only to a genericBoot profile.
hypervisor: hvi| Value | Notes |
|---|---|
vz |
The default on macOS when the field is absent. The only backend with a graphical console. On Linux it means hvi |
hvi |
Seven of the nine built-in profiles say hvi. The default on Linux when the field is absent |
qemu |
The Linux runtime bundle does not ship it |
BRIG_HYPERVISOR overrides the field. See Environment variables.
runtimeBin #
The runtime binary to drive, in place of the one on PATH. Brig expands ~.
runtimeBin: ~/bin/hullThis field describes your machine, so it is of no use to a person you share the profile with.
BRIG_RUNTIME_BIN overrides the field.
rootfsType #
How the guest root reaches the microVM: block, virtiofs or 9pfs.
rootfsType: block # room to apt installIf the field is unset or virtiofs, a genericBoot profile boots an overlay root where the host can build one. BRIG_ROOTFS_MODE=virtiofs turns the overlay off. See The guest root of a generic boot.
If the sandbox installs packages, set block. The sandbox then has a writable disk.
genericBoot #
States that the image is a plain OCI image such as ubuntu:latest, with no kernel and no urunc metadata. Brig supplies the kernel and initrd and boots the image unmodified, on macOS and Linux.
name: plain-ubuntu
image: docker.io/library/ubuntu:latest
guestHome: /root/work
kind: shell
binary: bash
genericBoot: true
rootfsType: block # room to apt install
mem: 4096
cpus: 2Brig never modifies the image, and it runs as it does anywhere else. The profile is the same on macOS and Linux.
On Linux it needs nerdctl and the urunc that the runtime bundle builds. Brig refuses docker before the boot. See Runtimes.
The kernel and the initrd:
- They are host files. Brig never takes them from the image, so an image cannot name a file on your machine.
- The kernel is
Imageon arm64 andbzImageon x86_64. The initrd iscontainer-initrd. - The image needs no guest agent of its own.
brig shtalks to the one in the initrd. - The Linux runtime bundle carries them, so a bundle install fetches nothing.
- If the files are missing, Brig fetches them once, on the first
brig runof agenericBootprofile. On Linux they go in$XDG_DATA_HOME/brig/assets(default~/.local/share/brig/assets), and the fetch needsoras. Without it, Brig says so and tells you what to fetch.
| Variable | Effect |
|---|---|
BRIG_BOOT_ASSETS |
Names the directory that holds the files, on both platforms. It also turns the fetch off, so Brig never downloads a release bundle over a build you work on |
BRIG_BOOT_ASSETS_REF |
Pins a specific bundle in place of the current one for your platform |
The bundle is the OCI artifact ghcr.io/nofireai/hull-assets, and it pulls anonymously. To do the same fetch by hand:
oras pull ghcr.io/nofireai/hull-assets:<os>-<arch> --output <dir>See Guest image for what genericBoot means for the image.
hostConfigDir #
The directory of your agent configuration on the host. Brig uses it only when the run passes --skills or sets BRIG_SKILLS=1.
hostConfigDir: ~/.claude
projectPaths: [skills, plugins]Limits:
hostConfigDirandprojectPathsare required together.- Only
claude-codeandherdrdeclare them, so--skillsdoes nothing on the other seven built-in profiles.
projectPaths #
The subdirectories of hostConfigDir that Brig seeds into the guest home, under the same condition.
hostConfigDir: ~/.claude
projectPaths: [skills, plugins]Limits:
- Required together with
hostConfigDir.
onboarding #
A first-run state file to seed.
onboarding:
file: .claude/.claude.json
seed:
hasCompletedOnboarding: true
hasTrustDialogAccepted: true
trustKey: [projects, hasTrustDialogAccepted]| Key | What it does |
|---|---|
file |
The agent's state file |
seed |
The flags to write |
trustKey |
The two JSON levels around a directory name, for an agent that records trust per directory |
Some agents stop on a first-run screen that the guest cannot answer, such as a login choice that opens a browser. A few non-secret flags in the agent's state file answer it.
Brig sets trustKey for the directory that each run starts in, resolved to the git repository root.
Limits:
- Brig writes
seedonly whenfiledoes not exist. It never overwrites the agent's own file. - Brig never seeds anything that contains a credential.
An older claude-code workspace has .claude.json at its root. Brig moves it into .claude once, before boot, and never over a file already there.
reserved #
Stops a session name from landing on the guest home that another profile owns.
reserved: trueA session's guest home is named after the agent and the label, joined by a dash, so the pair can spell another profile's name. The built-in claude-desktop profile sets reserved: true, so Brig refuses a session whose agent and label join to claude-desktop.
brig run claude@desktopis allowed.claudeis an alias ofclaude-code, so its guest home is~/.brig/homes/brig-claude-code-desktop.- If you name a profile of your own
claude, it wins over the alias, and Brig refusesclaude@desktop. brig agent importrefuses a profile nameddesktop.
Warning A profile of your own named
my-codexwithreserved: truereservescodexthe same way. Brig then refuses to import a profile namedcodex, including one meant to override the built-in.
unpublished #
States that the profile ships without an image. brig run reports this and stops before the pull.
unpublished: trueTo run the profile anyway, pass --image with an image that you built. brig agent ls marks the profile (no published image). cursor is the only built-in profile with the field.
policy #
Names of policies attached inline to this profile. Every run carries all of them, together with the policies attached separately by name. See Policies.
Limits:
- Not allowed on a
kind: shellorkind: guiprofile.
Worked example #
This profile runs a CLI called mytool from your image:
# The vendored CLI needs a bigger guest than the default.
name: mytool
desc: our internal agent
image: ghcr.io/example/mytool:arm64
guestHome: /home/mytool
binary: mytool
env:
- name: MYTOOL_TOKEN
ref: env.MYTOOL_TOKEN
- name: GH_TOKEN
ref: env.GH_TOKEN
deny:
- MYTOOL_ADMIN_KEY # lets the agent reconfigure the account
headless: true
mem: 8192
cpus: 4brig agent import mytool.yaml
MYTOOL_TOKEN=$(pass show mytool/token) brig run mytoolThe image is outside ghcr.io/brig-sh, so Brig warns on every boot. See image.
Building the image #
Brig does not build the image. bring-your-own-image.md documents how to build one. The images of the built-in profiles are open source at brig-sh/community-images.
Guest image is the full contract: every binary that Brig execs inside the guest, and the account it expects. It also names a script that checks an image that you built.
Profile directory #
The nine built-in profiles are embedded in the binary, so brig run claude needs no install step.
Your profiles are one file each in $XDG_CONFIG_HOME/brig. The default is ~/.config/brig. The directory is flat: ~/.config/brig/mine.yaml. BRIG_PROFILE_DIR overrides the location.
The directory starts empty. Only three commands write to it:
| Command | Overwrites an existing file |
|---|---|
brig agent import |
|
brig agent export <agent> <name> |
Only with --force |
brig agent new <name> --from <agent> |
Only with --force |
The location follows the XDG Base Directory Specification, version 0.8. Brig treats an empty or relative XDG_CONFIG_HOME as unset.
Listing profiles #
brig agent ls lists embedded and file-backed profiles together in one namespace. It marks the origin of each:
| Marker | Meaning |
|---|---|
| none | Embedded |
(file) |
A profile that exists only as a file |
(file, overrides built-in) |
A file that shadows an embedded profile |
A file can take the name of a built-in profile. Use this to pin your image for a profile that Brig knows.
Duplicate names #
The file name and the name: inside the file can differ, so two files can declare one name. Brig reports the collision and says which file won. See Confirmation for how brig agent rm treats them.
Settings from older versions
- Brig refuses to start while
BRIG_TEMPLATE_DIRis set andBRIG_PROFILE_DIRis not. - Brig does not read
~/.config/brig/templates. If files remain there, Brig says so on every invocation. Move them withbrig agent import.
Built-in profiles #
| Profile | Alias | Kind | Image | Network |
|---|---|---|---|---|
claude-code |
claude |
agent | ghcr.io/brig-sh/claude-code-stock:root |
isolated |
claude-desktop |
desktop |
gui | ghcr.io/nofireai/urunc-claude-desktop:aarch64 |
shared |
codex |
agent | ghcr.io/brig-sh/codex-stock:root |
isolated |
|
cursor |
agent, example profile | ghcr.io/brig-sh/cursor:latest |
unset | |
gemini |
agent, example profile | ghcr.io/brig-sh/gemini-stock:root |
isolated |
|
grok |
agent, example profile | ghcr.io/brig-sh/grok-stock:root |
isolated |
|
herdr |
herd |
agent | ghcr.io/brig-sh/herdr-stock:latest |
isolated |
opencode |
agent, example profile | ghcr.io/brig-sh/opencode-stock:root |
isolated |
|
ubuntu |
shell | docker.io/library/ubuntu:latest |
isolated |
Built-in profiles prints the full YAML of each one.
"example profile" is the desc: of the profile, and brig agent ls prints it.
herdr is claude-code with sshd and a herdr server in the image. See herdr.
Kinds. claude-desktop opens a window, and ubuntu opens a shell. See kind.
Images. cursor declares unpublished: true. brig run refuses it before it reaches the registry. To run it, pass your own --image.
Signatures. claude-code, codex, gemini, grok and opencode are Brig's multi-architecture builds under ghcr.io/brig-sh. herdr is Brig's own build there too. Brig can verify the signature of all six. claude-desktop and ubuntu are outside it, at ghcr.io/nofireai/ and Docker Hub, so Brig warns on every boot. See image. The claude-desktop image is also single-architecture, aarch64 only.
Network. The seven isolated profiles use hvi. claude-desktop uses shared because its GUI requires vz. cursor leaves the posture unset: Linux and hvi isolate, and vz and qemu fall back to shared. These are defaults for new sandboxes. See network for existing sessions.
Export and import #
brig agent export claude-code # prints to stdout
brig agent export claude-code mine # ~/.config/brig/mine.yaml
brig agent export claude-code mine --force # ...overwriting what is there
brig agent export claude-code > ./mine.yaml # a copy somewhere of your own
brig agent export x | brig agent import -Export writes YAML, comments included. Import stores your bytes as written, so your comments and your ordering stay.
An exported built-in profile carries its explicit network: value. Before you change its backend to vz or qemu, see network.
If a program reads profiles, use brig agent show --json. Import reads both YAML and JSON.
Destination names #
The destination is a name, never a path. For a copy in another location, export to stdout and redirect it.
Brig refuses these destinations, and each refusal names the collision:
| Destination | Why it is refused |
|---|---|
| A path, or a typo that looks like one | Brig writes only to the profile directory |
An alias: claude, desktop or herd |
A profile of that name wins the lookup over the alias. Every brig run claude would then run the copy, and the built-in is reachable only as claude-code |
A name that a reserved profile owns |
The same reason |
Inspecting a run #
brig info <profile> reports what the guest receives. It reports names only, never a value.
$ brig info mine
...
brig: workspace /Users/you/.brig/homes/brig-mine (sandbox brig-mine)
brig: runtime hull (/opt/homebrew/bin/hull)
brig: image ghcr.io/brig-sh/claude-code-stock:root (pull missing)
brig: image verification: warn, against brig's own trust policy
brig: forwarding to guest:
brig: GH_TOKEN(secret)
brig: CI
brig: EDITOR
brig: guest git over HTTPS: off (BRIG_GIT_CONFIG=1 to enable)(secret)marks a variable from the secret store. An ambient or literal variable has no mark.- The
...stands for the block that comes first (PROFILE,SANDBOX,WORKSPACEand the rest). brig inforesolves secrets as a run does. A profile that misses a required secret fails here as it does underbrig run.
BRIG_ENV_ARGV #
BRIG_ENV_ARGV=1 puts ordinary forwarded variables on the runtime's command line. It is for a runtime build that does not take a bare --env KEY.
A value on that command line can be logged to a file on host disk. Brig never does this for a stored secret, so on such a build a stored secret does not arrive at all. See Security.
Removing a profile #
brig agent rm mytoolThe argument is a profile name or an alias, not a file name. rm finds the file under any file name.
Built-in profiles are compiled in and cannot be removed. To shadow one, import a profile of the same name.
Confirmation #
File that rm resolves to |
What rm does |
|---|---|
The file you named, such as mytool.yaml for brig agent rm mytool |
Removes it without asking |
| A file reached through an alias | Names the file and waits for a y |
| A second file that declares the same profile | Names the file and waits for a y |
| A file renamed by hand | Names the file and waits for a y |
If more than one file declares the name, rm removes all of them.
-y answers in advance, as in brig secret delete:
brig agent rm claude -y # removes your file for claude, without askingIf there is no terminal to ask on, rm refuses and says so.
Existing sandboxes #
rm refuses while a sandbox of the profile exists, running or stopped. It names the brig rm <ref> command for each one.
Remove those sandboxes first. After the file is gone, brig rm <ref> cannot reach them. You must then use brig rm --all, or create a new profile of the same name.
rm does not refuse an override of a built-in profile, because the name still resolves to the built-in profile.
How rm finds the runtime
To find sandboxes, rm asks the runtime of the profile what it holds.
| Case | Runtime that rm asks |
|---|---|
| Brig has recorded a session of the profile | The profile's runtimeBin |
| No session recorded yet | The runtime on PATH |
So rm never executes the runtimeBin of a profile that you imported and never ran.
If Brig cannot ask, rm keeps the file and names the cause. Correct that setting first. The causes are:
BRIG_RUNTIMEis set to a runtime Brig does not know.runtimeBinpoints at nothing, on a profile Brig has run.
With no runtime installed, there are no sandboxes, and rm continues.