Guides
Brigfile
On this page
A Brigfile is a YAML file at the root of a repository that defines how to run an agent on that repository under Brig. It lists targets. Each target names a profile, the policies to apply, the sandbox size and the agent's default arguments.
The Brigfile belongs to the repository, and an agent in a sandbox can change it and every file it names. So before Brig runs a target, it shows you the resolved configuration and asks you to approve it. A run boots only a configuration you approved.
Quick start #
brig init # create a Brigfile at the root of the worktree
brig target ls # list its targets
brig config --target dev # show the resolved configuration of dev
brig plan --target dev # show what a run of dev would get
brig run --target dev # approve the run, then start itbrig init creates a Brigfile with one target, dev, that uses the built-in claude-code profile. If a Brigfile already exists, brig init leaves it unchanged.
brig target ls and brig config only read the Brigfile and the files it names. brig init writes the Brigfile and nothing else. None of the three starts a sandbox, reads a secret or needs a runtime.
File format #
apiVersion: brig.sh/v1alpha1
name: demo
defaultTarget: dev
profiles:
claude:
from: builtin:claude-code
tool:
file: .brig/tool.yaml
policies:
anthropic:
file: .brig/anthropic.yaml
targets:
dev:
profile: claude
policies: [anthropic]
overrides:
cpus: 2
args: ["--continue"]
ci:
profile: toolTop-level fields:
| Field | Required | Description |
|---|---|---|
apiVersion |
yes | brig.sh/v1alpha1 |
name |
no | A display name |
defaultTarget |
no | The target to run when none is named. Must name a target in targets |
profiles |
no | Profile aliases |
policies |
no | Policy aliases |
targets |
yes | One or more targets |
Target fields:
| Field | Required | Description |
|---|---|---|
profile |
yes | A profile alias |
policies |
no | Policy aliases. Each alias can appear once |
overrides |
no | Replaces the profile's cpus, mem (in MB) or image |
args |
no | The agent's arguments. Arguments after -- on the command line replace them |
Alias and target names can contain lowercase letters, digits, ., - and _, and must start with a letter or a digit.
Brig parses the Brigfile strictly. It rejects unknown keys, duplicate keys, and a number or boolean where a string is expected, so quote values such as "0600" or "yes". Each error names the file and the field.
Aliases #
Declare each profile or policy alias in one of three forms:
| Form | Source |
|---|---|
from: builtin:<name> |
A profile that ships with Brig, such as builtin:claude-code. Profiles only |
file: <path> |
A profile or policy file in the repository |
inline: |
A complete profile or policy, written in the Brigfile |
A builtin: profile resolves the same way on every machine. Brig ignores any file in your profile directory that overrides the built-in, and brig config tells you when it does.
If a target overrides image on a builtin: profile, the profile's credential bindings still apply, so the image the repository names receives those credentials. brig plan --target reports this in a NOTE row.
A file: path is relative to the directory that contains the Brigfile. Brig rejects absolute paths, paths that contain .., and links that point outside that directory. Profile files use the format in Agent profiles, and policy files use the format in Networking.
A target that uses a shell or gui profile cannot list policies, because Brig does not enforce policies on those profiles.
Validate a Brigfile in your editor
brig init writes a schema comment as the first line of the Brigfile, so a YAML editor validates the file as you type:
# yaml-language-server: $schema=https://raw.githubusercontent.com/brig-sh/brig/main/api/project/v1alpha1/brigfile.schema.jsonA release writes the URL for its own tag, so the editor validates against the fields that release supports. Any other build, such as a release candidate, a channel build or a build from source, writes main, as shown.
To validate every file named Brigfile in VS Code, install the YAML extension and add this to your settings:
{
"files.associations": { "Brigfile": "yaml" },
"yaml.schemas": {
"https://github.com/brig-sh/brig/releases/latest/download/brigfile.schema.json": "Brigfile"
}
}The schema checks only the structure of the file. Run brig config to check the rest.
Where Brig looks #
In a Git checkout, Brig reads the Brigfile at the root of the worktree. It does not look in subdirectories or parent directories. Outside Git, Brig reads the Brigfile in the current directory.
To use a different file, pass -f <path>. The directory that contains that file becomes the project, and file: paths resolve relative to it:
brig target ls -f ci/Brigfile.ciPlan a target #
brig plan --target dev
brig plan --target dev --jsonbrig plan --target prints what a run of the target would get, without starting a sandbox, reading a secret or writing a file. Review the plan before you run a target. It shows:
- the target, its Brigfile, and the profile and where it comes from
- where the image, memory, vCPU count and network come from
- whether the image is pinned by digest
- each policy and where it comes from
- for each route: its upstream, the secrets from your store that it uses, its preset, the git URLs it rewrites and the guest variables it sets
Brig takes the image, memory and vCPU count from the first of these sources that sets them:
- a flag on the command line
- a
BRIG_*setting - the target's
overrides - the profile
The network follows the same order, except that overrides cannot set it.
Which BRIG_* settings apply depends on where the profile comes from. A target on a builtin: profile reads that profile's settings, such as BRIG_CLAUDE_CODE_IMAGE. A target on a file: or inline: profile reads only the global settings, such as BRIG_IMAGE, whatever the profile is named.
Which policies apply #
A target gets all of these policies together:
- the target's
policies - the policies a repository profile lists under
policy: - for a
builtin:profile only, that profile's own policies and any policies you attached to it withbrig policy attach
Brig reads a Brigfile's policies from the repository, never from your policy directory. A repository profile gets none of the policies you attached, whatever its name, and a policy you attached to one session with -n does not apply to a target.
Allow rules and routes from every applied policy take effect, so adding a policy can give the agent more access. Plan the target again after you change its policies.
If any applied policy sets an egress default or a route, the run does not use the shared network, even with --network shared.
Run a target #
brig run --target dev
brig run --target dev -- --resume
brig runbrig run --target <name> starts the target's sandbox and runs its agent. The project is the directory that contains the Brigfile. Brig mounts it read-write at /work/<name> and starts the agent there.
- The agent receives the target's
args. Arguments after--replace all of them. brig runwith no profile and no--targetruns thedefaultTarget. If the Brigfile sets nodefaultTarget, Brig lists the targets and exits with status2.- A target run takes no profile or project argument, and rejects
--homeand--no-project.
Brig keeps its records of target sessions, and your approvals, in its state directory. Because the project is mounted read-write in the guest, run, plan, stop and rm --target refuse a project that contains Brig's state directory (~/.brig) or sits inside it. They refuse before asking for approval. In that case, set BRIG_STATE_DIR to a directory outside the project.
The approval #
The first time you run a target, Brig prints the plan and asks for approval:
brig: target dev in /home/you/code/demo asks to run with this configuration
brig: ↳ the Brigfile and the files it names are the repository's, and the agent can change them
brig: ↳ nothing runs until you approve it
...
ARGS "--continue"
APPROVAL sha256:b8fce0d5...
brig: run target dev as shown above? [y/N]Only y or yes approves the run. Any other answer, an empty line or closed input refuses it.
Brig stores your approval, and later runs with the same configuration start without asking. If anything has changed, Brig prints the plan again and lists each change:
brig: this differs from what you approved on 2026-11-13 17:01:32
brig: ↳ the file .brig/egress.yaml (policy egress) changedAn approval covers:
- the Brigfile and every file it names
- the resolved profile
- each policy and route
- the image reference
- the size, network and mounts
- the settings in effect
- the credential bindings
- the published ports
- the runtime
- the agent's arguments
A change to any of these needs a new approval. A change to your source code does not.
Some runs fail before Brig asks for approval, for example when two policies define routes with the same name, or when a secret the run needs is missing from your store.
An approval stores names, paths and digests, never secret values. Brig reads your secrets only after you approve. It boots the configuration it showed you, so a change to the Brigfile while the prompt is open does not reach the run.
An approval does not cover:
| Item | Notes |
|---|---|
| An image referenced by tag | A tag can later point to different content, and the prompt warns about this. To pin the content, reference the image by digest in overrides.image |
| The value of a secret | The plan names each secret and the upstream each route sends it to. Review the route rows before you approve |
| What the agent does once it runs | The rest of the Security model applies |
Brig stores approvals in ~/.brig/approvals.json, one for each checkout, target and session. Approving dev does not approve another session of dev, or dev in another checkout. If Brig cannot read the file, it treats nothing as approved. brig rm --target deletes the approval together with the session.
Approve ahead of time #
When there is no terminal, or with --json, Brig does not ask. A run that no stored approval covers boots nothing, exits with status 8 and prints the digest to approve:
brig: target ci is not approved to run as shown above, and there is no
terminal to ask on. To approve it, run the same line with --approve sha256:...Review the plan, then run the same command with that digest:
brig run --target ci --approve sha256:<digest>Brig boots only if the digest matches this run. A digest from a different run is refused with exit status 8, and Brig prints the digest of this run.
The digest covers the checkout path, the command line and your settings, so take it from a run on the same machine and in the same directory. Store it outside the repository, for example in a CI variable that only maintainers can change. Otherwise, anyone who can change the repository can change the Brigfile and the digest together.
Sessions of a target #
Each target has a default session. To start another, pass --session <name>. Each session has its own sandbox and guest home, named from the project, target and session, so two checkouts never share a sandbox. Sandbox names start with brig--. BRIG_NAME and BRIG_WORKSPACE do not apply to a target.
brig run claude in the same checkout starts a session of the profile, not of a target, and does not read the Brigfile.
brig stop --target dev
brig rm --target dev --session fix
brig rm --target ci -f ci/Brigfile.ci --dry-runstop and rm find a session from the project, target and session name. They do not read the Brigfile, so they still work after the Brigfile is deleted or the target is removed from it. With -f <path>, the path names the project, and the file does not need to exist.
brig rm --targetalso removes the session's guest home and approval.brig rm --allalso removes target sandboxes.stopandrmexit with status3when neither Brig nor the runtime knows the session.brig info,brig shandbrig logstake a ref only, and reject--target.
brig ls lists target sessions in a separate table, with the columns TARGET, SESSION, SANDBOX, STATE and PROJECT:
| Row | Meaning | To remove it |
|---|---|---|
| A target and a project | A session that Brig has a record of | brig rm --target <name> in that project |
STATE is unlisted |
Brig has a record of the session, but the runtime did not list its sandbox | brig rm --target <name> |
STATE is on <runtime> |
Another runtime booted the session | brig rm --target <name> under that runtime, or brig rm --forget --target <name> if that runtime is gone |
TARGET is - and PROJECT is unknown |
The runtime has a target sandbox that Brig has no record of | brig rm --all |
A sandbox keeps the configuration it started with. If the Brigfile changes, brig run --target refuses to start and lists what changed. To continue, either boot the new configuration on the same guest home, or remove the session:
brig run --target dev --recreate
brig rm --target dev--recreate asks you to approve the new configuration first.
Repository profile limits #
A profile declared with file: or inline: comes from the repository, not from you. It can describe the guest, but it cannot reach your host or weaken the sandbox. Brig rejects these fields in a repository profile:
| Field | Reason |
|---|---|
runtimeBin |
It names a program on your host |
hostConfigDir, projectPaths |
They name host directories that Brig copies into the guest |
The source of a secret: sources, from, service, path, var, hint, field, expiryField |
A repository can name a secret, but not where its value comes from |
ref: env.<name> |
It copies a variable from your environment into the guest |
A hostmount volume |
It shares a host directory. tmpfs volumes are allowed |
network: shared |
It joins a network shared with other sandboxes. isolated and offline are allowed |
hypervisor |
It selects a hypervisor on your host, which determines the network the sandbox can get |
An image that starts with - |
The runtime would read it as a flag |
No string in a repository profile or policy can contain a control character, because the plan prints these strings to your terminal. These limits do not apply to builtin: profiles.
Repository policy limits #
A policy declared with file: or inline: must follow two rules: a route rewrites git URLs only for its own host, and a preset route keeps the behavior Brig ships. A policy in your own policy directory is exempt from both, so there you can, for example, put a mirror in front of github.com.
Git rewrites #
Each prefix under guest.git.insteadOf must be a URL on the route's upstream:
routes:
- name: forge
upstream: https://git.example.com
credential: {secretRef: {name: forge-token}}
inject: {basicAuth: {username: x-access-token}}
guest:
git:
insteadOf:
- "https://git.example.com/" # accepted
- "https://github.com/" # rejectedPreset routes #
A repository policy chooses the secret for a preset route. It can also point the github-token preset at another host, which is how a repository reaches GitHub Enterprise:
routes:
- name: github
preset: github-token
upstream: https://ghe.example.com
credential: {secretRef: {name: ghe-token}}
request: {allow: {repos: ["team/*"]}}The preset's git rewrites follow the upstream, so this route rewrites git URLs for ghe.example.com, not for github.com.
A repository policy cannot change these fields of a preset route:
| Field | Reason |
|---|---|
upstream of anthropic-api-key or github-api |
The guest finds these routes through a variable rather than a host name, so there is no host to hold the route to |
inject |
The preset defines how the secret is sent |
request of aws |
The preset defines which requests it accepts |
Warning Brig does not check that a repository route's upstream is the service its name suggests, so a secret from your store can go to an upstream the repository names. The plan shows each route's upstream and secrets. Review them before you approve.
Stability #
brig.sh/v1alpha1 is an alpha format, and any release can add, rename or remove a field. See Stability.
For every field, flag and error, see brig's docs/brigfile.md.