Secrets
Read keys from Bitwarden, 1Password or a command
By default your provider keys sit in a file in your Headmaster home folder. If you would rather keep them in a password manager, Headmaster can read them from there each time it starts. You keep one small token locally, and every other key stays in the vault where you can rotate it in one place.
These are command line features. They apply where the agent runs, which is your own computer in Work mode.
Supported sources
| Source | Command | You need |
|---|---|---|
| Bitwarden Secrets Manager | headmaster secrets bitwarden (alias bw) | A machine account and access token. The free tier works. |
| 1Password | headmaster secrets onepassword (aliases op, 1password) | The op command line tool, signed in. |
| Command helper | Set in the config file | Any vault with a command line, such as pass or keepassxc-cli. |
You can turn on more than one source at once.
Bitwarden
- In Bitwarden, create a machine account, give it read access to one project and make an access token.
- Run the setup:
headmaster secrets bitwarden setup
It installs the bws tool if needed, asks for the token (hidden), asks for your region (US, EU or self-hosted), lets you pick the project, test-fetches the secrets and switches the integration on.
Every time Headmaster starts, it fetches the project's secrets and applies them. By default the vault wins over values already set, so rotating a key in Bitwarden reaches Headmaster the next time it starts.
| Command | What it does |
|---|---|
setup | Guided setup. Accepts --project-id, --access-token and --server-url. |
status | Show the settings, the tool and whether the token works. |
token | Replace an expired or revoked token. It is checked before it is stored. |
sync | Preview what would be applied. Add --apply to apply it to the current shell. |
install | Install or repair the bws tool. Add --force to re-check it. |
disable | Turn it off. Your token and project stay in place. |
Each is run as headmaster secrets bitwarden <command>.
1Password
Keep each key as a 1Password item and point Headmaster at it with an op://vault/item/field reference.
headmaster secrets onepassword setup
headmaster secrets onepassword set OPENAI_API_KEY "op://Private/OpenAI/api key"
headmaster secrets onepassword sync
| Command | What it does |
|---|---|
setup | Check op, record the account or token setting and switch it on. Accepts --account, --token-env, --token and --binary-path. |
status | Show the settings, the tool, sign-in state and your references. |
token | Replace a service-account token. |
set ENV_VAR "op://..." | Map a setting to a reference. |
remove ENV_VAR | Drop a mapping. |
sync | Preview what resolves. Add --apply to apply it to the current shell. |
disable | Turn it off. Your mappings stay in place. |
Headmaster never signs in for you and never downloads op. It uses the copy you already trust. If op is missing, locked or a reference is wrong, you get a one-line warning and startup carries on with the keys it already has.
Command helper
Any tool that can print KEY=VALUE lines will do. Set it in the config file:
secrets:
command:
enabled: true
command: "pass show headmaster/env"
Headmaster runs the command once at startup. It must be quick and must not ask questions: the default time limit is 3 seconds. Its error output is discarded on purpose, because vault tools can print secret material there. A helper does not override existing values unless you set override_existing: true. This source needs a Unix shell and is not available on Windows.
Which value wins
When the same setting comes from several places:
- Your own file and shell win, unless a source has
override_existing: true. Bitwarden and 1Password do by default. - A source where you map each setting yourself beats one that brings a whole project.
- Otherwise the first source wins, and you see a warning at startup. Nothing is replaced silently.
To keep some values local whatever the vault says, list them:
secrets:
preserve_existing: [TELEGRAM_BOT_TOKEN]
Good to know
- The token that unlocks the vault still lives locally. It is the only secret there.
- Commands the agent runs, and code it executes, get a cleaned environment. Your keys are removed unless you list a setting under
terminal.env_passthrough. - Startup is never blocked by a vault problem. You get a warning and Headmaster continues with local keys.
- For a sandbox that must never hold your real keys, combine this with the Egress proxy.