Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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: agent for anything an AI runs (the MCP server refuses any other kind), host for a machine, human for 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:

SettingTaken 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 certificatesBOUNCER_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 messageWhat to do
7, no server addressWrite the address to ~/.config/bouncer/server, or set BOUNCER_URL
7, the key file can be read by otherschmod 600 ~/.config/bouncer/key
7, plain HTTPThe server address must start with https:// (plain http:// works only for an address on this machine, for testing)
6, the key isn't acceptedThe key is wrong, was replaced, or the requester was disabled. Ask your admin
1, the server can't be reachedCheck the address, your network or VPN, and any proxy settings
1, a certificate errorIf 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.

This manual covers Bouncer 0.5.7. Built from source commit cdd3b5958d5be0b33e865b1b56b770f6bccffaf7 (workspace version 0.5.7+34).