Guides

Authentication

An agent gets its credentials in one of three ways. Guest git access to GitHub over HTTPS is a separate setting.

You need Brig installed (Install) and a shipped agent, such as claude-code.

Agents and profiles #

An agent is the CLI surface you run: brig run claude, a session. A profile is the file that declares credentials: brig secret import claude-code.

A built-in agent and its profile share one name. A profile has no session, and brig secret import takes no @label.

Credential methods #

Log in inside the guest #

This is the default:

brig run claude ~/code/demo

Claude Code prompts for a login. Complete the login inside the guest.

Whether the login survives brig stop depends on the profile:

Missing secret warnings #

claude-code declares two secrets, claude-credentials and gh-token. Both are optional, so the sandbox boots without them. brig info claude prints the same warnings as a run, and boots nothing:

$ 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

In a log or a pipe, every line starts with brig:.

That run exits 0. Only a required secret stops a run before the sandbox exists. None of the eight built-in profiles declares one.

Import a host login #

An imported login survives brig stop:

brig secret import claude-code

claude-code and claude-desktop fill claude-credentials from the first of two places on your host:

1. The macOS keychain's Claude Code-credentials generic-password item.
2. The file ~/.claude/.credentials.json.

Neither profile declares a source for gh-token. Create it with brig secret create gh-token, or export it. See Git access.

The other six shipped profiles declare no secrets:: codex, cursor, gemini, grok, opencode, ubuntu. For them, import has nothing to read on your host. The command prints <profile> declares no secrets, so there is nothing to import and exits 0, on any host, without opening the secret store.

Secrets has the import flags and rules.

Sessions that stop authenticating #

Warning If a long claude-code session stops authenticating, log in on the host again. Then run brig secret import claude-code again.

Brig re-delivers the stored claude-credentials document on every command that reaches the sandbox: run, sh and exec.

Measured on 2026-08-19 against a live account:

• Claude Code refreshes that document in place.
• Anthropic rotates the refresh token single-use.
• A refresh inside the guest invalidates the host copy.
• The next Brig command re-delivers the dead stored document over the guest's fresh one.

This can change with either the agent or the provider.

Environment keys #

Some agents read a credential from your environment. Export the variable before you run:

export GEMINI_API_KEY=<key>
brig run gemini ~/code/demo

Brig reads the key on every run. It does not store a copy.

Refused variables #

Some profiles refuse a provider key from your environment. A forwarded key moves the sandbox off your subscription and onto metered billing.

Secrets has the message Brig prints.

Git access #

Guest git over HTTPS is off by default. Turn it on with BRIG_GIT_CONFIG=1:

BRIG_GIT_CONFIG=1 brig run claude ~/code/demo

brig info reports the setting:

$ brig info claude
...
brig: guest git over HTTPS: off (BRIG_GIT_CONFIG=1 to enable)

GH_TOKEN is for git over HTTPS inside the guest. It does not authenticate the agent to its provider.

If the setting is on, Brig regenerates a credential helper and a managed gitconfig inside the guest on every run. The helper reads GH_TOKEN when git asks for a credential. If the variable is unset, the helper does nothing. Git then reports an authentication error, and does not fail on an empty password.

GH_TOKEN reaches the guest differently by profile:

Secrets is the reference for the secret store. To change any of this for an agent of your own, see Profiles.