Guides
Authentication
On this page
An agent in a sandbox starts with no login. This page covers three separate needs:
- The agent's login to its provider, such as Anthropic or Google.
- Git access to GitHub over HTTPS. See Git access.
- Access to other services, such as a cloud API. See Credential broker.
Credential methods #
| Your goal | Method | Profiles |
|---|---|---|
| A first run with no setup | Log in inside the guest | all |
| Start logged in with the login you already have on this host | Import a host login | claude-code, claude-desktop, herdr |
| Use an API key from your shell, a CI job or a secret manager | Environment keys | cursor, gemini, grok, opencode |
| Keep the login on the host, out of the guest | Keep the login on the host | claude-code, or any profile with a route |
brig info <ref> shows which credentials a run gets, by name, and boots nothing. A secret is a value in Brig's own secret store: the macOS keychain, or a Secret Service keyring on Linux. See Secrets.
A built-in agent and its profile share one name. Commands that take a profile, such as brig secret import claude-code, take no @label.
Log in inside the guest #
This is the default:
brig run claude ~/code/demoClaude Code asks for a login. Complete it inside the guest, as on a new machine.
| Profile | Where the login is stored | After brig stop |
|---|---|---|
claude-code, herdr |
A memory-backed mount | Lost. The next brig run asks again. |
claude-desktop, codex, cursor, gemini, grok, opencode |
The guest home, on host disk | Kept, until brig rm deletes a guest home Brig created. |
For claude-code, the login never reaches host disk. codex signs in with codex login --device-auth inside the guest.
Missing secret warnings #
claude-code declares two optional secrets, claude-credentials and gh-token. A run without them prints a warning and continues:
$ brig info claude
brig: claude-code runs without 2 secrets
○ claude-credentials → brig secret import claude-code
↳ run `claude` on the host once to log in
○ gh-token → brig secret create gh-token
↳ export GH_TOKEN before running brig, or store one: gh auth token | brig secret create gh-token○ marks a secret with no value, → the command that gives it one, and ↳ a note. In a log or a pipe, every line starts with brig:.
Only a required secret stops a run before the sandbox exists. No built-in profile declares one.
Import a host login #
Log in to Claude Code on this host first. Then copy that login into Brig's secret store:
brig secret import claude-codeimport copies the Claude Code login from the macOS keychain, or from ~/.claude/.credentials.json, and stores it as claude-credentials. claude-desktop and herdr use the same login. Brig then gives the login to the guest on every run and sh, so the sandbox starts logged in, also after a stop.
To check the result, run brig info claude. The guest login: line names the stored secret and where it was imported from.
The other profiles declare no secrets. For them, import prints <profile> declares no secrets, so there is nothing to import and exits 0.
Secrets has the import flags.
Sessions that stop authenticating #
Warning If a long
claude-codesession stops authenticating, log in on the host again. Then runbrig secret import claude-codeagain.
Claude Code refreshes its login inside the guest, and Anthropic accepts each refresh token once. A refresh in the guest makes the stored copy invalid, and the next Brig command writes that invalid copy over the fresh one in the guest. This can change with the agent or the provider.
A claude-code route avoids this. The broker refreshes the login on the host, and the guest never holds the refresh token.
Environment keys #
export GEMINI_API_KEY=<key>
brig run gemini ~/code/demoBrig reads the key from your environment on every run and stores no copy.
| Profile | Variable it forwards |
|---|---|
cursor |
CURSOR_API_KEY |
gemini |
GEMINI_API_KEY |
grok |
XAI_API_KEY |
opencode |
OPENROUTER_API_KEY |
Refused variables #
Some profiles refuse a provider key from your environment, because the key would move the agent from your subscription to metered API billing.
| Profile | Never forwarded |
|---|---|
claude-code, claude-desktop, herdr |
ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN |
codex |
OPENAI_API_KEY |
To forward one anyway, change the profile's deny list. See Profiles.
Keep the login on the host #
A route of the credential broker keeps the credential on the host. The guest gets a session token that works only through the broker, and brig stop or brig rm revokes it. For Claude Code, import the login as above, then bind a policy with a claude-code route. Credential broker has the complete example.
Routes work on Linux, and on macOS with the hvi backend. A route on the aws preset is the exception to "the credential stays on the host": it gives the guest temporary AWS keys.
Git access #
BRIG_GIT_CONFIG=1 brig run claude ~/code/demoBRIG_GIT_CONFIG=1 turns on git over HTTPS in the guest. It is off by default. A token in GH_TOKEN is for git only. It does not log the agent in to its provider.
With the setting on, git in the guest uses GH_TOKEN for HTTPS. If no token reaches the guest, git reports its own authentication error.
| Profile | Source of GH_TOKEN |
|---|---|
claude-code, claude-desktop, herdr |
Your exported GH_TOKEN if you set one, then a stored gh-token secret |
| The other six | Your exported GH_TOKEN only |
To store the token once:
gh auth token | brig secret create gh-tokenTo check the setting, run brig info claude. It prints guest git over HTTPS: on or off, and its CREDENTIALS row names GH_TOKEN when a value reaches the guest.
The agent can use the token for as long as the sandbox holds it, so give it a token limited to the repositories the agent needs.