brig docs

Guides

Networking and egress policy

On this page

You decide where a sandbox can connect. A network posture sets which network the sandbox joins. An egress policy limits the sandbox to the hosts and ranges you allow, for one profile or for one session.

Note Brig enforces an egress policy on Linux with nerdctl, and on macOS 15 or newer with the hvi backend. It refuses a policy-bound run anywhere else, docker included, so a policy is never ignored. --network offline works on every runtime. See Enforcement.

Example policy #

A policy is a YAML file. This one lets the sandbox reach Anthropic's API and one internal range, and nothing else:

apiVersion: brig.sh/v1alpha1
kind: Policy
metadata:
  name: locked-down
  description: only Anthropic's API and one internal range
spec:
  egress:
    default: deny
    allow:
      - host: api.anthropic.com
      - cidr: 10.0.0.0/8
An egress policy at the gateway The sandbox sends every connection through a network gateway that enforces the policy. Connections to api.anthropic.com and 10.0.0.0/8, which the policy allows, pass. A name the policy does not allow does not resolve, and a connection to an address it does not allow does not open. Sandbox claude every connection goes through the gateway Network gateway enforces your policy default: deny allow: - api.anthropic.com - 10.0.0.0/8 api.anthropic.com allowed 10.0.0.0/8 allowed example.com the name does not resolve 203.0.113.7 the connection does not open
The locked-down policy, enforced at the gateway on the hvi backend. For Linux, see On Linux.
A real session, recorded on macOS. The allowed host connects. The other name does not resolve, and the other address does not connect.

Create the policy, attach it to a profile, and check it:

brig policy create locked-down   # writes ~/.config/brig/policies/locked-down.yaml
brig policy attach locked-down claude-code
brig policy check claude-code

brig policy create writes a starter document and opens it in your editor. Fill it in as shown above. brig policy check names each policy bound to the profile, and says where Brig can enforce it:

locked-down
note: enforced on the hvi backend and on Linux with nerdctl, which give the sandbox a network of its own; a run on any other backend is refused rather than left unenforced

Then run the agent as usual, with brig run claude. A sandbox that is already running restarts to take the policy.

To remove the policy from the profile again:

brig policy detach locked-down claude-code

The document covers the format, and A worked example walks through the other verbs.

Tip A policy can also hold routes, which keep an API key on the host and limit the requests that use it. See Routes and Credential broker.

Network postures #

Posture What it permits
shared One network for every sandbox using this posture on the host. Opt-in, except for the vz profiles and retained older sessions
isolated A network of this sandbox's own. The default for new hvi and Linux sandboxes
offline No route out. The agent runs, the guest home is mounted, nothing leaves
brig run claude                         # a new sandbox gets its own network
brig run --network shared claude@shared # explicitly share one with other sandboxes

Both shared and isolated permit internet access. The isolated posture separates sandboxes. It applies no outbound allow list, and it does not promise that host services are unreachable. An egress policy is a separate choice.

Sandboxes on shared reach each other on hvi and on Linux. vz is not measured on a current hull. --network isolated keeps a sandbox off the shared network. Security has the measurements for each backend.

Setting a posture #

Brig uses the first posture it finds in this order:

  1. The --network flag, such as brig run --network offline claude.
  2. The BRIG_NETWORK setting, such as BRIG_NETWORK=shared.
  3. The posture that the sandbox was started with.
  4. The network: field of the profile, such as network: isolated.
  5. The default for the backend.

Brig refuses a run with an unrecognized value and names the source of the value:

$ BRIG_NETWORK=bogus brig info claude-code
brig: BRIG_NETWORK "bogus" is not a posture: use shared, isolated or offline

Default postures #

On macOS, isolated needs the hvi backend.

Case Default posture How to override
New sandbox on hvi or Linux isolated --network or BRIG_NETWORK
The seven built-in hvi profiles isolated, named explicitly in the profile --network or BRIG_NETWORK. On vz or qemu these profiles need --network shared or BRIG_NETWORK=shared
claude-desktop shared. Its GUI requires vz, where Brig cannot give a sandbox its own network --network or BRIG_NETWORK
The unpublished cursor profile Unset in the profile. isolated on Linux and hvi, the shared fallback on vz and qemu --network or BRIG_NETWORK
Custom profile with no network: field, on vz or qemu shared, only when no flag, environment setting or retained posture names a network. The NETWORK row in brig info names that fallback --network or BRIG_NETWORK. An explicit isolated is refused
Existing sandbox The posture it was started with Name a different posture with --network or BRIG_NETWORK. Brig restarts the sandbox
Sandbox with an egress policy or a route bound isolated, forced. An offline run stays offline Detach the policy

Changing a posture #

A later command that names no posture, such as brig sh, brig info or a bare brig run, uses the posture the sandbox was started with. The network: field of the profile does not change it.

The posture is fixed at boot. If you name a different posture, Brig restarts the sandbox and names both postures:

$ brig run claude --network shared
brig: this sandbox was started with the isolated posture and --network asks for shared
  ↳ rules are fixed when a sandbox boots, so brig restarts it
  ↳ any other session using this sandbox will be disconnected

brig rm removes the record of the posture with the sandbox.

Posture in brig info #

brig info prints the posture as one of these three lines:

NETWORK      shared (one network for every sandbox on this host)
NETWORK      isolated (a network of this sandbox's own)
NETWORK      offline (no egress)

The row names the posture of the running sandbox. If the next boot gets a different posture, the row names that posture too. One cause is a policy attach or detach:

NETWORK      isolated (a network of this sandbox's own); shared from its next boot

Postures and policies #

An egress policy bound to a sandbox forces the isolated posture, whether or not --network asks for it. So does a route. A run with a route therefore needs no --network isolated. An offline run stays offline under a policy. A run with a route and the offline posture is refused, because it has no network to reach the route on.

Brig records the posture you asked for, not the forced one. After you detach the policy, the sandbox returns to the recorded posture. Until its next boot, brig info names isolated, the posture the sandbox runs with.

To keep isolated after a detach, pass --network isolated while the policy is attached. Brig restarts the sandbox to record that posture.

Isolation cost #

On hvi, the network of each isolated sandbox used about 28.7 MB of memory in the measurement in issue 369. That figure is a measurement and not a resource guarantee.

The isolated address pool has 64 networks. If the pool is exhausted, Brig refuses another boot. To free networks, remove unused sandboxes with brig rm <ref>. Linux does not use this pool.

The vz and qemu backends

On macOS, isolated needs the hvi backend. vz and qemu take their network from vmnet, which Brig does not own. Brig refuses --network isolated on those backends.

Default postures lists the shared fallback on these backends. The NETWORK row in brig info names that fallback.

Sessions with no posture record, and other rare cases

A session from an older release can have no posture record. Brig then reads the posture from the runtime, and a run that reuses the sandbox records it.

When Brig cannot establish the posture, brig info reports it as unknown, and Brig refuses a run that names no posture. Name the posture with --network or BRIG_NETWORK to recreate the sandbox. That disconnects any session that uses it. If you removed the VM with hull rm, brig ls prunes the stale session, and brig rm <ref> forgets it.

If you changed BRIG_GATEWAY_DIR or BRIG_GATEWAY_SOCK since the sandbox booted, Brig cannot find its network records. Restore the settings, or name --network. Brig rejects a BRIG_GATEWAY_SOCK override named sandbox-*.sock, because isolated gateways use that name. Older releases allowed a shared override with that name, and Brig can report a sandbox started that way as isolated when it is shared.

An older release that boots the sandbox again does not update the record. brig info can then name a posture that the sandbox no longer has. A brig stop and a brig run from the current release write a new record.

Writing a policy #

A policy is a named YAML or JSON document that declares what an agent can reach outbound. It sets a default of allow or deny, and host or cidr exceptions on either side. It can also hold routes.

brig policy create locked-down   # writes ~/.config/brig/policies/locked-down.yaml
brig policy edit locked-down     # change the rules

Policy files #

Brig keeps one file per policy in a flat directory, for example ~/.config/brig/policies/locked-down.yaml.

Setting Policy directory
Default ~/.config/brig/policies
$XDG_CONFIG_HOME set $XDG_CONFIG_HOME/brig/policies
BRIG_POLICY_DIR set That path, taken as given, relative or not. It overrides the other two

An empty or relative $XDG_CONFIG_HOME counts as unset. This follows the XDG Base Directory Specification, version 0.8.

The directory starts empty. Brig writes there only when you run brig policy create, edit, rm, attach or detach.

metadata.name: in the file overrides the filename, as it does for a profile. create always names the file after the policy. A directory can hold any number of policies.

A file that fails to parse does not stop the other files from loading. brig policy ls reports that file on stderr and lists every policy that loaded. It reports two files that declare the same name in the same way.

The document #

Example policy shows a complete document. It uses the Kubernetes envelope: apiVersion, kind, metadata and spec.

Field Required What it is
apiVersion yes Pins the document shape. brig.sh/v1alpha1 is the only value this build knows. Anything else is refused
kind yes Policy. A document without kind is read as the flat form. See The flat form
metadata.name yes The policy's identifier. See Naming a policy
metadata.description no One line, shown by brig policy ls
metadata.labels, metadata.annotations no Maps of strings. Brig does not read them
spec.egress.default yes, with spec.egress allow or deny, applied to any traffic neither list below names
spec.egress.allow no Exceptions to a deny default
spec.egress.deny no A host or range to refuse. For its priority over allow and default, see Limits
spec.routes no Routes to the credential broker. See Routes

A policy needs spec.egress, spec.routes, or both.

Each entry in allow or deny names one of host: or cidr:. Brig refuses an entry with both or with neither.

Rule Value Validation
host: A domain, or a glob such as "*.githubusercontent.com" Refused only for whitespace or a control character
cidr: A network range such as 10.0.0.0/8 Refused when it is not a valid range. A typo like 10.0.0/8 is refused

A host: glob matches the name that the guest looks up. * spans dots, and *.example.com does not cover example.com itself.

Parsing is strict. A document with an unrecognized field fails to parse, such as engine: under spec or a typo such as descripton:. A key must match the field name byte for byte, so Spec:, or a key with a lookalike letter, is refused too. So is a block or a list with no value, such as allow: with every rule under it commented out. Give it a value, or leave the key out. A file holds one document, and Brig refuses a second one after ---.

The flat form #

Older policies leave out kind and put name, desc and egress at the top level. Brig still reads that form until v0.6.0, and converts it to the envelope as it loads it. A key in the flat form matches its field without regard to case, as in Egress:. Brig refuses two spellings of one key, such as name: and Name:, and a second document after ---. brig policy check prints a notice for each bound policy that is still in the flat form, and brig policy show prints any policy in the envelope form. Policy documents has the mapping.

Routes #

A route keeps a credential on the host and limits the requests that use it. Credential broker covers routes, their presets and their request rules.

apiVersion: brig.sh/v1alpha1
kind: Policy
metadata:
  name: claude-only
  description: Claude Code through the broker; no other egress
spec:
  egress:
    default: deny
  routes:
    - name: anthropic
      preset: claude-code
      credential:
        secretRef: { name: claude-credentials }

A sandbox on hvi, or on Linux with nerdctl, reaches a route at https://brig.internal. On hull's vz or qemu backend, and on docker, Brig refuses a run bound to a policy with routes before anything boots, with exit code 7:

brig: policy claude-only (route anthropic) declares a route in mode endpoint, which the guest reaches at brig.internal: a policy applies to this sandbox, and hull on vz cannot enforce the route mode endpoint: vz takes its network from vmnet, and brig routes brig.internal at the user-mode network gateway that only the hvi backend uses. Run it on hvi (BRIG_HYPERVISOR=hvi), or detach the policy. brig will not boot a sandbox under a policy nothing enforces

Several policies with routes #

Every route of every policy bound to a run applies to that run. Brig refuses four clashes between routes:

  • Two routes with one name.
  • Two routes that set one guest.env name. The gcloud variables that Brig writes for a route with services count as names of that route. See GCP.
  • Two routes that rewrite one guest.git.insteadOf prefix.
  • Two routes with services.

brig policy check refuses each of them:

$ brig policy check claude-code
claude-only
  route anthropic  preset claude-code  mode endpoint
claude-api-key
  route anthropic  preset anthropic-api-key  mode endpoint
brig: the policies bound to claude-code cannot apply together: route anthropic is declared by both claude-only and claude-api-key; a route name is unique across the policies bound to a run

Routes in check #

check prints each route under the policy that declares it, with its preset and its mode. Under each route it prints a row per run path, with the answer for that path and the transport. It ends with the posture the run would get. The route rows and the posture: line go to stderr, so stdout stays one policy name per line:

$ BRIG_HYPERVISOR=hvi brig policy check claude-code
claude-only
  route anthropic  preset claude-code  mode endpoint
    hull on hvi  enforced: hull's gateway answers brig.internal with its own address and diverts port 443 of it to the broker, which serves it with TLS under the brig CA; transport: brig.internal
    hull on vz  cannot enforce: vz takes its network from vmnet, and brig routes brig.internal at the user-mode network gateway that only the hvi backend uses
    ...
posture: isolated

A run with a route needs the isolated posture. The posture: line is that plan.

A route with inject.tls gets a tls row that names its secrets. See Client certificates.

For routes, check asks the runtime and the hypervisor the run would use. Where the run would refuse a route, check exits non-zero with the reason on stderr, and plans no posture. On a hull that is too old to serve routes:

brig: policy claude-only (route anthropic) declares a route in mode endpoint, and brig refuses the run before boot: a policy applies to this sandbox, and hull on hvi cannot enforce the route mode endpoint: `network-gateway` of /opt/homebrew/bin/hull has no --divert. Upgrade hull, or detach the policy. brig will not boot a sandbox under a policy nothing enforces

brig plan and brig run report the same refusal.

Naming a policy #

A policy name uses the same characters as a profile name: lowercase letters, digits, dot, dash and underscore. It must start with a letter or digit.

One rule applies only to policies. YAML reads an unquoted bare word such as no, true or 123 as a boolean or a number. A policy file that says name: no declares the name false. brig policy create refuses such a name:

$ brig policy create no
brig: name "no" reads as false when written unquoted in YAML, not as itself; pick a different name

The verbs #

Verb What it does
brig policy ls Lists every policy that parses, by name and description. For a bound policy, also lists what binds it
brig policy create <name> [--force] Writes a starter document, then opens it: $VISUAL, then $EDITOR, then vi
brig policy edit <name> [--force] Opens an existing policy. Replaces it only if the save still parses and validates. Refuses a rename that orphans anything bound to it, inline or attached, unless --force
brig policy show <name> [--json] Prints the parsed document, with each route's preset expanded
brig policy show --preset <preset> [--json] Prints the route that a preset expands to. See Presets
brig policy rm <name> [--force] Deletes it. Refuses a policy that is bound to anything, inline or attached, unless --force
brig policy attach <policy> <profile> [-n NAME] Binds it to every run of a profile. With -n, binds it to one session by name instead
brig policy detach <policy> <profile> [-n NAME] Reverses an attach
brig policy check <profile> [-n NAME] Lists what is effectively bound to a run of the profile or the -n session, with its routes. Reports whether Brig can enforce anything against it at all

Command lines for all eight verbs:

brig policy ls
brig policy create locked-down
brig policy edit locked-down
brig policy show locked-down --json
brig policy show --preset claude-code
brig policy attach locked-down claude-code
brig policy detach locked-down claude-code
brig policy check claude-code
brig policy rm locked-down --force

A policy is bound in one of three ways: an inline entry in the policy: list of a profile, an attach to a profile, or an attach to one session.

create #

create refuses to overwrite a file at the target path unless you pass --force.

It refuses a name that a different file already declares, with or without --force.

ls #

brig policy ls prints the bindings of a policy under it. A session-level attach prints as <profile> -n <session>:

$ brig policy ls
locked-down     only Anthropic's API and one internal range
                bound to: claude-code, claude-code -n refactor

attach and detach #

attach and detach write to attachments.yaml in the policy directory. They do not write to the policy or the profile.

$ brig policy attach locked-down claude-code
attached locked-down to claude-code
$ brig policy attach locked-down claude-code -n refactor
attached locked-down to claude-code -n refactor

attach refuses, and writes nothing, in three cases:

  • Either name does not exist.
  • The profile is kind: shell or kind: gui, which has no agent to hook an egress rule into.
  • The profile already declares the policy inline in its policy: list.
$ brig policy attach locked-down ubuntu
brig: cannot attach locked-down to ubuntu: ubuntu is kind: shell, which has no agent to hook an egress rule into. Nothing was written

Both attach and check print a note: line on stderr that names the backends that enforce a policy. Example policy shows it, and the other examples on this page leave it out. The word "attached", or a policy name that check prints, does not mean that a rule is in force.

detach reverses attach:

$ brig policy detach locked-down claude-code -n refactor
detached locked-down from claude-code -n refactor

detach refuses a policy that the profile declares inline. To remove that binding, edit the policy: list of the profile. A -n detach is not refused, because an inline entry and a session-level attach are different bindings.

check #

check resolves all bindings (inline, profile-level and session-level) for one profile, or with -n for one session. It lists the policies that apply and runs the same refusal as attach:

$ brig policy check claude-code
locked-down
$ brig policy check ubuntu
no policy applies to ubuntu
brig: cannot enforce any policy on ubuntu: ubuntu is kind: shell, which has no agent to hook an egress rule into

check makes three structural checks:

  • Whether the profile is kind: shell or kind: gui. Neither can enforce a policy.
  • Whether every bound name still resolves to a policy that loaded.
  • Whether the routes of the bound policies can apply together. See Several policies with routes.

For a policy with routes, check also prints the routes and the posture. See Routes in check.

Note For a policy without routes, check does not look at the runtime. It cannot tell you whether this host will boot the run or refuse it. See Enforcement.

--force on rm or on a rename can leave a binding to a name that no policy loads under:

$ brig policy rm locked-down --force
removed /home/you/.config/brig/policies/locked-down.yaml
$ brig policy check claude-code
locked-down (not loaded)
brig: claude-code is bound to locked-down, which no policy loads under -- nothing can enforce what did not load

"Not loaded" means that no file declares that name, or that the file that declares it did not parse. In the second case, Brig names the file and its parse error on stderr.

rm #

With --force, rm removes the file of a bound policy, and each binding then points at nothing:

$ brig policy rm locked-down
brig: locked-down is bound to claude-code. Detach it first, or pass --force to remove it anyway
$ brig policy rm locked-down --force
removed /home/you/.config/brig/policies/locked-down.yaml

The refusal says "detach it" for an attach, and "edit the profile's policy: list" for an inline entry. It says both if a policy is bound both ways.

edit #

edit opens a scratch copy. If the copy parses and validates, Brig replaces the original. A crash or a full disk cannot leave the real file half written. If the copy fails, the original stays unchanged:

$ brig policy edit locked-down
brig: not saved, /home/you/.config/brig/policies/locked-down.yaml is unchanged: cidr "10.0.0/8" is not a valid CIDR: netip.ParsePrefix("10.0.0/8"): ParseAddr("10.0.0"): IPv4 address too short
your edit is still at /tmp/brig-policy-edit-2427992151.yaml

A rename is a change to name:. If the old name is bound to anything, Brig refuses the rename in the same way:

$ brig policy edit locked-down
brig: not saved, /home/you/.config/brig/policies/locked-down.yaml is unchanged: renaming locked-down to totally-new would leave claude-code pointing at a name nothing declares. Detach it first, or pass --force to rename it anyway
your edit is still at /tmp/brig-policy-edit-2427992151.yaml

A save that keeps the same name never triggers this check.

Session bindings #

-n NAME must be the slug form of the session name: lowercase letters, digits, dot, dash and underscore. Brig refuses attach -n Refactor and names the slug to use.

The <agent>@<label> form follows the same slug rule. Brig accepts claude@refactor and refuses claude@Refactor.

The slug names the sandbox and the workspace, keys the session index, and selects the policy.

brig policy check -n reads the name the same way, so it reports what the run gets. Unlike attach -n, it accepts a name that is not a slug. A hand edit or an earlier build can leave such a key, and brig policy ls prints it. check reports a row under that key and says that no run reaches it:

$ brig policy check claude-code -n "My Work"
brig: no-net is recorded under "My Work", which no run reaches
  ↳ a session named "My Work" starts "my-work"
  → to remove it:  brig policy detach no-net claude-code -n "My Work"
no-net

One gap remains. attach -n refuses a name that any reserved profile ends in. A session is refused only a name that is reserved for its agent. claude@desktop therefore opens an ordinary session. Brig refuses brig policy attach locked-down claude-code -n desktop, because the name collides with claude-desktop. You cannot bind a policy to that one session.

Sessions named with --name

v0.5.0 removed brig run --name. A session opened before that with brig run claude --name Refactor has the slug refactor for its sandbox and its workspace, and Brig looks up the policy under that slug. brig policy attach locked-down claude-code -n refactor covers the session, whichever way you named it.

A worked example #

Start from nothing:

$ brig policy ls
no policies yet; your own live in /home/you/.config/brig/policies
brig policy create <name> writes a starter one

Create a policy. The starter opens in your editor. In this example, the starter is already filled in:

$ brig policy create locked-down
/home/you/.config/brig/policies/locked-down.yaml created
$ brig policy ls
locked-down     only Anthropic's API and one internal range

Show it, as YAML or as JSON:

$ brig policy show locked-down
apiVersion: brig.sh/v1alpha1
kind: Policy
metadata:
  description: only Anthropic's API and one internal range
  name: locked-down
spec:
  egress:
    allow:
    - host: api.anthropic.com
    - cidr: 10.0.0.0/8
    default: deny
$ brig policy show locked-down --json
{
  "apiVersion": "brig.sh/v1alpha1",
  "kind": "Policy",
  "metadata": {
    "name": "locked-down",
    "description": "only Anthropic's API and one internal range"
  },
  "spec": {
    "egress": {
      "default": "deny",
      "allow": [
        { "host": "api.anthropic.com" },
        { "cidr": "10.0.0.0/8" }
      ]
    }
  }
}

show prints the parsed document and not the file verbatim. The YAML output has sorted keys, so the field order differs from the file. A policy in the flat form is printed in the envelope form.

Edit it, and remove it:

$ brig policy edit locked-down
/home/you/.config/brig/policies/locked-down.yaml updated
$ brig policy rm locked-down
removed /home/you/.config/brig/policies/locked-down.yaml

Common errors #

What Brig says What happened
unknown policy "x". `brig policy ls` lists them show, edit or rm on a name that is not there
name "x" may use only lowercase letters, digits, dot, dash and underscore, and must start with a letter or digit See Naming a policy
name "x" reads as false when written unquoted in YAML, not as itself; pick a different name The name is a bare YAML boolean, null or number word. See Naming a policy
<path> already exists. Edit it directly with `brig policy edit x`, or pass --force to replace it with a fresh starter create on a name whose file is already there
policy "x" already exists, declared in <path>. Edit it directly with `brig policy edit x`, or remove that file first create on a name a different file already declares. --force does not help here
a rule needs host: or cidr: A rule in allow: or deny: named neither
a rule takes host: or cidr:, not both … A rule named both
cidr "x" is not a valid CIDR: … A typo in a cidr: value, such as a missing octet
host "x" contains whitespace or a control character A host: value that cannot be a domain or glob under any grammar
apiVersion is required, and must be "brig.sh/v1alpha1" A document with no apiVersion:, or the wrong one
kind is required, and must be "Policy" A document with kind: and no value. A document with no kind: key is read as the flat form
unknown field "Spec" A key that is not the exact name of a field, such as Spec or a lookalike letter
the file holds more than one YAML document; one file is one document A second document after ---
route x: mode: name "…" may use only lowercase letters, … A route's mode is not a name
policy x (route y) declares a route in mode m, and brig refuses the run before boot: … route mode m is not part of this build of brig. … check on a profile bound to a route in a mode this build does not serve. A run, sh or plan refuses it the same way, and exits 7
route x: guest.env NAME is a literal; a value is {route.url}, {session.token} or {route.region}, never a literal A guest.env value that is not a placeholder. The error leaves the value out
route x: upstream "…" has a path; write the bare origin, https://host[:port] An upstream with a path, a query or a fragment, or not in canonical form
route x: inject.headers.set names NAME, which inject.headers.remove drops first; … A header named in both set and remove
route x: … names Host, which the broker sets itself A header list names a header that the broker owns
route x: preset claude-code keeps its credential fresh (anthropic-oauth) … A route changes the upstream or credential.field of a preset that refreshes its credential
route x: inject takes headers.set or basicAuth, not both A route, or a route and its preset, set both
route x: credential.lifecycle is set by a preset, and a policy does not name it A policy names credential.lifecycle
route x is declared by both a and b; … Two bound policies declare a route of the same name. See Several policies with routes
guest.env NAME is set by route x of a and by route y of b; … Two bound routes set the same guest.env name, or a route sets a gcloud variable that Brig writes for a route with services
guest.env NAME is set by route x of a; brig writes the gcloud endpoint overrides for route y of b A route sets a CLOUDSDK_API_ENDPOINT_OVERRIDES_ variable while a route with services is bound
guest.env NAME: brig writes the gcloud endpoint overrides itself A gcp route sets a CLOUDSDK_API_ENDPOINT_OVERRIDES_ variable in its own guest.env
guest.env CLOUDSDK_CORE_CUSTOM_CA_CERTS_FILE: brig writes the gcloud CA variable itself A gcp route sets the gcloud CA variable in its own guest.env
guest.git.insteadOf PREFIX is rewritten by route x of a and by route y of b; … Two bound routes rewrite the same git prefix
policy x (route y) declares a route in mode endpoint, which the guest reaches at brig.internal: … A run, sh or plan with routes on hull's vz or qemu backend, on docker, or on a hull too old to serve routes. It exits 7
policy x (route y) declares a route in mode endpoint, and brig refuses the run before boot: … check on a profile bound to such a route
policy x (route y) declares routes, and this run has no network (BRIG_NETWORK=none) to reach them on; … A run with routes and the offline posture
policy x (route y) injects a secret that brig's secret store does not hold: missing secret "s" … A run or sh with a route whose secret is not in the store. It exits 6, and the message names the command that stores it
policy x (route y) injects s, which the broker reads from brig's secret store on the host, and the store is not available: … The same, on a host whose store does not open, such as Linux with no Secret Service. It exits 6
could not register the routes of brig-x with the credential broker: … brig-broker is not installed, did not start, or refused the routes. ~/.brig/host/broker/broker.log says why
… another process holds the credential broker's port, 127.0.0.1:N, so brig refuses the run. … Another process listens on the broker's port. brig doctor names it
not saved, <path> is unchanged: … The save from edit did not parse or validate, or it renamed a bound policy without --force. The real file is untouched. The error names where your edit still is
unknown profile "x". `brig agent ls` lists them attach, detach or check naming a profile that is not there
cannot attach x to y: y is kind: shell, which has no agent to hook an egress rule into. Nothing was written attach to a kind: shell or kind: gui profile
cannot enforce any policy on x: x is kind: shell, which has no agent to hook an egress rule into check on a kind: shell or kind: gui profile
x is bound to y, which no policy loads under -- nothing can enforce what did not load check on a profile bound to a name nothing loads under. Either --force on rm or a rename left no policy behind it, or the file that declares it did not parse (named separately on stderr)
x is already declared inline in y's policy: list, which binds every run already. Nothing was written attach naming a policy the profile's own policy: list already declares
x is declared inline in y's policy: list, not attached; edit the profile directly to remove it detach naming a policy the profile's own policy: list declares, without -n
x is bound to y. Detach it first, or pass --force to remove it anyway rm on a policy attached to a profile or a session. A policy declared only inline says "edit the profile's policy: list" instead
a policy applies to this sandbox, and hull on vz cannot enforce the egress policy: … A policy on a run path whose answer is cannot enforce: hull's vz or qemu backend, or docker. See Enforcement
a policy applies to this sandbox, and whether nerdctl on <shim> enforces the egress policy is unknown: brig cannot find the network namespace of the container network: … On Linux: rootless containerd is not running, XDG_RUNTIME_DIR is not set, or nsenter is not installed
… is unknown: brig puts the sandbox's rules in place with nftables: nft is not installed nft is not installed
… is unknown: the probe `<nsenter …> /usr/sbin/nft list tables` failed: … nft ran and failed, for instance on a kernel without nftables
… is unknown: brig could not start the egress resolver: … The resolver cannot install its rules or bind the bridge address. The error quotes its log
… is unknown: the sandbox's bridge is not where brig put the rules: … BRIG_RUNTIME_BIN reaches a containerd other than the rootless one Brig found. Brig removes the container
a policy applies to this sandbox, and whether nerdctl on <shim> enforces the route mode endpoint is unknown: … A run with routes and no egress policy, whose brig.internal routing Brig did not put in place. The reasons are those of the egress rows above
<sandbox> is already running, so brig leaves its egress rules alone Another brig booted the sandbox between this one's check and its boot. Run the command again
a policy applies to this sandbox, and nerdctl on <shim> cannot enforce the egress policy: its rules need a network of its own, and the run asks for the shared network A run reached nerdctl with a policy and the shared posture, which a policy normally narrows to isolated. Run it with --network isolated. It exits 7
a policy applies to this sandbox, and hull on hvi cannot enforce the egress policy: the network-gateway of <bin> has no --egress-default. Upgrade the runtime, or detach the policy hull is too old to enforce a policy. Upgrade it
a policy applies to this sandbox, and whether hull on hvi enforces the egress policy is unknown: the probe `<bin> network-gateway --help` failed: … Brig did not get an answer from the hull binary: it did not run, exited non-zero, or gave no answer within 30 seconds
a policy applies to this sandbox, and whether hull on krun enforces the egress policy is unknown: brig holds no answer for this run path. Run it on hull's hvi backend (BRIG_HYPERVISOR=hvi), or detach the policy BRIG_HYPERVISOR names a backend Brig holds no record for, such as krun. Brig refuses the run

Default egress #

With no policy attached, a sandbox has open internet access, so the agent reaches its API with no setup. No profile that Brig ships binds a policy, so brig run <agent> on a fresh install filters nothing. The default isolated posture does not filter outbound traffic either. To limit it, attach a policy.

No policy and a deny default are different cases:

What you do Result
Attach no policy No filtering
Attach a policy whose default: is deny Everything is refused except what its allow list names. With an empty allow list, the sandbox has no way out

Enforcement #

Brig holds one answer for each run path, which is a runtime with one backend. The answer is enforced, cannot enforce or unknown. On hvi and on Linux, a check at boot confirms the answer or overturns it.

Run path Egress policy Why What the host needs
hull on hvi (macOS) enforced The rules apply at the network gateway of the sandbox, its only way out macOS 15 or newer, and a hull recent enough to enforce a policy
nerdctl (Linux), on any shim enforced Brig applies the rules on the sandbox's own network, and answers its DNS nft (the nftables package) and nsenter (util-linux)
hull on vz cannot enforce Brig does not filter the network of vz
hull on qemu cannot enforce Brig does not filter the network of qemu
docker, on any shim cannot enforce Brig does not filter docker's network
hull on any other backend unknown Brig holds no answer for it

Enforcement on Linux is measured on rootless nerdctl. Brig treats nerdctl as rootful when Brig runs as root, and that case is not measured.

Run Result
A policy, on an enforced run path Brig boots the sandbox
A policy, on a cannot enforce or unknown run path Brig refuses the boot with exit code 7. The refusal names the property, the runtime and the backend. vz, qemu and docker also name the backend that enforces
A policy without routes, with --network offline, on any run path Brig does not refuse the run. A sandbox with no route out satisfies every rule set
No policy Brig asks nothing of the run path

Brig makes this check before anything starts. It makes the check again when it finds the sandbox already running, so a running sandbox does not bypass it.

Warning Every runtime that Brig ships refuses a policy it cannot enforce. This guarantee covers the runtimes that Brig ships today. It is not a property of the interface. A runtime that never answers the question is never asked, and is not refused.

On hvi #

On the hvi backend, Brig puts the rules of every policy bound to the run on the network gateway of that sandbox, which is its only way out.

A measurement in a real guest gave three results. An allowed name is reachable, a denied name does not resolve, and an address dialled directly does not connect. See the egress policy test record.

Brig refuses a hull that is too old to enforce the rules:

$ brig policy attach locked-down claude-code
attached locked-down to claude-code
$ brig run claude
brig: a policy applies to this sandbox, and hull on hvi cannot enforce the egress policy: the network-gateway of /opt/homebrew/bin/hull has no --egress-default. Upgrade the runtime, or detach the policy. brig will not boot a sandbox under a policy nothing enforces

If Brig cannot check the hull binary, the answer is unknown and Brig refuses the boot. The refusal names the binary and the error.

On Linux #

On Linux, Brig enforces a policy itself. A sandbox under a policy always has its own network. Before it boots, Brig puts a DNS resolver and nftables rules on the bridge of that network. If nft or nsenter is missing or fails, Brig refuses the boot with exit code 7.

Policy default What the resolver does
default: deny Answers only names that an allow glob covers. The guest can connect to an address that it resolved there for two minutes
default: allow Answers every name. The guest cannot connect to the addresses of a name that a deny glob covers

The rules limit what leaves the sandbox:

  • They refuse a connection to an address that no rule allows. TCP gets a reset, and anything else is dropped.
  • They carry TCP, UDP and ping, and refuse every other protocol.
  • They refuse IPv6 and 169.254.0.0/16. On a run with an aws route, port 80 of 169.254.170.2 goes to the broker, and the rest of that range stays refused. See Routing brig.internal.
  • DNS for any server other than Brig's resolver is ordinary traffic under the policy, as on hvi.
nerdctl Host addresses
rootless The rules treat them like any other address
rootful Every address of the host is refused under either default

A rule means the same on Linux and on hvi. Ping differs. On Linux, it reaches an address that the rules allow and no other. On hvi, the gateway answers every ping itself.

While the sandbox runs, brig stop and brig rm remove the rules only after the sandbox is confirmed stopped. A stop that failed leaves them in place. A connection left from an earlier boot is judged again under the new rules.

Failure Result
Something removes the rules, such as a flush ruleset on a rootful host The sandbox is not filtered for up to 5 seconds, until the resolver installs the rules again. Under default: deny, the addresses that the guest looked up before are refused until it asks for them again
The resolver dies Within 15 seconds, every new connection is refused under either default. Connections that are already open stay open. The next brig run or brig sh reboots the sandbox
The resolver and the rules are both gone The sandbox is not filtered until the next brig run or brig sh reboots it

The resolver logs refused names to ~/.brig/egress/<sandbox>.log, or under BRIG_GATEWAY_DIR when that is set. The log starts afresh at each boot, and brig stop removes it. It logs a refused name at most once every 30 seconds, at most 20 such lines every 30 seconds, and at most 4 MiB in all. A refused connection is not logged.

Routing brig.internal #

A sandbox on Linux reaches its routes at brig.internal. A run with a route takes the isolated posture. A sandbox with routes and no policy gets the same resolver and rules, which then filter nothing else.

The resolver answers brig.internal with the bridge address, under any policy. A connection to port 443 of that address goes to the broker. On a run with an aws route, a connection to port 80 of 169.254.170.2 goes to the broker too. Under a policy with a default, every other address and port of 169.254.0.0/16 stays refused. Every other port of the bridge address is refused, except DNS. The bytes pass to the broker unchanged, and are never logged.

Failure Result
The run is not isolated, or it runs on docker Brig refuses the run
The broker is not running, or refuses the connection The guest's connection is reset
256 connections are already open The new connection is reset
The resolver dies The guest's connection is refused

Binding properties #

The rules are fixed when the sandbox boots. An edit to a policy changes what the next boot enforces. A sandbox that is up when the rules change does not continue under the old rules. Brig detects the mismatch, then stops, removes and reboots the sandbox. It warns that any other session on the sandbox will be disconnected.

A policy takes the network posture with it. Rules cover every sandbox on one network, so a sandbox with its own rules runs isolated, as Postures and policies describes. The NETWORK row of brig info shows the isolated posture. The forced posture only narrows what was asked for.

Several policies at once are unioned. A rule in any bound policy is a rule of the run. The default is the strictest that any policy names: one deny makes the run deny-by-default. A host that the second policy allows is reachable even when the first policy alone denies it. The deny priority in Limits applies across the whole set.

Limits #

attach and check do not inspect the rules in a policy. They refuse a kind: shell or kind: gui profile, and a name bound to nothing. They cannot tell you that an allow glob matches nothing you intended. They tell you only that the document parses.

Rule priority. Brig applies no priority when it merges policies. It concatenates the allow and deny lists from every bound policy. deny takes priority over allow and over default. On hvi, the gateway applies that order. On Linux, Brig's rules do.

What was measured. Two manual test records cover enforcement:

Record Guest Covers Does not cover
Egress policy on hvi A real guest on hvi A default: deny policy with one host allow A deny rule that overrides an allow rule, and a default: allow policy
Egress policy on Linux A urunc guest on rootless nerdctl The network conformance cases under both defaults, including a deny glob inside an allow glob and a deny cidr inside an allow cidr

Host rules. A host rule is enforced through the resolver in front of the sandbox: the gateway's on hvi, and Brig's own on Linux. The coverage of the rule depends on the default.

Policy default What a host rule covers
default: deny The resolver answers only names an allow glob covers. The guest reaches nothing it did not resolve there. Traffic sent straight to an address, DNS over HTTPS and DNS over TLS do not get out
default: allow A host deny is best effort, because traffic sent straight to an address never asks for a name

A cidr rule is matched on the address with either default.

A host rule decides an address, not a name. Neither enforcer reads TLS SNI or an HTTP Host header. Two names served from one address, as on a CDN, get the same verdict. An allow for one name lets the guest reach the other, and a deny for one refuses the other.

Type a command, a flag or an error message.