brig docs

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 nothing

brig plan prints what a run of mine gets. Its LIMITS row shows the change:

LIMITS       4096 MB, 2 vCPUs

Then 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.yaml

Minimal profile #

name: mine
image: ghcr.io/brig-sh/codex-stock:root
guestHome: /root
binary: codex
mem: 4096
cpus: 4

The 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: mine

Limits:

  • Lowercase letters, digits, dot, dash and underscore only.

image #

The guest image to boot.

image: ghcr.io/brig-sh/codex-stock:root

Limits:

  • 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: /root

kind #

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: shell or kind: gui profile that carries policy:.
  • Only the vz hypervisor backend shows a console. Brig refuses to boot a kind: gui profile on hvi or qemu.
  • v0.5.0 removed the older shell: and gui: booleans. A profile that still has one fails to parse, and the error names kind:. See Migration.

binary #

The agent CLI inside the guest, which brig run execs.

binary: claude

Limits:

  • For kind: shell, Brig does not require or read the field.

mem #

Guest memory size.

mem: 4096

Limits:

  • Must be greater than zero.

cpus #

Guest CPU count.

cpus: 4

Limits:

  • Must be greater than zero.

desc #

One line that brig agent ls shows.

desc: our internal agent

secrets #

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_token

A 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: env and ref: env.<name> behave differently. Brig reads a ref: on every run. A from: env source copies the value into the store when you run brig secret import, and never reads it again. For a value that expires, use a refs: 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 one path: 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_token

If 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_token

A 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: vi

Each 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 second

A 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: or refs:. Brig refuses any other combination.
  • A ref namespace other than secrets. or env. is a parse error.
  • A secrets.<name> ref whose name is absent from secrets is 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 refuses refs: and env.<name>.
  • mode: is a quoted string. YAML reads an unquoted 0644 as 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 tmpfs volume. A hostmount under that volume must not bind the target back out. Brig refuses this at parse time. See volumes.
  • 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. Use field: 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 directory
kind: 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 hostmount must be nested under a tmpfs. Otherwise it is a parse error.
  • Brig refuses source:, size: and at: on a hostmount.
  • size: must be a number optionally followed by k, m or g. Brig refuses anything else at parse time.

Warning State that an agent writes under a tmpfs-covered path with no matching hostmount does not survive brig 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:, hostmount entries and files: bindings relative to guestHome. Brig maps them to the same relative path under at:.
  • A host-side rename of the home cannot move a hostmount under a relocated tmpfs either.
  • On the hvi backend, /brig sits on a per-sandbox root that only the host user writes.
  • claude-code and herdr mount their .claude tmpfs at /brig/claude and set CLAUDE_CONFIG_DIR to it. claude-desktop still covers .claude inside the guest home.

Only kind: tmpfs takes at:. Brig refuses, at parse time, an at: that:

  • is not absolute and clean, or is /
  • is guestHome or 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 another tmpfs

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 account

Some 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:

  • deny applies in the same way to a value that arrives by ref:.
  • deny guards the environment channel only. Brig does not check a files: binding against it, so a profile can deliver a metered key inside a settings.json and 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: true

guiTitle #

The window title for a kind: gui profile.

kind: gui
guiTitle: Claude Desktop

network #

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/hull

This 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 install

If 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: 2

Brig 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 Image on arm64 and bzImage on x86_64. The initrd is container-initrd.
  • The image needs no guest agent of its own. brig sh talks 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 run of a genericBoot profile. On Linux they go in $XDG_DATA_HOME/brig/assets (default ~/.local/share/brig/assets), and the fetch needs oras. 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:

  • hostConfigDir and projectPaths are required together.
  • Only claude-code and herdr declare them, so --skills does 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 seed only when file does 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: true

A 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@desktop is allowed. claude is an alias of claude-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 refuses claude@desktop.
  • brig agent import refuses a profile named desktop.

Warning A profile of your own named my-codex with reserved: true reserves codex the same way. Brig then refuses to import a profile named codex, 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: true

To 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: shell or kind: gui profile.

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: 4
brig agent import mytool.yaml
MYTOOL_TOKEN=$(pass show mytool/token) brig run mytool

The 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_DIR is set and BRIG_PROFILE_DIR is not.
  • Brig does not read ~/.config/brig/templates. If files remain there, Brig says so on every invocation. Move them with brig 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, WORKSPACE and the rest).
  • brig info resolves secrets as a run does. A profile that misses a required secret fails here as it does under brig 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 mytool

The 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 asking

If 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_RUNTIME is set to a runtime Brig does not know.
  • runtimeBin points at nothing, on a profile Brig has run.

With no runtime installed, there are no sandboxes, and rm continues.

Type a command, a flag or an error message.