Set up a requester
A requester is whoever asks Bouncer for access: you at the command line, an AI agent, or a host such as a build server. Each one has its own requester key, a random string starting brk_. The key lets the requester ask and use what's approved for it. It can never approve anything.
1. Get a key from your admin
The admin creates the requester on the Bouncer server and gives you its key as a file (People, requesters and devices). Ask for:
- one requester per agent, host or pipeline, so the approver can tell them apart and the admin can disable one without affecting the others;
- the right kind:
agentfor anything an AI runs (the MCP server refuses any other kind),hostfor a machine,humanfor you.
If you're listed as a person in the server's configuration, your own human requester already exists. The admin gives it a key with bouncer-admin requester rotate-key <your-id>, which also stops any key it had before.
The key is shown to the admin only once. If it's lost, the admin makes a new one, and the old one stops working.
2. Store the key
Copy the key file to the machine that will use it (for example with scp), then, as the user who will run bouncer:
install -d -m 700 ~/.config/bouncer
install -m 600 build-agent.key ~/.config/bouncer/key
shred -u build-agent.key
echo https://bouncer.example.com > ~/.config/bouncer/server
bouncer now reads the server's address and the key from those two files, so there's nothing to export.
The key file is checked the way ssh checks a private key: it must belong to you or root, and other users must not be able to read or change it. bouncer refuses it otherwise, with exit code 7.
To use a different key, for example for an agent running under your own user, keep it in another file and point to it:
export BOUNCER_KEY_FILE=~/.config/bouncer/agent-key
The order bouncer uses:
| Setting | Taken from, first match wins |
|---|---|
| Server | --server, then BOUNCER_URL, then the first line of ~/.config/bouncer/server |
| Key | --key-file, then BOUNCER_KEY_FILE, then BOUNCER_KEY (the key itself), then ~/.config/bouncer/key |
| Extra CA certificates | BOUNCER_CA_FILE, a PEM file trusted on top of the system's, for both Bouncer and OpenBao |
$XDG_CONFIG_HOME replaces ~/.config when it's set.
Never type the key as an argument. bouncer refuses any argument that looks like a key, because it would end up in your shell history and in the process list where other users can see it. BOUNCER_KEY works, but a file is safer: an environment variable is passed to every program you start.
3. Check it works
bouncer resources
Expected result: a table of the resources this requester may ask for:
RESOURCE NAME KIND FIELDS FOR WRITE NOW
prod-db-password Production database password secret password 5m,15m,1h,6h,1d no -
deploy-token Deploy token api-key token 5m,15m,1h yes -
If it fails:
| Exit code and message | What to do |
|---|---|
| 7, no server address | Write the address to ~/.config/bouncer/server, or set BOUNCER_URL |
| 7, the key file can be read by others | chmod 600 ~/.config/bouncer/key |
| 7, plain HTTP | The server address must start with https:// (plain http:// works only for an address on this machine, for testing) |
| 6, the key isn't accepted | The key is wrong, was replaced, or the requester was disabled. Ask your admin |
| 1, the server can't be reached | Check the address, your network or VPN, and any proxy settings |
| 1, a certificate error | If your organisation uses a private CA, set BOUNCER_CA_FILE to its PEM file |
Proxies
HTTPS calls go through HTTPS_PROXY (or ALL_PROXY) when one is set, except to the hosts in NO_PROXY. The proxy only sees an encrypted tunnel. Plain HTTP and calls to this machine never go through a proxy, and HTTP_PROXY is never used, so a proxy can never see the key or a token in clear.