Guides
Secrets
On this page
brig secret manages Brig's secret store: it puts credentials into the store, reads them back, and imports a login from your host.
The secret store #
A run reads no other store. A profile declares the names it wants under secrets:. The values in the store under those names reach the sandbox. A value arrives as a file where the agent reads one, and as an environment variable otherwise.
For claude, log in inside the sandbox or import your host login:
brig run claude # log in inside the sandbox, or:
brig secret import claude # carry your host login in, onceA claude login made inside the sandbox is gone after brig stop. An imported login survives a stop. To choose a login path, see Authentication.
For what the keychain does and does not protect, see Security model.
External secret managers #
With 1Password, Vault or pass, pipe the value in once:
op read ... | brig secret create <name>
brig secret import <profile> <name> --from-command 'op read ...'Or keep the value in the environment. An env.<name> binding reads Brig's environment on every run. So <your secret manager's run-with-env command> -- brig run claude works for the variables a profile binds that way.
Commands #
| Command | What it does |
|---|---|
brig secret create <name> [--type tls|ca] |
Stores a new secret. Refuses if the name is taken. --type checks the value first. |
brig secret read <name> |
Prints the value. |
brig secret update <name> [--type tls|ca] |
Replaces an existing value. Refuses if the name is not there. --type checks the value first. |
brig secret delete <name> |
Removes the secret, after asking. -y answers in advance. |
brig secret ls |
Lists names, dates and where each value came from. Never values. |
brig secret import <profile> |
Fills that profile's secrets from your host, once. |
create and update never take the value as an argument. See Value input.
v0.5.0 removed rm and list, the old spellings of delete and ls. Brig refuses each as a usage error that names its replacement. Migration lists the removed spellings.
Create and update #
If create or update refuses a name, the message names the command to use:
$ printf %s "$TOKEN" | brig secret create gh-token
$ printf %s "$TOKEN" | brig secret create gh-token
brig: a secret named "gh-token" already exists. To replace it: brig secret update gh-token
$ printf %s "$TOKEN" | brig secret update gh-tokne
brig: no secret named "gh-tokne". To create it: brig secret create gh-tokneA successful write prints nothing.
Brig reads back what it wrote and compares the bytes. A create that does not match is removed. An update that does not match only reports the mismatch, because the previous value is already gone.
List secrets #
ls prints three columns:
$ brig secret ls
NAME UPDATED FROM
claude-credentials 2026-08-18 12:31 keychain:Claude Code-credentials
deploy-key 2026-08-15 21:09 -
gh-token 2026-08-15 21:09 ---json prints the same data, one object per secret. It leaves out any field a secret does not have:
$ brig secret ls --json
{
"apiVersion": "brig.sh/v1alpha1",
"kind": "SecretList",
"data": []
}ls reads no value, so it raises no access prompt.
| Column | Meaning | When it is missing |
|---|---|---|
UPDATED |
When the value last changed. | If the store cannot supply a date, text shows - and JSON omits modified. |
FROM |
Provenance: where brig secret import read the value. |
Text shows -, and JSON omits provenance. Brig did not put the value there. You created it by hand. |
A --from-command value shows command in FROM. Brig does not record the command line, because it can hold a credential.
An empty store is not an error:
$ brig secret ls
no secrets yet. To add one: brig secret create <name>Expiry warnings #
If the profile declares an expiryField:, provenance also carries the expiry of the credential. Before boot, a run warns that a stored copy has expired:
brig: the imported credential <name> (<profile>) expired 3h ago
→ renew it on the host, then: brig secret import <profile>A secret with no sources:, filled with --from-command, gets a different second line. The profile-wide import cannot refill it:
renew it, then store it again: brig secret import <profile> <name> --from-command '<command>'A certificate stored with --type tls gets a warning within three days of its expiry, and once it has expired. A certificate stored without --type gets no warning. The warning comes once per brig plan, and once when brig run or brig sh starts or attaches to a sandbox:
brig: the client certificate <name> (route <route>) expires in <time>
→ store the renewed certificate, then: brig secret update <name> --type tlsWhen several routes present the same secret, the line names all of them. A plain brig secret update <name> without --type tls clears the recorded expiry, and the warning stops. Store the renewed copy with --type tls to keep it.
Delete a secret #
delete asks first. Brig keeps no copy of a deleted value, and the keychain keeps no history.
$ brig secret delete gh-token
brig: delete "gh-token"? The value cannot be recovered [y/N] y
deleted gh-tokendelete also removes the secret's renewal journal, which can hold a renewed copy of the value. It also removes a journal whose secret is already gone, and says deleted the renewal journal <name>.journal.
If there is no terminal to ask on, delete refuses:
$ echo | brig secret delete gh-token
brig: deleting "gh-token" cannot be undone, and there is no terminal to ask on. Pass -y to answer in advance: brig secret delete gh-token -yA worked example #
This example stores a GitHub token, uses it, rotates it and removes it.
Store the token. printf %s stores no newline, and the pipe keeps the value out of your shell history:
$ printf %s 'ghp_16C7e42F292c6912E7710c838347Ae178B4a' | brig secret create gh-token
$ brig secret ls
NAME UPDATED FROM
gh-token 2026-08-15 21:09 -Use it. claude-code declares gh-token, so a secret stored under that name needs no other setup:
$ brig info claude-code
...
brig: forwarding to guest:
brig: IS_SANDBOX
brig: CLAUDE_CONFIG_DIR
brig: GH_TOKEN(secret)
brig: never forwarded for claude-code: ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN (they would move this sandbox onto metered billing)(secret) means that the value came from Brig's store and not from your shell. brig info reports the forwarding, and brig run claude-code does it.
Warning The denylist in the last line covers environment forwarding only. It does not check a
files:binding. It does not stop an agent that reads a credential inside the guest from sending it over the network. See Security model.
An exported GH_TOKEN wins over the stored value, so GH_TOKEN=$(gh auth token) brig run claude-code works. The stored value is the fallback for a shell that exports nothing. See Git access.
Rotate it:
$ printf %s 'ghp_9a1FfE0d5B7c4A2e8D3b6C1a0F5e9D8c7B6a' | brig secret update gh-tokenBrig re-reads what it hands the guest on every exec. The next command gets the new value, and the sandbox does not need a restart.
Remove it:
$ brig secret delete gh-token
brig: delete "gh-token"? The value cannot be recovered [y/N] y
deleted gh-token
$ brig secret ls
no secrets yet. To add one: brig secret create <name>Import from your host #
brig secret import <profile> copies that profile's credentials from your host into Brig's store:
$ brig secret import claude-code
claude-code: importing 1 secret
claude-credentials: stored from keychain:Claude Code-credentials, expires 2026-08-19 01:31
gh-token: no source on your host, so it is one you supply: brig secret create gh-token
note: claude-desktop also declares claude-credentials, so this fills it there tooEach secret in a profile carries a sources: list, and the first source that exists wins. brig agent ls shows which names a profile can import and which it cannot. Profiles covers how to declare sources in a profile of your own.
| Flag or argument | What it does |
|---|---|
--dry-run |
Previews the action. It reads the sources to check them, and writes nothing. |
-y |
Replaces a value Brig did not write, without asking. |
--from-command '<sh>' |
Takes one named secret's value from a command's stdout, not from its declared sources. |
[name...] after the profile |
Narrows the import to the names you list. |
--aws-profile <p> |
For a secret whose source is aws: the AWS profile on your host that the sandbox's keys come from. See An AWS profile behind a route. |
--role-arn <arn> |
With --aws-profile: the sandbox assumes this role. The recommended mode. |
--identity self |
With --aws-profile or --gcloud-configuration: the sandbox gets your own identity. |
--source-identity <id> |
With --role-arn: the source identity of the role session, in place of the one Brig reads from the profile. |
--session-duration <d> |
With --role-arn: the lifetime of the role session, 25m to 1h. Default 30m. |
--gcloud-configuration <c> |
For a secret whose source is gcloud: the gcloud configuration on your host that the sandbox's tokens come from. See A gcloud login behind a route. |
--impersonate-service-account <email> |
With --gcloud-configuration: the sandbox acts as this service account. The recommended mode. |
The argument to import is a profile. If you give it a secret name, Brig names the profile to use:
$ brig secret import claude-credentials
brig: "claude-credentials" is a secret, not a profile, and import takes the profile that declares it: brig secret import claude-code claude-credentialsImport rules #
Import reads your host's credential stores once, when you run it. A later run reads only Brig's own copy, so only import raises an approval dialog. The aws and gcloud sources are the exceptions. Each time brig-broker fetches keys or mints a token, it runs the host's aws or gcloud CLI, which reads your login.
The copy does not track its source. If you renew the login on the host, the copy does not change. If you log out on the host, the copy stays valid. To refresh the copy, import again. To remove it for good, use brig secret delete.
Import does not replace a value Brig did not write. A secret with no provenance is one you created by hand. Import stops, because it cannot recover the value that the import replaces:
$ brig secret import claude-code
brig: "claude-credentials" is already stored and brig did not put it there, so importing would replace a value you supplied. To replace it: brig secret import claude-code claude-credentials -yImport skips an unchanged value. UPDATED then still shows when the value last changed, and not when an import last ran.
Exit status #
| Case | Exit status |
|---|---|
| A secret that has an importer is not filled: the source gave nothing, or reading it failed | Non-zero |
| A name has no importer at all | Informational. It does not fail the command. |
brig secret import x && brig run x works for a profile that mixes imported and hand-created secrets.
Note On a machine that has never run the agent, there is nothing to import and the command exits non-zero. That state is normal.
Large credential documents #
Brig stores a credential document of several kilobytes the same way as a token. Examples are Claude Code's document after plugins add their MCP OAuth state, and codex's ~/.codex/auth.json. The only limit is the 65536-byte cap in Value input.
Value input #
The value is never an argument. That keeps it out of ps and out of your shell history. It comes from stdin or from a file:
| Source | What gets stored |
|---|---|
stdin, the default (--stdin spells it out) |
The bytes, less one trailing line ending |
-f FILE |
The file's bytes, verbatim |
-f - |
stdin, spelled out. Same stripping as stdin. |
-f more than once |
The files appended in the order given, with a line break between two when the first does not end in one. A - among them is stdin. |
The two most common commands:
printf %s "$TOKEN" | brig secret create gh-token
brig secret create deploy-key -f ~/.ssh/id_ed25519Trailing newlines #
echo adds a newline that is not part of the secret, and Brig strips it:
$ echo tok | brig secret create with-echo
$ brig secret read with-echo | xxd
00000000: 746f 6b tokThe store holds three bytes. A trailing newline inside an Authorization: header fails in a way that reads like a bad token. CRLF counts as one line ending.
Brig stores a file as it is. A PEM key's final newline belongs to the key:
$ printf 'tok\n' > tok.txt
$ brig secret create from-file -f tok.txt
$ brig secret read from-file | xxd
00000000: 746f 6b0a tok.The store holds four bytes. For exact bytes from stdin, use printf %s. There is no flag for it:
$ printf %s 'tok' | brig secret create exact
$ brig secret read exact | xxd
00000000: 746f 6b tokSize cap #
Each source has a cap of 65536 bytes. create and update refuse a longer value before it reaches the store:
$ brig secret create x < /dev/zero
brig: the value on stdin is over 65536 bytes, which is larger than any secret brig can store. If that is a file or a stream rather than a credential, this is the wrong oneThe cap stops streams. No credential comes near it.
Certificates and CA bundles #
With --type tls or --type ca, Brig checks the value before it stores it. A value that fails the check is refused, and nothing is written. These secrets are for a route's client certificate.
A PKI hands out a client certificate in one of two layouts, and both work:
# one bundle: the certificate, its chain and the key in one file
brig secret create inventory-client --type tls -f bundle.pem
# separate files, appended in any order
brig secret create inventory-client --type tls -f client.crt -f client.key -f ca.crt
cat client.crt intermediate.crt client.key | brig secret create inventory-client --type tls
brig secret create example-root-ca --type ca -f root-ca.pemA tls value holds CERTIFICATE blocks and exactly one private key block, PRIVATE KEY, RSA PRIVATE KEY or EC PRIVATE KEY, in any order. Text outside the blocks, such as the Bag Attributes lines of openssl pkcs12, is ignored. Brig reads it in four steps:
- The leaf is the one certificate whose public key matches the key. A certificate that appears twice, byte for byte, counts once.
- The chain is built from the leaf up. Each next certificate signed the one before and is a CA (basic constraints
CA:TRUE). A certificate that does not continue the chain is not sent. - A self-signed root at the top of the chain is not sent, because the upstream holds its own roots.
- The broker sends the leaf and then the chain in the handshake.
So the order of the blocks does not matter, and a bundle that also carries the CA works as it is. On success, create and update print to stderr the certificate's subject, issuer and expiry, the length of the chain, and the subject of each certificate that will not be sent. They never print the key.
A refusal reads create inventory-client: the value is not a client certificate: <reason>, or … is not a CA bundle: <reason> for --type ca:
| The value | The reason |
|---|---|
No CERTIFICATE block, or one that does not parse |
no usable CERTIFICATE block |
| No private key block | no private key block |
| More than one private key block | more than one private key block |
An ENCRYPTED PRIVATE KEY, or a key with Proc-Type: 4,ENCRYPTED |
the private key is encrypted |
Another block type that ends in PRIVATE KEY, such as OPENSSH PRIVATE KEY |
unsupported key block "OPENSSH PRIVATE KEY" |
| A key block that does not parse | the private key block does not parse |
| A key that is not RSA, ECDSA or Ed25519 | unsupported private key type |
| No certificate that matches the key | the private key does not match the certificate |
| Two different certificates that match the key | more than one certificate matches the private key |
A leaf past its notAfter, or before its notBefore |
the certificate has expired on <date>, or the certificate is not yet valid: … |
A leaf whose extended key usage holds neither clientAuth nor anyExtendedKeyUsage. A leaf with no extended key usage is accepted |
the certificate's extended key usage does not allow client authentication |
A ca value holds one or more CERTIFICATE blocks, every one of which parses, and at least one CA certificate. Only the CA certificates in it become roots. A route's ca may name the same secret as its clientCertificate, for a PKI whose root signs both.
The type is not kept beside the value, and brig secret ls does not show it. The expiry of a tls certificate is kept as its provenance, which is what the expiry warning reads.
Value output #
read writes the value to stdout and adds nothing, so a pipe gets the stored bytes.
On a terminal, read adds a trailing newline and prints a warning, because the value is now in the scrollback:
$ brig secret read gh-token
ghp_16C7e42F292c6912E7710c838347Ae178B4a
brig: gh-token is now in this terminal's scrollback
→ to keep it out, pipe it: brig secret read gh-token | ...The warning goes to stderr, so a pipe gets only the value.
Command substitution #
The shell's $(...) strips all trailing newlines. That is correct for a token, such as GH_TOKEN=$(gh auth token) brig run claude. It is wrong for a value whose trailing newline matters, such as a PEM key stored with -f:
$ brig secret read from-file | wc -c
4
$ printf %s "$(brig secret read from-file)" | wc -c
3If the bytes matter, redirect:
(umask 077; brig secret read deploy-key > ./deploy-key)Secret names #
Every verb enforces the same grammar:
- letters, digits,
-and_ - starts with a letter
- at most 128 characters
$ printf %s v | brig secret create gh.token
brig: a secret name holds letters, digits, - and _, and "gh.token" holds "."
$ printf %s v | brig secret create 1password
brig: a secret name starts with a letter, and "1password" starts with "1"Storage #
A secret lives in your login keychain, under the service sh.brig.secret. Brig stores it as two items:
| Item | Holds |
|---|---|
<name> |
A random key |
<name>.sealed |
The value, encrypted under that key |
The renewal journal is a third item, <name>.journal. brig secret ls lists neither the .sealed nor the .journal item.
The value and the key never appear on a command line. The ciphertext and the secret's name do, and other processes on the host can read them there.
The encryption does not change who can read the value. Each item has the keychain's default ACL, so anything that can run /usr/bin/security as you can read it with no dialog. A process that can read Brig's keychain items as you can also decrypt the value. Security model lists what the keychain stops and what it does not.
Brig stores into a Secret Service keyring on your D-Bus session bus. gnome-keyring and KWallet both speak that API.
Brig keeps one item per secret in your default collection. Each item is tagged as Brig's, and Brig lists and touches nothing else in the keyring. If the collection is locked, Brig opens it through your keyring UI.
If the D-Bus session bus or the keyring is missing, brig secret says which one. It does not fall back to a file:
$ brig secret create gh-token
brig: no secret store on this platform: a D-Bus session bus is running but no Secret Service answers on it. Install a keyring (gnome-keyring or KWallet, both speak the Secret Service API) and log in to a session that starts it, or read the secret once from a command's output with `brig secret import <profile> --from-command '<sh>'`, which stores it like any other importBrig checks for the store before it reads stdin, so you learn of a missing store before you fetch a token. --from-command also needs a keyring to store into.
Secrets stored by older versions on macOS
A secret stored by an older Brig keeps working. The next update or import moves it into the two-item layout. You do not migrate anything by hand.
An older Brig refuses a secret stored in this layout, and never gives the key to a guest.
A secret behind a route #
A policy's route names a secret in this store. On a run with that route, Brig neither reads nor delivers the secret. brig-broker reads it from the store on each request, and adds it on the host. The sandbox gets a session token. A files: or env: binding of the same secret in the profile is dropped for that run, and brig info lists it as kept on the host.
A run whose route's secret is missing, or whose store does not open, is refused with exit code 6 before boot. The message names the command that stores the secret. A secret removed after the boot makes the route answer 502, and ~/.brig/host/broker/audit.log says why. Create or import it, and the next request finds it.
A route's clientCertificate and ca secrets are read the same way, on each request, and never reach the sandbox.
A secret behind an aws route holds a pointer to an AWS profile and no key. The broker answers with keys it fetches through aws. A route that forwards requests does not send such a pointer upstream. It answers 502 with check=credential.vendonly, since the pointer names your AWS profile and role.
A secret behind a gcp route can hold a pointer to a gcloud configuration in place of an access token. The broker injects a token it mints through gcloud. A route without services does not send such a pointer upstream. It answers 502 with check=credential.gcponly, since the pointer names your gcloud configuration and service account.
An AWS profile behind a route #
The aws route hands the sandbox temporary AWS keys. Its secret holds a pointer and no key: the AWS profile on your host, and whether the sandbox assumes a role or gets your own identity. Declare it in a profile with an aws source:
secrets:
- name: aws-creds
sources:
- from: awsThen import it, and say how the sandbox gets AWS:
brig secret import <profile> aws-creds --aws-profile dev \
--role-arn arn:aws:iam::111122223333:role/brig-coding-agent| Mode | Flag | What the sandbox gets |
|---|---|---|
| role | --role-arn <arn> |
Keys of a session of that role, assumed with your profile for 30 minutes at a time. The session is named after the sandbox, so CloudTrail shows which sandbox made a call |
| self | --identity self |
Keys of your own identity in that profile. The sandbox can do what you can |
import refuses a line that names neither mode, or both. Self mode is never the default. An aws flag on a secret whose source is not aws is refused too. The flags answer for one secret, so import each aws secret on its own line.
In role mode the session carries a source identity. Brig reads it from the last path segment of the profile's caller ARN, which for an SSO login is your user name. --source-identity sets another, of 2 to 64 of the characters A-Za-z0-9+=,.@_-.
A role session lasts 30 minutes, which bounds how long a leaked key works. --session-duration sets 25m to 1h. The role cannot enforce the length, because IAM has no condition key for it. Brig requests it.
Before it stores anything, import checks with aws that the profile works, that it has a region, and in role mode that it can assume the role. The sandbox gets the region as AWS_REGION and AWS_DEFAULT_REGION. A profile with no region is refused, with the command that sets one. --dry-run runs the same checks and stores nothing. In self mode, import prints the identity the sandbox will get. brig secret ls shows aws:<profile> in the FROM column.
aws runs with every AWS_ variable removed from its environment. A profile that works only because your shell exports AWS_PROFILE, AWS_CONFIG_FILE or a key fails at import, and not at the first run.
When the SSO login lapses and aws has no cached credentials left, a new run is refused with exit code 6. The message names aws sso login --profile <profile>. The aws route lists what the sandbox holds and how to revoke it.
A gcloud login behind a route #
The gcp route injects a Google access token into each request. Its secret can hold a pointer and no token: the gcloud configuration on your host, and whether the sandbox acts as a service account or as you. Declare it in a profile with a gcloud source:
secrets:
- name: gcp-creds
sources:
- from: gcloudThen import it, and say how the sandbox gets GCP:
brig secret import <profile> gcp-creds --gcloud-configuration default \
--impersonate-service-account brig-readonly@my-project.iam.gserviceaccount.com| Mode | Flag | What the sandbox gets |
|---|---|---|
| impersonate | --impersonate-service-account <email> |
Tokens of that service account, minted with your gcloud login. The service account's IAM roles limit what the sandbox can do. Your account needs roles/iam.serviceAccountTokenCreator on it |
| self | --identity self |
Tokens of your own gcloud login, the account the configuration names at import. The sandbox can do what you can |
import refuses a line that names neither mode, or both. Self mode is never the default. --gcloud-configuration is required. A gcloud flag on a secret whose source is not gcloud is refused. So is a line that selects two gcloud secrets, or one that carries an aws-only flag and a gcloud flag. Import each secret on its own line.
The configuration name is a lowercase letter followed by up to 62 lowercase letters, digits and -. The service account is a *.gserviceaccount.com address.
In self mode, import records the account that the configuration names. A configuration with no account is refused. If you later change the configuration's account, with gcloud config set account or a gcloud auth login as another user, mints fail until you import the secret again. The sandbox does not get the other identity.
Before it stores anything, import mints one token, as the broker will. It sends the token to Google's tokeninfo endpoint to check the identity it belongs to, and refuses a token for another identity. In self mode, it also refuses a token that names no account. A lapsed login or a missing serviceAccountTokenCreator grant fails at import, and not at the sandbox's first Google call. --dry-run runs the same check and stores nothing. import prints the identity the sandbox will act as:
gcp: the sandbox will act as brig-readonly@my-project.iam.gserviceaccount.com (impersonated by you@example.com)
gcp: the sandbox will get your own identity you@example.combrig secret ls shows gcloud:<configuration> in the FROM column.
gcloud runs without GOOGLE_APPLICATION_CREDENTIALS, CLOUDSDK_CONFIG, CLOUDSDK_CORE_ACCOUNT, CLOUDSDK_ACTIVE_CONFIG_NAME, any CLOUDSDK_AUTH_* variable, and the variables that set HTTP logging or the log level. A variable in your shell does not decide which identity the sandbox gets. gcloud reads your logins from $HOME/.config/gcloud. import refuses while CLOUDSDK_CONFIG is set. Unset it, or log in under $HOME/.config/gcloud with gcloud auth login --configuration <c>.
The broker mints a new token when the one it holds has less than 2 minutes left. When the login of the configuration has lapsed, a new run is refused with exit code 6. The message names gcloud auth login --configuration <c>, or in self mode gcloud auth login <account> --configuration <c>. The gcp route lists what the sandbox holds and the limits of this route.
A static token still works as the secret of a gcp route, for a quick try without a gcloud source.
Renewal on the host #
A run whose route serves claude-credentials does not deliver the document. Such a run works on macOS with the hvi backend and on Linux with nerdctl and urunc. brig-broker renews the OAuth pair on the host, so the sandbox never holds the refresh token. Every other run still delivers the document as a file. See Sessions that stop authenticating.
anthropic-oauth, the lifecycle of the claude-code preset |
|
|---|---|
| What refreshes | accessToken, refreshToken and expiresAt in claudeAiOauth |
| When | 10 minutes before expiresAt, or halfway through the life of a pair shorter than 20 minutes, and once when the provider refuses the access token |
| From where | The host, to the provider's token endpoint over HTTPS, with full verification. Never through a route. HTTPS_PROXY and NO_PROXY apply |
| What is written back | The same document with the three fields replaced. The provenance keeps its FROM, and its expiry moves to the new expiresAt |
| What is refused | An answer that is not a 200 with an access token and a refresh token. Brig keeps the old document and writes nothing |
The provider rotates the refresh token single-use. So one broker refreshes each secret, one refresh at a time, and two sandboxes that share the secret wait on the same refresh. Once a refresh request has reached the provider, Brig does not send that refresh token again, whatever fails after it.
The new document is written back to the store before its access token is used. A write that fails is retried 30 seconds later at the earliest, and the broker serves the new document from memory meanwhile. Brig reads the store again before every refresh and every write-back, and at least every 5 minutes. A deleted secret stops being served. A secret you import again replaces the document in memory. After a failed refresh, log in on the host and run brig secret import claude-code.
The import copies the host's own refresh token. Brig and Claude Code on the host then hold the same pair, and whichever side refreshes first invalidates the other's copy. Do not run Claude Code on the host against the same account during a brokered run.
The renewal journal #
Between the provider's answer and the write-back, the new refresh token is only in the broker's memory. So the broker journals each refresh in the store, next to the secret, as <name>.journal. The journal is a store item like the secret, never a file.
- The broker creates the journal in phase
renewing, with the start time and the SHA-256 of the document it starts from. If the journal cannot be written, the refresh is not sent. - The broker calls the provider.
- The journal moves to phase
renewed, and holds the new document. - The secret takes the new document.
- The broker deletes the journal.
When the broker next serves the secret, or a sandbox registers a route for it, it reads the journal first. A renewed journal over an unchanged secret is written to the secret, without a call to the provider. A renewing journal over an unchanged secret is dropped, and the broker renews once at the next request. If the provider then refuses the token as spent, log in on the host and import again. A secret that changed since the refresh started, because you imported it again, wins over any journal. brig doctor reports refresh recovering until the broker settles the journal.
The journal records the process id of its broker and that process's start time. A journal of another broker that still runs, younger than 10 minutes, is left alone. brig secret delete removes the journal with the secret. brig secret read and delete refuse a journal's own name, because a journal can hold the only valid copy of a renewed credential.
Errors #
| What Brig says | What happened |
|---|---|
a secret named "x" already exists. To replace it: brig secret update x |
create will not overwrite. |
no secret named "x". To create it: brig secret create x |
update will not create. |
no secret named "x". `brig secret ls` lists them |
read or delete on a name that is not there. |
create x was given an empty value, and brig skips empty variables when it forwards them, so it would never reach a sandbox |
The source was empty. |
no value on stdin. Pipe one in, or pass -f <file>: … (and prints two examples) |
create at a prompt with nothing piped in. It does not wait, because a value typed there goes into your scrollback. |
-f was given an empty path. Leave it out to read stdin, or pass `-f -` to say so |
-f "$KEYFILE" with the variable unset. Brig does not fall through to stdin, which can hold other data from the script. |
--stdin and -f name two different sources; pass one |
Both were given. |
the value on stdin is over 65536 bytes, which is larger than any secret brig can store. If that is a file or a stream rather than a credential, this is the wrong one |
create or update read more than 65536 bytes before reaching the store. With -f FILE, the message names the file in place of stdin. |
"x" secret is damaged: the key is in the keychain, but its sealed value is missing. Store it again: … |
The x.sealed item was removed and the key item was not. See Storage. |
"x" secret is damaged: the sealed item does not open with the key stored for it, so one of them was changed outside brig. Store it again: … |
One of the two items was replaced by something other than Brig. Storing the value again replaces both. |
"x" secret is damaged: the sealed item is not a brig sealed value, so something other than brig put it there. Store it again: … |
The x.sealed item holds something that is not Brig's format. Storing the value again replaces both. |
deleting "x" cannot be undone, and there is no terminal to ask on. Pass -y to answer in advance: … |
delete ran with no terminal, such as in a cron job or a unit file. |
a secret name holds letters, digits, - and _, ... |
See Secret names. |
no secret store on this platform: … no Secret Service answers on it … |
Linux with no keyring on the D-Bus session bus. Install gnome-keyring or KWallet and log in to a desktop session that starts it. |
no secret store on this platform: … a keyring is running but has no default collection … |
Linux with a keyring but no default collection, such as a headless or freshly provisioned session that has not opened one. Open your keyring once from a desktop session, which creates it. |
"x" is a secret, not a profile, and import takes the profile that declares it: … |
import's first argument is a profile. The message names the profile that declares the secret you typed. |
nothing to import for "x": … held no value |
The profile's sources exist and none of them had anything. Usually: run the agent on the host once to log in. |
"x" is already stored and brig did not put it there, so importing would replace a value you supplied |
You created it by hand. Pass -y if you mean to replace it. |
--from-command fills one secret, so it needs one name |
It supplies a value, and nothing in the command says which secret it is for. |
<verb> x: the value is not a client certificate: … or … is not a CA bundle: … |
--type tls or --type ca refused the value, and nothing was written. See Certificates and CA bundles. |
say how the sandbox gets AWS: --role-arn <arn> (recommended) or --identity self |
An import of an aws source that names neither mode. |
the AWS SSO session for profile x has expired; … |
The SSO login of the profile lapsed. Run the command it names on the host, then run again. |
the aws command was not found; install the AWS CLI v2: … |
The aws CLI is not on PATH. For the broker, that is the PATH of the brig that started it. |
say how the sandbox gets GCP: --impersonate-service-account <email> (recommended) or --identity self |
An import of a gcloud source that names neither mode. |
--impersonate-service-account and --identity self are two answers; pass one |
An import of a gcloud source that names both modes. |
--gcloud-configuration is required: … |
An import of a gcloud source with a mode and no configuration. |
the gcloud configuration x has no account; run gcloud auth login --configuration x |
A self-mode import of a configuration that is not logged in. |
the gcloud configuration x minted a token for y, not z, the account it was imported with; … |
The configuration's account changed after a self-mode import. Import the secret again to use the new account. |
the aws and gcloud flags fill different secrets; import each on its own line |
One import line carries an aws-only flag and a gcloud flag. |
the gcloud login of configuration x has expired; … |
The gcloud login lapsed. Run the command it names on the host, then run again. |
your gcloud account cannot impersonate x; it needs roles/iam.serviceAccountTokenCreator on that service account |
Your account has no grant to mint tokens for the service account. Grant the role in IAM. |
the gcloud command was not found; install the Google Cloud CLI: … |
The gcloud CLI is not on PATH. For the broker, that is the PATH of the brig that started it. |
the imported credential x (y) expired N ago, followed by renew it on the host, then: brig secret import y |
A run found a stored, imported credential past its expiryField:. Log in on the host again and import again. |