Manual for Bouncer 0.5.7. Chapters state version and distribution limits. Source cdd3b59, site build 20 November 2026. Your server or app may run an earlier version.
Bouncer documentation
Bouncer lets people approve or deny access to an organisation's secrets from their phone or PC. A person, a script or an AI agent asks for access to a secret, an API key or an SSH host. The people who look after that resource get the request in the Bouncer app. They approve it for a length of time they choose, or deny it. When the time runs out, Bouncer stops handing out the secret. Anyone who already read it still has the value, so if that matters, change the secret where it is used.
Your organisation runs its own Bouncer server. The secrets themselves are kept next to that server in OpenBao. OpenBao is an open-source fork of HashiCorp Vault, managed by the Linux Foundation.
This manual covers Bouncer 0.5.7. Your server or app may run an earlier version. Platforms and status says what is available on each platform.
Approving requests in the app
Use the apps covers installing the app, pairing it with your organisation's server, approving and denying requests, and what to do when a device is lost or replaced.
A lost or replaced device
See Replace, lose or remove a device. If a paired phone or PC is lost or stolen, tell your administrator straight away.
Connecting a script, service or AI agent
Integrate with Bouncer covers the bouncer
command-line tool, setting up a requester, the MCP server for AI agents, and
patterns for workloads.
Running the server
Operate a Bouncer server covers installing the server and OpenBao, configuration, pairing, backups, upgrades and recovery. How Bouncer protects access explains what Bouncer protects against and what it doesn't. The Reference has the API, config file, CLI and ports.
Approval time and access time
A request has a short time to be answered, usually minutes. If you approve, you also choose how long the access lasts, which can be much longer. Approvals and access duration explains both.
Help
- Frequently asked questions
- Glossary: the words these pages use, explained
- Support: who to ask, and what to tell them
- Releases: what changed in each version
Use the apps
The Bouncer app is where people answer access requests. You can also ask for access yourself, see the access you've approved and end it early, and, where your organisation allows it, look at or save a credential.
Before you start
You need three things:
- A Bouncer server run by your organisation. The app doesn't work on its own. Your organisation's Bouncer administrator sets up the server and adds you to it as a person who can approve, ask for access, or both.
- A network connection that reaches that server. That may be your office network, the internet, or a VPN, depending on how your organisation runs Bouncer. The app doesn't need any particular network product. If your organisation uses a VPN for Bouncer, connect it first.
- A one-time pairing code from your administrator. They make it with
bouncer-admin device pairon the server. It works once and only for a few minutes.
On Windows, "tap" means click.
The tasks, in order
- Install the app on your device: Android, Windows, or see iPhone and Mac for where those stand. Get Bouncer says where the files are today.
- Pair the app with your server. This registers the device with the server. A phone makes its approval key as it pairs; a Windows PC makes one later, when you turn on Windows Hello.
- Answer requests. Approve for a length of time you choose, or deny.
- Understand approvals and access duration. The time to answer and the length of access are different things.
- See and end access you've approved, in Grants.
- Ask for access yourself, if your administrator lets you.
- View, save and share credentials in the Library, where your server allows it.
- Replace, lose or remove a device, including signing out and switching servers.
- Fix common problems.
What each app can do
The Android and Windows apps come from the private GitLab release. The iPhone app is in internal testing, and the Mac app is in development, so neither is available to install yet. Platforms and status has the status of each.
| Android | Windows | |
|---|---|---|
| See requests, grants and your own requests | Yes | Yes |
| Approve and deny | Yes | Yes, if the PC has a TPM and your server accepts Windows Hello keys. Then turn on Windows Hello. |
| Pair | QR code or pairing string | Pairing string |
| Notifications | Push notifications, even when the app is closed | Windows notifications, only while Bouncer is running (in the window or the tray) |
| Approve from a notification | If you turn it on, and your server allows it | No |
Words used in the app
A few words come up everywhere. The glossary has more.
- Requester: whoever asks for access. It can be a person, a script or host, or an AI agent. Each has its own requester key, issued by Bouncer.
- Approver: a person allowed to approve or deny requests for a resource.
- Resource or credential: the thing being asked for, such as a stored secret, an API key or SSH access to a host.
- Grant: the access you approved. It has an end time, and you can revoke it before then.
- Approval key: a key your device makes and keeps (a phone when you pair it, a PC when you turn on Windows Hello). The app signs every approval and denial with it, so the server knows the decision came from your device.
Install, update and remove the app on Android
Bouncer has no public Play listing or public download. These steps cover the APKs from the private release, which you install yourself (sideloading). Get Bouncer says where the files are and who can get them, and Platforms and status has the state of Google Play internal testing.
What you need
- A phone running Android 9 or later.
- A screen lock (PIN, pattern or password). Bouncer's approval key only works while the phone is unlocked, so Android needs a lock to protect it.
- From the release: the APK,
bouncer-android-<version>.apk, andSHA256SUMS.SHA256SUMShas a checksum for every file in the release: a 64-character string of letters and numbers that only that exact file produces.
Install
-
Check the file, if you can, before installing it. On a computer, in the folder with the APK and
SHA256SUMS:sha256sum -c SHA256SUMS --ignore-missingIt should say
bouncer-android-<version>.apk: OK. On a Mac, runshasum -a 256 bouncer-android-<version>.apkinstead. On Windows, runGet-FileHash .\bouncer-android-<version>.apkin PowerShell. On a Mac or Windows, check that the long string it prints matches the APK's line inSHA256SUMS. If it doesn't match, don't install it, and tell whoever gave it to you. -
Copy the APK to the phone, or download it there.
-
Open the APK on the phone, from your Downloads or Files app.
-
If Android says that for your security it isn't allowed to install unknown apps from this source, tap Settings, turn on Allow from this source, and go back. This permission is for the app you opened the APK with (for example Files or your browser), not for Bouncer. You can turn it off again after installing.
-
Tap Install. Google Play Protect may warn that it doesn't recognise the app, because it didn't come from Play. If you're sure the file came from your organisation, choose to install anyway.
-
Open Bouncer. You should see "Approve access to your secrets from this phone." and the steps To pair this phone.
Next: pair the app with your server.
Update
Install the newer APK the same way, over the one you have. Android keeps your pairing, and you don't need to pair again.
Android only accepts an update signed by the same key as the installed app. If it says App not installed or that the package conflicts with an existing one, the new file was signed differently (for example, a copy from the Play internal track, or a differently signed test build). Don't uninstall to get round it without reading Remove first: uninstalling removes the pairing, and you'll need a new pairing code.
To see which version you have, open Settings (the gear at the top right)
and look under About. It shows the version with its build number, for
example Bouncer 0.5.7+34 (pre-release).
Test builds
Testers may be given an internal test build,
bouncer-android-<version>-internal.apk, through Firebase App Distribution,
Google's service for test builds. At the moment the 0.5.7 internal build is
only for S6 Studios' own testing, and there's no public link
(Platforms and status).
An internal build installs over a build signed with the same key and keeps the pairing. It can't update a copy from Google Play, which is signed with a different key. It shows a red banner, "Internal test build: screenshots allowed", on every screen, and it lets you take screenshots of screens that show a secret. Use it only with test data, and delete screenshots you don't need.
Remove
- In Bouncer, open Settings and tap Sign out. Read the message and tap Sign out again. Bouncer asks your server to revoke this phone, then deletes the pairing and the approval key from the phone.
- Uninstall Bouncer: press and hold its icon, tap App info, then Uninstall.
Uninstalling deletes everything Bouncer kept on the phone. But if you
uninstall without signing out, your server still lists the phone as
paired. Ask your administrator to revoke it. They can find it with
bouncer-admin device list and remove it with bouncer-admin device revoke.
If you reinstall later, Bouncer starts unpaired. When you pair it again, it lists your other devices on this platform under Paired this phone before?, with the command to revoke the old pairing on the server.
If something goes wrong
| What you see | What to do |
|---|---|
| Android won't open the APK | Check the file finished downloading, and that the checksum matches. |
| App not installed when updating | The new APK was signed with a different key. See Update. |
| Bouncer opens on the pairing screen after an update | The old app was removed before the new one was installed, so the pairing was lost. Pair again, and ask your administrator to revoke the old pairing. |
| No notifications | See Troubleshooting. |
Install, update and remove the app on Windows
There's no public download of the Windows app yet. The files come from Bouncer's private release (Get Bouncer says where they are and who can get them). There are two ways to install it. If you're not sure, use the installer (MSIX). Use the portable ZIP only if you can't get administrator rights on the PC for the one-time certificate step, or if your organisation's IT policy blocks installing app packages from outside the Microsoft Store.
| Installer (MSIX) | Portable ZIP | |
|---|---|---|
| Administrator rights on the PC | Yes, once: someone with administrator rights on the PC trusts S6 Studios' certificate | No |
| Start menu entry | Yes | No |
| Starts in the tray when you sign in | Yes (you can turn it off) | Only if you add a shortcut |
| Updates | From its update link, if you installed it that way | Never; download each new version |
| Remove it | Settings > Apps | Delete the folder |
Use one or the other, not both. The installer can pick up a pairing the ZIP left on the PC, so the two can end up as the same device on your server, and revoking one would revoke the other. To move from the ZIP to the installer, follow the steps under Update.
What you need
- Windows 11, 64-bit (x64).
- The files from the release:
bouncer-windows-x64-<version>.msix, the certificatebouncer-beta-signing.cer,SHA256SUMSandbouncer-windows-install-instructions.md, or the ZIPbouncer-windows-x64-<version>.zipandSHA256SUMS. - To approve on this PC (rather than only see requests): Windows Hello with a PIN, a TPM security chip (most PCs sold with Windows 11 have one), and a server that accepts Windows Hello keys. Servers don't by default, so ask your administrator. See Approve on Windows.
Install with the MSIX
1. Check the files
In PowerShell, in the folder with the files:
Get-FileHash -Algorithm SHA256 .\* | Format-Table Hash, Path
Each hash should match that file's line in SHA256SUMS. SHA256SUMS lists
every file in the release, so it has lines for files you didn't download too.
(bouncer-windows-install-instructions.md may call it SHA256SUMS.txt. Use the release's SHA256SUMS; its lines for the Windows files are the same.)
2. Trust S6 Studios' certificate (once per PC)
The installer is signed with S6 Studios' own certificate. S6 Studios makes Bouncer. The certificate isn't from the Microsoft Store or a public certificate authority, so Windows has to be told to trust it once. This needs administrator rights on the PC. If you don't have them, ask your IT team to do this step.
Open Terminal (Admin) (right-click Start), go to the folder, and run:
Import-Certificate -FilePath .\bouncer-beta-signing.cer -CertStoreLocation Cert:\LocalMachine\TrustedPeople
Check that the thumbprint it prints matches the one in
bouncer-windows-install-instructions.md. If it doesn't, stop: the file
isn't the one that was published.
Trusted People lets Windows accept app packages signed by this one certificate. It doesn't make it a certificate authority for anything else. Don't put it in Trusted Root Certification Authorities.
3. Install
In a normal (not administrator) window, double-click the .msix file and
choose Install, or run:
Add-AppxPackage -Path .\bouncer-windows-x64-<version>.msix
If Install is greyed out and App Installer says the publisher certificate couldn't be verified (0x800B010A), do step 2 first.
4. Open Bouncer
Open Bouncer Desktop from the Start menu. You should see Pair this PC. Next: pair the app with your server.
Install the portable ZIP
- Right-click the ZIP and choose Extract All. Choose a folder in your own
profile, for example
C:\Users\alice\Apps\Bouncer. You don't need administrator rights. - Open the extracted
Bouncer-<version>folder and runBouncer.exe. Keep the DLL files and thedatafolder beside it. Don't run it from inside the ZIP. - The ZIP isn't signed, so Windows may say Windows protected your PC. Choose More info, then Run anyway.
If Windows says a plugin DLL is missing, you ran it from inside the ZIP or copied the EXE on its own. Extract the whole ZIP and run that copy.
To start the ZIP copy when you sign in: press Windows+R, type shell:startup,
press Enter, and make a shortcut to Bouncer.exe there. Add --tray at the
end of the shortcut's Target to start it in the tray without a window.
How it runs
- Closing the window keeps Bouncer running in the notification area (the tray). Click the tray icon to open it again. The icon shows how many requests are waiting.
- To stop it, right-click the tray icon and choose Quit Bouncer Desktop, then confirm. You won't get request notifications on this PC until you open it again.
- Notifications only come while Bouncer is running. Windows has no push to a closed Bouncer, so requests wait until you start it (they also reach your other paired devices).
- The installed MSIX starts in the tray when you sign in. To stop that, turn Bouncer Desktop off in Settings > Apps > Startup.
- While the PC is locked, notifications say only "Access request pending" and "Unlock this PC to see the details".
Update
Bouncer doesn't update itself; Windows does. In Bouncer, open Settings and look under About at Updates. It shows the installed version and how this copy updates:
- Installed from its update link (a
Bouncer.appinstallerfile): Windows checks for updates when you start Bouncer (at most every 8 hours), and in the background at other times.- If it finds one when you start Bouncer, Windows asks first. Finish Updating installs the update and then opens Bouncer. Open Now opens the version you have straight away and updates in the background. If you close the question with its X, nothing opens; start Bouncer again.
- Check now, in Bouncer's Settings, checks straight away. If there's an update, it says "Update downloaded. It installs the next time Bouncer Desktop starts."
- Either way, a running Bouncer is never closed for an update, so an approval you're in the middle of isn't lost.
- Installed from the MSIX file itself: it says it doesn't check for updates. Install a newer MSIX the same way; it upgrades in place and keeps your pairing. To get automatic updates, install once from the update link if your organisation provides one. Bouncer has no update link yet: it needs a public place to host it, which isn't decided.
- The portable ZIP never updates. Download and extract each new version.
Move from the ZIP to the installer
Do it in this order, so the installer starts without the ZIP's pairing:
- In the ZIP copy of Bouncer, open Settings and choose Sign out, then confirm. This asks your server to revoke the ZIP's device and deletes its pairing from the PC.
- Quit the ZIP copy from the tray icon, and delete its folder.
- Install the MSIX as described above, and pair it with a new pairing code.
If you pair the MSIX first and then ask your administrator to revoke the ZIP's device, you may revoke the MSIX too, because it can start with the ZIP's pairing.
If a later release is signed with a publicly trusted certificate instead of S6 Studios' own, Windows will treat it as a different app. You'll install it beside this one, pair it again, and then remove the old one.
Remove
Uninstalling doesn't always remove the pairing, so sign out first:
-
In Bouncer, open Settings and choose Sign out, then confirm. Bouncer asks your server to revoke this PC, then deletes the pairing from the PC. If the server can't be reached, it says so and shows the
bouncer-admin device revokecommand for your administrator. -
Quit Bouncer Desktop from the tray icon.
-
Remove the app:
- MSIX: Settings > Apps > Installed apps, find Bouncer Desktop, choose Uninstall.
- ZIP: delete the folder you extracted, and the folder
%LOCALAPPDATA%\S6 Studios\Bouncer.
-
If you turned on Windows Hello approvals, Windows still keeps a passkey named "Bouncer on DEVICE-NAME", where DEVICE-NAME is the name you gave this PC when pairing. Remove it in Settings > Accounts > Passkeys.
-
To remove S6 Studios' certificate too, in PowerShell as administrator:
Get-ChildItem Cert:\LocalMachine\TrustedPeople, Cert:\CurrentUser\TrustedPeople | Where-Object Thumbprint -eq '<thumbprint from bouncer-windows-install-instructions.md>' | Remove-Item
If you already uninstalled without signing out, delete
%LOCALAPPDATA%\S6 Studios\Bouncer if it's there, and ask your administrator
to revoke the PC on the server.
The ZIP also leaves three small registry entries for notifications, under
HKEY_CURRENT_USER\Software. They do nothing once Bouncer is gone; the
README-windows.txt in the ZIP lists them if you want to delete them.
iPhone and Mac
iPhone
The iPhone app isn't available to install yet. It's in internal testing at S6 Studios through TestFlight, Apple's test-distribution service. S6 Studios installed an earlier test build on a real iPhone, paired it and approved a request with it. iOS 0.5.7 hasn't been checked on a real iPhone yet (Platforms and status).
Until then, approve on an Android phone or a Windows PC. Ask your administrator which to use. Then follow Install on Android or Install on Windows.
What the iPhone app does
- The same screens as the Android app: inbox, approvals, grants, requests, the Library, and Settings. It pairs by QR code or pairing string.
- An approval key in the iPhone's Secure Enclave. Every approval needs Face ID or Touch ID, with no passcode fallback. Changing Face ID or Touch ID retires the key, and the iPhone has to be paired again.
- Notifications through Firebase Cloud Messaging and Apple's push service. They carry only a random ID and generic text.
- iPhone alerts have no Approve or Deny buttons; open the request to answer it.
- iOS doesn't let an app block screenshots. When a value is shown, the app hides it while the screen is being recorded or mirrored, and before the app switcher takes its picture.
These pages will cover installing it from TestFlight once that's open to testers.
Mac
The Mac app is in development. On a Mac today, you can't approve requests. Use a paired Android phone or Windows PC.
See Platforms and status for every platform.
Pair the app with your server
Pairing connects the app to your organisation's Bouncer server. A phone makes its own approval key while pairing; a Windows PC makes one later when you turn on Windows Hello. The key never leaves the device, and the server records the device and its key. After that, the server sends your requests to this device, and accepts approvals signed with its key.
What you need
-
A network connection that reaches your Bouncer server. If your organisation uses a VPN for Bouncer, connect it first; otherwise nothing extra is needed.
-
A pairing code from your administrator. They run
bouncer-admin device pairon the server, which shows:- a QR code to scan with a phone;
- a pairing string, one line starting
bouncer-pair:, to copy and paste; - the server address and a 12-character pairing code (shown as three groups of four), to type in by hand.
The code works once, and expires a few minutes after it was made. Ask for it when you're ready to pair. If your administrator sends you the pairing string, use a private channel: anyone who uses it first pairs as you.
On an Android phone
- Open Bouncer. You see To pair this phone with the command your administrator runs.
- Tap Scan QR code and point the camera at the QR code. Or tap Enter the code instead, then either Paste pairing string (if you copied the pairing string) or type the Server address and Pairing code, and tap Continue.
- On Name this phone, check the banner. It says Pairing with your server's address and As your name. If either is wrong, stop and ask your administrator.
- Check the Device name, or change it. It's shown in alerts and the approval log, so make it recognisable, for example "Alice's Pixel".
- Confirm every signature with biometrics is offered on Android phones that can make such a key. Tick it to require your fingerprint (or face, where strong enough) for every approval, instead of just an unlocked phone. Your server must allow these keys, and servers do not by default. If it refuses, tap Pair without biometrics. It is off unless you choose it.
- Tap Pair.
- You should see "Alice's Pixel is paired" and "It can now approve and deny requests on" your server. Your other paired devices get a New device paired alert.
- Tap Turn on notifications and allow them when Android asks, so you hear about requests without opening the app. Notifications show details only once the phone is unlocked.
You land in the Inbox. "Nothing waiting" is normal until someone asks for something.
Setting up biometric approvals later
If you paired without Confirm every signature with biometrics, Settings shows Set up biometric approvals. It needs a new pairing code, and your server must allow biometric keys. Your current pairing stays until the new setup succeeds.
On Windows
- Open Bouncer. You see Pair this PC.
- On the server, your administrator runs
bouncer-admin device pairand gives you the line under "Or copy this pairing string". Copy it. - In Bouncer, choose Paste pairing string. It fills in the Server address and Pairing code. (You can also type them.)
- Check the Device name, then choose Pair.
- Bouncer shows Pairing with your server's address and As your name. If both are right, choose Pair this PC. If either is wrong, stop and ask your administrator.
- Bouncer opens on the inbox. Your other paired devices get a New device paired alert.
Turn on approvals with Windows Hello
A PC pairs without an approval key, so at first it can only show requests and grants. To approve and deny on the PC:
- In the inbox (or in Settings), find the Windows Hello row and choose Enable. If the row is missing, your server does not accept Windows Hello keys (servers do not by default), or Bouncer cannot reach it. Ask your administrator.
- On Windows 11, Windows may ask "Let Bouncer Desktop create and use passkeys?" If it does, choose Yes.
- Windows asks you to confirm it's you. Choose Continue, then enter your Windows Hello PIN (or use your face or fingerprint). Windows asks twice: once to make the key and once to use it.
- You should see "Windows Hello approvals are on for this PC."
If you see "Windows Hello approvals need a PC with a security chip (TPM)", this PC can't approve; approve on another paired device instead. If you see "This server doesn't accept Windows Hello keys", your administrator hasn't turned them on.
Once approvals are on, the app marks this key as not checked by hardware. In 0.5.6 and earlier, Bouncer does not check whether a Windows Hello key is held in the TPM. 0.5.7 checks a TPM attestation when Windows supplies one, but no real PC has passed that check yet (Device keys).
If you chose No to the passkeys question, turn Bouncer Desktop on under Settings > Privacy & security > Passkeys > Let apps create and use passkeys, then choose Enable again. Windows Hello also needs a PIN, which you set up under Settings > Accounts > Sign-in options.
More than one device
You can pair a phone and a PC. Each request goes to all your devices, and answering on one closes it on the others. Each device's Settings lists the others under Your other devices, with whether each one approves.
The server check on Windows
On Windows, after you type the server address (press Enter, or move to the
next field), Bouncer checks it before any code is sent. It asks the server's
/v1/health, which needs no sign-in and changes nothing, and shows four
separate lines:
- Reachable: the PC got a connection to the server.
- Secure connection: the server's certificate is valid for the name you typed, in date, and from a certificate authority this PC trusts.
- Bouncer API: it answered as a Bouncer server this app can talk to.
- Pairing: always "Not paired yet" here. Pairing happens when you choose Pair, with the code.
The check gives up after 10 seconds. Retry runs it again. Changing the address stops a check that's still running and clears its result, and Pair checks the address first if it hasn't passed yet. Pairing can't start until the check passes.
Details opens the server check details: the address and the URL checked, each step's result, the server's name and version, and the certificate's subject, names, issuer, validity dates, SHA-256 fingerprint and validation result. If the secure connection failed before the server sent a certificate, it says so instead. It never shows the pairing code.
Bouncer never accepts a certificate the PC doesn't trust, and never falls back to plain HTTP or follows a redirect. If your organisation uses its own certificate authority, it has to be installed in Windows' certificate store first (ask your administrator).
| What the check says | What to do |
|---|---|
| "Couldn't find …" | Check the address for typos, and check the PC's network connection. |
| "…its vault isn't ready", "…can't reach its database" (from 0.5.7) or "…the Bouncer server behind it isn't answering" | The server is running but cannot serve. Tell your administrator; there is nothing to fix on the PC. |
| "… refused the connection" | Check the address, including any port number. |
| "This PC can't get to …" or "… didn't answer in time" | Check the address and your network connection, then Retry. |
| "… answered, but not over HTTPS" | Use the server's https:// address. |
| "The server's certificate isn't from a certificate authority this PC trusts" | Ask your administrator. If they use their own certificate authority, it must be installed on the PC. |
| "The server's certificate expired …" or "isn't valid yet" | Ask your administrator to renew it, or check the PC's date and time. |
| "The server's certificate is for a different name" | Check the address. Use the name the certificate is for, which Details shows. |
| "This address sends Bouncer on to …" | Enter the Bouncer server's own address. |
| "… isn't a Bouncer server" or "This Bouncer server uses API …" | Check the address with your administrator. The app or the server may need updating. |
If pairing fails
| What the app says | What to do |
|---|---|
| "This code has expired or was already used." | Ask for a new code. Each works once, for a few minutes. |
| "That doesn't look like a pairing code. It has 12 letters and numbers." | Check you typed or pasted the whole code. |
| "Can't reach this address." | Check the address and your network connection. |
| "This address answers, but it isn't a Bouncer server this app can pair with." | Check the address with your administrator. The server may also need upgrading. |
| "Too many wrong codes." | Wait up to 10 minutes, then try again. Your code still works if it hasn't expired (codes last 5 minutes unless your administrator chose another time); otherwise ask for a new one. |
| "Bouncer can't use the camera." | Allow camera access for Bouncer in Android settings, or tap Enter the code instead. |
| "That isn't a Bouncer pairing code." | You scanned a different QR code. Scan the one bouncer-admin device pair shows. |
| "Your server only pairs phones that keep their approval key in secure hardware, and this phone's key isn't." | This phone can't pair with this server. Use another phone. |
| "This phone can't keep a fingerprint- or face-protected key in secure hardware, so biometrics can't confirm each signature here." | Tap Pair without biometrics. |
| "This phone couldn't make a key that needs your fingerprint or face." | Set up a fingerprint in Android settings, or tap Pair without biometrics. |
| "Your server doesn't accept keys that need your fingerprint or face for every signature." | Tap Pair without biometrics, or ask your administrator. |
| "This phone couldn't make its approval key. Unlock it, then try again." | Unlock the phone and try again. A screen lock must be set. |
| "Your server paired this phone, but the phone couldn't save the pairing." | Ask your administrator to run the bouncer-admin device revoke command the message shows, then pair again with a new code. |
After a refusal, the app says either "Nothing was paired." or "Your existing pairing was kept."
Answer requests
When someone asks for access to a resource you're an approver for, the request comes to every device you've paired. Answer it on any one of them.
Where requests show up
- Inbox. Open Bouncer: the Inbox tab lists everything "Waiting for you", with a count. Each card says who wants what and how long is left to answer. "Nothing waiting" means there's nothing to answer.
- Android notifications. A notification arrives even when Bouncer is closed. On the lock screen it says only "Access request pending" and "Unlock your phone to see the details". Once the phone is unlocked it shows who wants what. The notification carries only a random ID; the app fetches the details from your server. If it can't, it says "Couldn't load the details. Open Bouncer to review it."
- Windows notifications, while Bouncer is running in its window or the tray. Choose Open to see the request. The tray icon shows how many requests are waiting.
Read the request
A request opens with one line saying who wants to do what, for example "deploy-bot wants to read prod-db-password". Under it:
- The reason, labelled as the requester's own words and "not checked by Bouncer". Treat it as a claim, not a fact.
- Who is asking: a person, an automation (a script, service or AI agent), or a host. "Your own request" or "Your own automation" means it's yours.
- The requesting app, exactly as the requester reported it, or "No app reported". The icon follows that text and isn't proof of the app.
- The credential, with Read or Save · N fields. Read means the requester wants to read the value. Save · N fields means it wants to write new values into that many fields, not read them.
- What approving does, in one sentence. For a read: the requester can read the credential until access ends, anything already read can't be taken back, and open sessions may continue. For a save: one update of the named fields, and no read access.
- The time left to answer, for example "4 minutes left to answer". This is not how long access lasts; see Approvals and access duration.
Tap More information for the source host, the network address the server saw, the requester key, what your approval signs, and the request ID. Each detail is marked Verified, Observed or Reported by requester, so you can tell what Bouncer checked from what it was told.
If you weren't expecting the request, deny it.
Approve
- Check Access for. It starts at what was asked for, marked Requested. On a phone, tap Change to pick another length (How long access lasts). Windows cannot change it: Approve gives the length asked for, so answer on your phone to choose another length.
- Tap Approve. On a phone the button names the length, for example Approve 1 hour or Approve 15 min; for a save it says Approve save.
- Confirm it's you if the device asks:
- Android: the phone must be unlocked. If you chose fingerprint approvals when pairing, put your finger on the sensor.
- Windows: Windows Hello asks for your PIN, face or fingerprint.
- You should see Approved for the length you chose, with when access ends. The requester can now use the credential.
On Windows you can also use the keyboard. Esc denies. Enter approves only when nothing has keyboard focus. If a button has focus, Enter presses that button, so Enter on Deny denies. Windows Hello still asks either way.
Deny
- Tap Deny. You get Deny this request? with two choices:
- Deny: "You know about this request, but it shouldn't go ahead."
- I don't recognise this: deny it and mark it as not recognised in the approval log.
- You should see Denied. The requester sees that it was denied.
If you choose I don't recognise this, the app shows Denied and flagged
and explains that someone else may have that requester's key. It shows the
commands your administrator can run on the server: one to revoke that
requester's key, and bouncer-admin revoke --all to end every grant and
revoke every token at once. Tell your administrator.
On Windows, Deny signs straight away with Windows Hello. There is no Deny this request? step or I don't recognise this choice. If you do not recognise a request, deny it on your phone so it is flagged in the approval log, or deny on Windows and tell your administrator.
Approve or deny from an Android notification
You can add Approve and Deny buttons to request notifications:
- Open Settings.
- Under Notifications, turn on Approve from notifications.
It's off by default. The phone signs this change and saves it on your server, so you need to be online to turn it on.
Then:
- Approve from a notification approves for the requested duration only. To choose another length, tap the notification to open the request.
- The phone still has to be unlocked, and asks for your fingerprint if you chose that when pairing.
- Every request notification has Review, which opens the request. A resource can refuse approval from notifications; its notifications then offer only Review. Approve is also left out when the requested duration isn't allowed, or when it's your own request on a resource that needs another approver.
- A save request's notification says "One-time save" and offers Approve save.
iPhone alerts and Windows notifications have no approve or deny buttons.
On Windows
The Windows app approves only after you turn on Windows Hello approvals. Until then, a request shows Approve on another device, and you answer it on another paired device that can approve, such as your phone. The footer under the buttons says "Approving signs with Windows Hello on this PC, and so does denying."
Some resources only accept approvals from a key that's kept in secure hardware and asks for your fingerprint or face every time. A Windows Hello key doesn't meet that today, so on those Windows says "This credential needs a key with a fingerprint or face check that's kept in secure hardware", names your devices that have one, and offers only Deny. A phone whose key doesn't ask for a fingerprint or face shows the same notice, with Approve turned off.
From 0.5.7, a resource can also require a hardware key that checks it's you each time it's used. Its notice says "This credential needs a key kept in secure hardware that checks it's you each time it's used". See Device keys for the different key rules and the limits of Windows TPM checks.
When you can't approve
| What you see | Why, and what to do |
|---|---|
| Another approver has to approve this | It's your own request (or your own automation's), and the resource needs someone else to approve those. You can still deny it. |
| This request expired | Nobody answered in time. Nothing was granted. The requester can ask again. |
| Already approved, Already denied or Cancelled | Someone answered on another device, or the requester cancelled. Nothing to do. |
| This phone couldn't check this request | What's on screen doesn't match what was asked, so the phone won't approve or deny it. Reopen it. If it still doesn't match, decide on another device or tell your administrator. |
| This phone wouldn't sign it ("This phone couldn't sign it just now"), and trying again doesn't help | The resource may only accept approvals from a key that asks for your fingerprint or face every time. If you paired this phone without Confirm every signature with biometrics, it can't approve that resource. Set up biometric approvals, or approve on another device. You can still deny. |
| This version can't approve it | The request uses something newer than your app. Update the app. |
| Couldn't send your decision | The phone couldn't reach the server. Check your network connection, then try again. |
Problems with the approval key (a locked phone, a cancelled fingerprint check, "Android needs a fresh unlock") are in Troubleshooting.
When a message says "Nothing was approved or denied", that's exactly what happened: your device sends a decision only after it has signed it.
Approvals and access duration
Bouncer keeps two clocks apart: the time an approver has to answer, and how long the access lasts.
The time to answer
When someone asks for access, the request waits for an approver for a limited time. The app shows it as "N left to answer" on the request and in the inbox. Your administrator sets how long requests wait. By default it's 15 minutes, and a server can set anything from 1 minute to 24 hours.
If nobody answers in time, the request expires and nothing is granted. The app says "This request expired" and that nothing was granted. The requester can ask again.
The time to answer says nothing about how long access lasts.
How long access lasts
When you approve, you choose how long the access lasts. The request shows Access for with the length the requester asked for (for example "Access for 1 hour", marked Requested), and on a phone the button says Approve 1 hour. To choose another length, tap Change. You get How long? with:
- the quick choices your server offers. By default these are 5m, 15m, 1h, 6h, 24h, 7d and Always (see Standing access). A choice the resource doesn't allow is shown greyed out with the reason, for example "Not allowed for prod-db-password. Its policy allows up to 24 hours.";
- Custom…, for any whole number of minutes, hours or days from 1 minute up to the resource's limit (at most 365 days).
If you pick a longer time than was asked for, the app asks you to confirm (Longer than requested), and the approval records that it's longer.
The access you approved is called a grant. It appears under Grants with its end time, and you can end it early there with Revoke.
Standing access ("Always")
Your server may offer Always, described in the app as "Standing, until you revoke it". It's in the default list unless your administrator turns it off. Always is experimental and may change or be removed, so choose a time limit instead. If you see standing grants, check them with your administrator.
What happens during a grant
For a stored secret or API key, Bouncer doesn't hand over the secret once and walk away. The requester gets short-lived tokens that can only read that one secret. Each token lasts a few minutes (5 minutes by default; the request says how long), and Bouncer issues new ones until the grant ends.
When the grant ends, or you revoke it:
- Bouncer stops issuing tokens and revokes the ones it already issued, so new reads stop.
- A value that has already been read can't be recalled. If the requester copied the secret somewhere, it still has it. If you think it was misused, change (rotate) the secret where it's used.
- Open sessions may continue. For example, a database connection opened with the secret may stay open until the database closes it.
The app says this in the request ("Anything already read can't be taken back, and open sessions may continue") and again when you revoke.
SSH access
For an SSH host, the requester gets a short-lived SSH certificate for one account, never a stored key. There is no value to view or copy. A certificate expires no later than the grant's end. If you revoke early, a host refuses certificates already issued only once it fetches Bouncer's updated revocation list. Until then, or until expiry, they can start new connections. In 0.5.6 and earlier, hosts can't fetch a new list while OpenBao is unavailable. From 0.5.7, Bouncer serves the list from its database during an OpenBao outage, once it has read the CA public key (issue #281; see SSH revocation). Bouncer does not cut off a connection already open.
Saving new values (store requests)
Some requests ask to save new values into a secret, rather than read it. The request says "wants to save new values to" the credential and lists the field names, never the values.
- Approving allows one update of those fields, sent within a short window shown on the request.
- The saved values stay after that window. The window only limits when they can be sent.
- Approving a save doesn't let anyone read the secret, and you never see the new values. They go straight to the secret store; Bouncer doesn't keep them.
Deny a save if you weren't expecting the change.
A short example
Alice's deploy script asks for prod-db-password for 1 hour, with the reason
"Nightly schema migration". The request waits up to 15 minutes. Bob, an
approver, opens it after 3 minutes, changes the duration to 15m because the
migration is short, and approves with his fingerprint.
- The request is answered: nothing more happens on the 15-minute answer clock.
- The grant runs for 15 minutes from Bob's approval. The script gets 5-minute tokens, renewed until the grant ends.
- After 15 minutes, new reads stop. If the script wrote the password to a log file, that copy still exists, so Bob would rotate the password.
See and end access
The Grants tab shows the access that is in force for the resources you're an approver for, and the history of every decision. You can end any active grant early.
Active grants
Open Grants, then Active. Each grant shows:
- who has access to what, for example "deploy-bot → prod-db-password";
- the action and the length approved, and when it ends ("Read · 1 hour, until 14:30"), with the time left;
- who approved it, on which device, and whether in the app or from the notification;
- when the last token was issued.
Grants with an end time are under Time-limited. Grants approved with Always are under Standing, with their review date. Always is experimental and may change or be removed, so choose a time limit instead. If you see standing grants, check them with your administrator (see Standing access).
A grant leaves Time-limited at its end. A standing grant whose review date passes without your administrator re-confirming it shows as "Suspended" from that moment, with no Revoke: it gives no more access, and the requester has to ask again. The app doesn't wait for the server to tell it.
Revoke a grant
- In Grants, Active, find the grant and tap Revoke.
- Revoke this grant? says who loses access to what, and how early.
- Tap Revoke to confirm.
- You should see "Revoked. deploy-bot no longer has access."
Bouncer stops issuing tokens at once and asks OpenBao to revoke the ones already issued, so new reads stop. If OpenBao cannot confirm a revoke, Bouncer retries until it succeeds or the token expires (5 minutes by default). For SSH access, a certificate already issued keeps working at a host until that host fetches Bouncer's updated revocation list or the certificate expires. In 0.5.6 and earlier, hosts can't fetch a new list while OpenBao is unavailable. From 0.5.7, Bouncer serves the list from its database during an OpenBao outage, once it has read the CA public key (issue #281; see SSH revocation). A value already read cannot be recalled. If you think it was misused, rotate it where it is used. Open sessions may continue.
Revoking doesn't need your approval key, so it works on any paired device, including a Windows PC without Windows Hello.
History
Grants, then History, lists every decision, newest first, with filters: All, Approved, Denied, Revoked and Expired. Entries read like:
- "Approved by Bob on Bob's Pixel, in the app · 15 minutes (asked for 1 hour)"
- "Denied as not recognised by Bob on Bob's Pixel, from the notification · asked for 1 hour"
- "Revoked by Bob on Bob's Pixel after 6 min of 15 minutes"
- "Expired unanswered after 15 minutes · nothing was granted"
- "Viewed prod-db-password (you, Bob's Pixel)", for a value viewed in the app
An entry that names no person ("Revoked after 6 min of 15 minutes") was ended by the requester or by an administrator on the server.
The full approval log is on your organisation's server. The app shows the part that concerns you.
Your own requests
Your own requests aren't here. They're on the Requests tab; see Ask for access.
Ask for access
If your administrator lets you ask for a resource, you can ask from the app. An approver gets your request, and you see the answer in the app.
People usually ask from the app when they want to view a credential
themselves. Scripts and agents ask through the bouncer command-line tool or
the MCP server instead, with their own requester key.
Make a request
- Open the Requests tab and tap New request. On Windows, choose New request… from the tray menu, or New request in the window.
- Under Resource, tap Select resource and choose what you need. Search looks at names, descriptions and folders. Each one shows its kind (stored secret, stored API key or SSH access) and its description, and its folder when you search. If some lengths are not allowed, the form names them under How long with the longest time the resource allows.
- Under How long, choose a length, or Custom. Lengths the resource doesn't allow are shown greyed out with the reason. Your approver can choose a shorter or longer time than you ask for.
- Under Reason, answer Why do you need it? in up to 280 characters. Your approver sees it as your own words.
- Tap Send request.
The form also tells you how you'll use the resource once it's approved, for example "You can view it in the Library once your grant is active, if this server allows it", or "Once approved, use it from the CLI with your requester key."
If you're an approver for the resource yourself, the form says the request will also reach you, labelled Self-approval. Whether you may approve it depends on the resource's policy.
Wait for the answer
You see Waiting for approval, with the time left for an approver to answer. "Your approvers have been notified. If nobody answers within 15 minutes, the request expires and you can ask again." To withdraw it, tap Cancel request.
When it's approved, you see Approved for the length the approver chose, and when your access ends. If they chose a different length, it says what you asked for. For a stored secret, it also shows the command to use it from your computer:
bouncer exec prod-db-password -- <command>
Replace <command> with the program that needs the secret. If you use the
bouncer command-line tool, your administrator can show you how to run it.
Your requests
The Requests tab lists what's Waiting and what's Recent, with a status for each: Active, Ended, Revoked, Denied, Expired or Cancelled. For example:
- "Approved by Bob for 15 minutes, until 14:30. You asked for 1 hour."
- "Today · denied by Bob · asked for 1 hour"
- "Today · nobody answered within 15 minutes"
If the request is refused
| What you see | What to do |
|---|---|
| "Choose the resource you need." | Pick a resource first. |
| "The server didn't accept this reason. Change it and send again." | Change the reason and send again. |
| "This resource isn't ready in the vault. Ask the operator to finish setting it up. Other resources can still be used." | From 0.5.7: ask your administrator to finish the resource's OpenBao setup. |
| "Add a short reason. Your approver reads it before deciding." | Write a reason. |
| "Keep it to 280 characters." | Shorten the reason. |
| "Remove the hidden or control characters, so your approver sees exactly what you wrote." | Retype the reason rather than pasting it. |
| "You can't ask for this resource any more. Choose another." | Your administrator has changed who may ask for it. |
| "That length isn't allowed for prod-db-password now. Choose another." | The resource's limits changed. Choose again. |
| "Couldn't reach your Bouncer server." | Check your network connection, then try again. |
View, save and share credentials
The Library tab lists the credentials you may ask for, approve or own, in folders. Depending on how your server is set up, you can also view a credential's value, save new values into it, and make your own credentials to share.
All of this is off until your administrator turns it on for a resource. If you don't see an option described here, that's the likely reason.
Browse the Library
- Open Library. Credentials are grouped in folders; ones without a folder are under Unfiled. Credentials others shared with you are under Shared with me.
- Search the library looks at names, descriptions and folders, never at values.
- Tap a credential for its Details: type, folder, description, who issues it, how long each token lasts, the longest access you can ask for, and Your access.
Your access says where you stand, for example No grant, Waiting for approval, "Active · 42 min left", or You approve this. From there you can Request access, Request again, or Open request.
These ownership and sharing labels are from 0.5.7. In 0.5.6 and earlier, Shared by followed by a name gives the credential's owner, and the other labels described here do not appear.
The small icons and labels beside each credential tell you separate facts:
- Owned by you or Owned by alice names the owner. Something you own can also say Shared with others.
- Shared by bob names the person who last changed the sharing that gives you access, if your role lets you see who that was. Owners and Managers may see who else shared it. Viewers and Editors see only the owner's name, so the app doesn't repeat it beside Owned by alice.
- Shared directly with you, or Via and a group's name (for example Via family), says how you have access. Sharing with a group doesn't make the group the owner. The credential's Sharing section lists every way you have access, and your role.
- Config-managed means the credential comes from your administrator's server configuration. It has no individual owner.
Some roles can't see who shared an item, and older servers don't say. The app then shows only how you have access, and doesn't guess. Ownership unavailable means the server didn't say who owns the item.
A folder's labels sum up the credentials you can see in it, including those in folders inside it. Mixed ownership means they have different owners, or are managed in different ways; the folder itself still has no owner. A folder says Ownership unavailable if the server didn't say who owns any one of them. Folders only organise credentials; they don't give anyone access. Ownership and sharing labels are separate from who approves requests, from your role, and from whether a grant has ended or been revoked.
View a value
Viewing is the one place the app shows a secret. Your administrator turns it on per resource, in one of two ways: for people who hold an active read grant for it, or for its approvers.
- Open the credential in the Library (or in Grants, under Secrets you have access to).
- Read the warning: "Anyone who sees this value has it. Viewing can't be undone."
- Tap Show value. The key uses its normal check: a standard Android key only needs the phone unlocked; a biometric key asks for fingerprint or face, and a Windows Hello key asks for Windows Hello. The device signs the view, and your server records it in the log ("Viewed prod-db-password").
- The value hides again after 30 seconds, or when you leave Bouncer. Tap Hide to hide it sooner.
Copy puts the value on the clipboard, and Bouncer clears it from the clipboard after 30 seconds, if it's still there. How safe copying is depends on the device:
- Android: the copy is marked sensitive, so Android doesn't show it in its clipboard preview. The clearing only happens while Bouncer is still running: if you close Bouncer, or Android stops it, within those 30 seconds, the value stays on the clipboard until you copy something else over it.
- Windows, from 0.5.1: the copy is kept out of clipboard history (Win+V) and isn't synced to your other devices by cloud clipboard. Bouncer also clears it when you quit Bouncer and when Windows ends your session (signing out or shutting down). If Bouncer crashes or is ended from Task Manager, it can't clear the copy, and the value stays on the clipboard until you copy something else. If Windows won't take the protected copy, nothing is copied and Bouncer says so.
- Windows, 0.5.0 and earlier: the copy is a plain one. Windows clipboard history and clipboard sync to other devices can keep it after Bouncer clears the clipboard. If you use either, turn them off (Settings > System > Clipboard) before copying a secret, or type it instead, or update to 0.5.1.
On Android and Windows, the screens that show or take a value are protected from screenshots and screen recording in the normal app, unless you turn on Allow screenshots (see Privacy settings).
If you can't view a value, Your access says why:
| Message | Meaning |
|---|---|
| Hidden: "Show and Copy appear once you have an active read grant." | Ask for access first. |
| Viewing is off for this credential | Your administrator hasn't allowed viewing it on a device. Scripts and agents can still use it with a grant. |
| Nothing to show | It's SSH access, which uses a new certificate for each connection. There's no stored value. |
| Your grant only saves values | A save grant lets you save new values, not read them. |
| Nothing is stored yet | The secret store has no value for it yet. Save one first. |
| This grant isn't yours | Only the person who holds a grant can view with it. |
Edit a credential's values
If the button says Replace (new version) rather than Edit, this credential keeps a version history. Use Save a replacement below; its form differs from the one described here.
Where you're allowed to save new values into a credential from this device, its Details screen has an Edit button (from 0.5.2). That's the owner or an Editor of a personal credential, or an approver of a resource your administrator lets you save into. Grants, under Secrets you have access to, opens the same form from a row marked Save. On Windows this needs Windows Hello approvals.
- Open the credential in the Library and tap Edit.
- The fields it already has are listed by name, empty and hidden. Opening the form doesn't fetch anything.
- Type a new value only in the fields you want to change. A field you leave empty keeps its current value: Bouncer sends only the fields you typed in, and the others aren't touched. A field can't be removed here.
- If you may also view the value, Load current values fills the form with what's saved, hidden. It's the same as Show value: you confirm it's you, and the log records it as a view. A loaded value you leave as it was isn't sent again, and loaded values go after 30 seconds, as a shown value does. If you may save but not view, you only replace values, and nothing is fetched.
- Tap Save and confirm it's you. After your fingerprint, face or Windows Hello, Bouncer sends the values once to your organisation's server, which stores them in the secret store. The app doesn't keep them.
- You should see "Saved" and the field names. The log records the save, never the values.
For a personal credential you own, Name, folder and type at the top of the form changes those. A personal credential keeps the fields it was made with, so you can't add new ones. For a resource from your server's configuration, Add a field adds a new field name.
Expire and replace a value
If your administrator has turned on version history (called lifecycle) for a credential or its storage area, its Details has a Versions section. It shows the version in use ("Version N is in use"), whether it has expired or is set to expire, and each older version's state, dates and who made the change. Listing versions doesn't fetch any values. "Saved (date) outside Bouncer" means Bouncer has no record of who saved that version; it doesn't tell you who changed the value.
Verification on 18 November 2026: the operations in these steps were
checked through the server's API with fake data, against a server built
from unreleased source at main commit 79335c2. The steps have not yet been
run in the app itself; button and label names come from the app's source.
Versions arrived in 0.5.3. The device-key checks in this section need 0.5.7 on both the app and the server. Builds from source made before the version bump still report 0.5.6+33, so the version number alone doesn't show whether a build has these checks. Ask your administrator which source commit your app and server were built from.
For a resource from your server's configuration, its approvers can expire it. Replacing it also needs your administrator to allow app saves and self-approval. For a personal credential, its owner, Editors and Managers can expire or replace it.
These changes need a key that checks it's you every time: a biometric key on a phone or Windows Hello. The key must also meet the credential's own key settings. If a button is missing, the reason can be your permissions, this device's key or the installed version. The administrator chapter has the full permission table.
Expire now or schedule expiry
- In Library, open the credential's Details and find Versions.
- Check which version is in use. To stop Bouncer handing out the value now, tap Expire now, read the warning and tap Expire. Confirm it's you when the device asks.
- To expire it later instead, tap Schedule expiry, pick a future date and time, and confirm it's you. Check the scheduled time it shows afterwards. Remove scheduled expiry removes it before it happens. To change the time, remove the schedule, then set a new one.
- Once it has expired, you should see Expired: waiting for a replacement. Bouncer hands nothing out for it, and never uses an older value instead.
The value stays in OpenBao's history. Bouncer tries to revoke the tokens it issued for the value, including tokens it handed out that nobody has used yet, and retries any that fail. Anyone who copied the value still has it, and an API key from another system still works there until it's revoked at that system. Sessions already open don't close. A version's expiry is separate from a grant ending or a standing grant's review date.
Save a replacement
- Open the credential's Details, check Versions, then tap Replace in Versions, or the Replace (new version) button that takes the place of Edit.
- Type a new value in at least one field. A field you leave empty keeps its current value. This form doesn't load the current values; Show shows only what you type.
- Tap Save replacement and confirm it's you.
- You should see "Saved as version N", with the new version number. Check Versions again. The credential keeps its ID, name, folder and sharing, and grants that already exist can use the new value.
If it's refused:
- "This credential changed. Check the current version and try again." Someone changed it while you were editing. Go back to Details, check the version in use and start again.
- A message that a replacement would remove an old version's value for good means OpenBao's version limit would be exceeded. Ask your administrator to review it. The app has no way to approve removing it.
- The server says OpenBao's answer was lost. The save may have worked. Check Versions before you try again. If it worked but Bouncer could not record it, you will see "Saved (date) outside Bouncer", without who saved it. For a personal credential, tokens that were handed out but not yet used may still read the old value, because Bouncer didn't revoke them when OpenBao's answer was lost.
View an old value
Only the owner of a personal credential can view an old version's value, and only where its storage area allows values to be shown. For a resource from your server's configuration, its approvers can, where viewing in the app is turned on. Can reveal the value, given when a credential is shared with you, doesn't cover old versions.
- In Versions, tap View on the older version. It only appears if you're allowed and this device's key is suitable.
- Check the version number and read the warning: "This is an old value, not the one in use. Each view of it is logged on its own."
- Confirm it's you.
The view is signed and logged separately from ordinary views. A value that was deleted, destroyed or removed in OpenBao can't be shown. Viewing an old value doesn't make it the version in use, and doesn't restore access to an expired credential.
Make your own credential
If your server is set up for personal credentials, you can make credentials you own and share them.
- In Library, tap New personal credential.
- Choose what you're adding, such as Password, API key or SSH private key. If none fits, choose Secret bundle / other. Bouncer sets up the usual fields for that type (see the table below). On a server older than 0.5.0 the type still sets up the fields, but it isn't saved.
- Fill in:
- Name: up to 64 standard keyboard characters, kept exactly as typed;
- Folder: where it shows in your Library. Folders only organise; they don't change who can use it. My credentials means no folder;
- Storage area, only if your server has more than one;
- Fields: the type's fields, each with a label and "Saved as" the field name. Fields marked (optional) can be left empty or removed. Add a field adds your own, with a field name and a value.
- Under Access, choose Approval required (you approve each request).
- Under Shared with, Add a person or Add a group by their ID, and choose a role for each: Viewer (can find it and use it), Editor (can also save new values) or Manager (can also share it). Tick Can reveal the value to let them view it. To keep the credential to yourself, don't add anyone under Shared with.
- Tap Review, check You're authorising, then Verify and create and confirm it's you.
- You should see "Created. Only who you chose can use it."
The values go once to your organisation's server, and the app doesn't keep them.
The fields each type starts with
| Type | Fields (optional ones in brackets) |
|---|---|
| Password | (username), password, (url) |
| API key | api_key, (url) |
| Access token | token, (url) |
| Certificate only | certificate, (chain) |
| Certificate + private key | certificate, private_key, (chain), (passphrase) |
| SSH private key | private_key, (public_key), (passphrase) |
| Encryption / signing secret key | secret_key |
| Public / private key pair | private_key, public_key, (passphrase) |
| Recovery / backup codes | recovery_codes, (account), (url) |
| Authenticator / OTP seed | otp_seed, (account), (url) |
| Secret bundle / other | one field you name |
Keys, certificates and recovery codes take several lines, and keep every line exactly as you paste it. Bouncer never trims or changes a value.
Changing the type
You can change the type from the Type row at the top of the form. Everything you've typed stays. If a field you filled in has no place in the new type, Bouncer asks first, and that field stays as one of your own, with the same name and value.
If you see "Personal credentials aren't on yet", your server isn't set up for them; ask your administrator.
Change or end sharing
Open the credential's Details. Under Sharing:
- Change sharing updates who has access. It applies from now on.
- Rename or move changes only its name, folder or type.
- Disable stops everyone using it until you Enable it again.
- Delete removes it.
Disabling or deleting revokes the tokens already handed out where possible, but a value someone already revealed can't be taken back. Change it at its source if that matters.
"Always approved"
The Access choice also offers Always approved, which lets the people you share with use it without asking. Always approved is experimental and may change or be removed, and a server may refuse it. Choose Approval required instead. If you see credentials shared as Always approved, check them with your administrator.
Hidden and shown values while you type
On the create and edit forms, a username, account or website is shown as you type it. A password, private key, token, passphrase, seed or recovery code is hidden. Each hidden value has its own Show button (an eye) to check what you typed; tap it again, or Hide, to hide it. With a keyboard, Tab from the field to the button and press Enter or Space. A screen reader announces it as "Show Password, Hidden" or "Hide Password, Shown".
Show only shows what you typed on this device. It doesn't fetch a saved value or contact your server. A field you add yourself is hidden while you type unless you untick Hide this value as I type.
If you switch apps while typing
From 0.5.2, on Android and Windows, what you've typed stays when you switch to another app or minimise Bouncer, so you can look something up and come back. It's kept only in Bouncer's memory, never saved on the device. Any value you chose to show is hidden again when you come back (unless you turn off Hide values when switching apps, below), and on a phone the form is covered in the app switcher.
What you've typed is cleared when:
- you lock your device, or it locks itself;
- you sign out or switch to another Bouncer server;
- your server stops accepting this device;
- you leave the form and choose Discard. If you've typed anything, leaving asks first;
- Android or Windows closes Bouncer.
On iPhone, what you've typed is cleared whenever Bouncer goes to the background, because the iPhone app can't yet tell switching apps from locking the phone. The Mac app, still in development, does the same.
Privacy settings
Settings has a Privacy group. Its settings are kept on this device only.
Hide values when switching apps
On unless you turn it off.
- On: when you switch away from Bouncer, any value you chose to show (a typed value, or a credential's value from Show value) is hidden again.
- Off: a value you chose to show stays shown when you come back. A credential's value from Show value still hides after its 30 seconds, however long you were away, and isn't fetched again.
Either way, what you've typed is kept as described above, and locking your device, signing out and your server's permissions work exactly the same.
Allow screenshots
On Android and Windows only, and off unless you turn it on.
- Off: the create and edit forms, and a shown value, are kept out of screenshots and screen recordings.
- On: those screens can be captured like any other. A screenshot of a value contains that value, so turn it on only when you need to, and turn it off again afterwards.
Changing it takes effect straight away, even with one of those screens open. It doesn't depend on Hide values when switching apps. If your server records what devices report, a screenshot or recording Bouncer notices on one of those screens is still recorded in History, marked as allowed by this setting. Bouncer says nothing on screen when that happens.
iPhone and Mac don't have this setting: iOS doesn't let an app block screenshots, and it isn't available on the Mac yet. An internal test build doesn't have it either, because it never blocks screenshots.
What the apps can't do yet
Folders can be made, but not renamed, moved or deleted. A credential can be moved to another folder with Rename or move, if it's a personal credential you own.
Replace, lose or remove a device
Each paired device has its own approval key and its own entry on your server. Ending a device's pairing (revoking it) stops it seeing or approving anything. You can revoke the device you're holding by signing out. Only an administrator can revoke another device.
Getting a new phone or PC
- Pair the new device with a new pairing code.
- Check it works: open a request on it, or look in its Settings under Your other devices for the old one.
- On the old device, open Settings and tap Sign out, then confirm. Bouncer asks your server to revoke the old device, then removes the pairing and approval key from it.
Pairing first means there's no gap when nobody can approve.
If the old device is already gone (broken, wiped or traded in), ask your administrator to revoke it, as for a lost device.
A lost or stolen device
Tell your administrator straight away. They find the device with
bouncer-admin device list and revoke it with bouncer-admin device revoke.
After that it can't see or approve anything, even if someone unlocks it.
Then:
- Pair a replacement.
- Look in Grants at what the lost device approved. Revoke anything you don't want to keep running. Time-limited grants it approved before it was lost run until they end unless someone revokes them. Revoking the device ends any Always grants it approved.
- If you think someone used it to approve something, tell your administrator.
They can end every grant at once with
bouncer-admin revoke --all.
Someone holding your phone can't approve while it's locked. Once it's unlocked, anyone holding it can approve, unless you chose fingerprint approvals when pairing. That's why revoking it quickly matters.
Sign out
Settings, then Sign out. The app explains what happens:
- Bouncer asks your server to revoke this device, then removes the saved pairing and approval key here. This device stops getting requests.
- If the server can't be reached, the pairing is removed from this device
only, and the device may stay active on the server. The message shows the
bouncer-admin device revokecommand, with this device's ID, for your administrator to run. - Time-limited access this device approved runs until it ends.
After signing out, the app is back at the pairing screen.
Switch to another Bouncer server
Settings, then Switch Bouncer server, then Continue. You need a pairing code from the new server.
Your current pairing stays usable until the new one is verified and saved. Cancelling, or a failed setup, keeps it. After a successful switch, Bouncer asks the old server to revoke this device. If the old server can't be reached, ask its administrator to revoke the device there.
"This phone was removed"
If the app says This phone was removed (or This PC was removed), your server no longer accepts the device: someone revoked it. It can't see or approve requests. If you didn't expect that, check with your administrator. To use the device again, tap Pair again and pair with a new code.
"This phone's approval key is gone"
The server still has an approval key for this device, but the device no longer holds it. This can happen after a system restore. On an iPhone, changing Face ID or Touch ID retires the key. On Android, changing your fingerprints retires a key that needs your fingerprint ("This phone's key stopped working").
The device can't approve or deny until you pair it again, which makes a new
key. Before you tap Pair again, copy the bouncer-admin device revoke
command the app shows, and give it to your administrator, so the old pairing
is removed from the server too.
Remove the app completely
Sign out first, then uninstall. The install pages for Android and Windows have the steps, including the Windows Hello passkey that Windows keeps.
Troubleshooting
Problems you can fix from the app side, by what you see. Pairing problems are on Pair the app with your server, and approval refusals on Answer requests.
If nothing here helps, ask your administrator, or see Support.
Can't reach the server
"Can't reach your Bouncer server", or Offline under Server in Settings.
From 0.5.7, a brief "Reconnecting…" notice can appear at the bottom of the screen when you unlock your device or return to Bouncer, while the connection comes back. If the server still can't be reached after a few seconds, the app shows "Can't reach your Bouncer server".
- Check the device is connected to a network that reaches your Bouncer server.
- If your organisation uses a VPN for Bouncer, check it's connected on this device.
- Tap Try again.
Nothing is approved or changed while the app is offline. Requests wait on the server for their time to answer, so you can still answer them once you're back. Settings shows when the server was last reached.
The server is running but can't serve
These messages mean nothing is wrong with your device. Tell your administrator (whoever runs your Bouncer server). There's nothing to fix on the phone or PC, and no need to pair again.
| The app says | What's wrong |
|---|---|
| "Your Bouncer server returned an error" | From 0.5.7: the server answered with an error. Tell your administrator what you were doing. |
| "Your Bouncer server can't reach its database" | From 0.5.7: the server cannot reach PostgreSQL. Your administrator must fix it. |
| "Your Bouncer server's vault is sealed" | The vault (OpenBao, where the server keeps credentials) is sealed, usually after a restart. Your administrator must unseal it |
| "Your Bouncer server can't reach its vault" | The vault is stopped or out of the server's reach |
| "Your Bouncer server can't sign in to its vault" | The vault refused the server's own sign-in |
| "Your Bouncer server isn't answering" | Its address answers, but the server behind it doesn't: it's stopped or restarting |
Tap Try again once your administrator says it's fixed. Their side is in When Bouncer is unavailable.
No notifications
On Android
- Open Bouncer's Settings, and under Notifications tap Notification settings. If it says notifications are turned off for Bouncer, turn them on in Android settings.
- Android 13 and later ask for permission to show notifications. If you chose Not now when pairing, turn notifications on there.
- Battery savers can delay notifications. If they come late, let Bouncer run unrestricted in Android's battery settings for the app.
- Open Bouncer. Requests always show in the Inbox, notification or not.
If Settings says Push notifications are off in this build, this copy of the app was built without its notification settings. Requests show only when you open the app. Ask for a normal build.
On Windows
- Bouncer must be running. Check for its icon in the notification area (the tray; it may be under the ^ arrow). If it isn't there, start Bouncer Desktop from the Start menu. Windows has no push to a closed Bouncer.
- Check Settings > System > Notifications in Windows: Bouncer and notifications in general must be on, and Do not disturb off.
- While the PC is locked, notifications only say "Access request pending" and "Unlock this PC to see the details".
The phone won't approve or deny
When the phone can't use its approval key, the app says why. Nothing was approved or denied in any of these cases.
| What you see | What to do |
|---|---|
| Your phone is locked | Unlock it, then try again. |
| Android needs a fresh unlock | On Android 12 to 14, some face unlocks and Smart Lock don't count for Bouncer's key. Lock the phone, unlock it with your PIN, pattern, password or fingerprint, then try again. |
| Not confirmed | You cancelled the fingerprint check, or it timed out. Try again. |
| Too many attempts | Wait a moment, or lock the phone and unlock it with your PIN, pattern or password. |
| Bouncer wasn't on screen | Keep Bouncer open while you confirm. |
| Fingerprint check isn't available | Check a fingerprint is set up in Android settings. |
| Another confirmation is open | Finish or cancel the other fingerprint check. |
| This phone's key stopped working | Your fingerprints changed, so Android retired the key. Pair again. |
| This phone couldn't use its key | Unlock the phone and try again. If it keeps happening, pair again. |
Windows Hello problems
| What you see | What to do |
|---|---|
| "Windows Hello was cancelled. Nothing changed." | Try again. If you answered No to "Let Bouncer Desktop create and use passkeys?", turn Bouncer Desktop on under Settings > Privacy & security > Passkeys > Let apps create and use passkeys. |
| "Windows Hello couldn't make a passkey for Bouncer Desktop." | Set up a Windows Hello PIN under Settings > Accounts > Sign-in options, and check the passkeys setting above. |
| "Windows Hello approvals need a PC with a security chip (TPM)." | This PC can't approve. Approve on another paired device. |
| "Windows Hello didn't sign. Nothing was sent." | Try again. |
A request disappeared
Requests wait for a limited time. If nobody answers in time, a request expires and nothing is granted. It also leaves your inbox when someone answers it on another device, or the requester cancels it. Grants, then History, shows what happened to it.
The camera doesn't open
Allow camera access for Bouncer in Android settings, or tap Enter the code instead. Bouncer uses the camera only to read the pairing QR code. The Windows app doesn't use a camera.
Windows: a plugin DLL is missing
You started the portable ZIP's Bouncer.exe from inside the ZIP, or copied
it on its own. Extract the whole ZIP with Extract All and run
Bouncer.exe from the extracted folder, with its DLLs and data folder
beside it.
Windows: "Windows protected your PC"
The portable ZIP isn't signed, so SmartScreen doesn't recognise it. Choose More info, then Run anyway, if the file came from your organisation. The MSIX installer avoids this, once its certificate is trusted.
The app looks wrong after an update
Check the version in Settings under About. If Bouncer starts on the pairing screen after an update, the old app was removed before the new one was installed, so the pairing was lost. Pair again, and ask your administrator to revoke the old pairing.
Connecting scripts, agents and hosts
These pages are for developers and operators who want a script, a build job, a server or an AI agent to use secrets that Bouncer guards. The program asks; a person approves on their phone or PC; then the program gets the secret for a limited time.
The pieces
bouncer, the command-line client. It lists what you may ask for, files requests, waits for the decision, and runs a command with the secret handed to it.bouncer-mcp, a Model Context Protocol (MCP) server. MCP is the standard way AI agent clients (Claude Code, Claude Desktop and others) call external tools.bouncer-mcpgives an agent tools to ask for access and use secrets, but no tool that approves.- A requester key. Every program that asks needs its own requester and key, made by the server's administrator (admin for short). The key goes in a private file; it never goes on a command line.
How a request flows
- The program files a request: a resource, a duration and a reason. (
bouncer request, or the MCP toolrequest_access.) - The resource's approvers get a notification. One of them reviews the request on their phone or PC and approves, shortens or denies it. The device signs that decision with a key that never leaves it.
- The server records a grant: permission to use that resource until a set time.
- While the grant lasts, the program asks Bouncer for a short-lived OpenBao token (5 minutes by default), and reads the secret from OpenBao with it.
bouncer execand the MCP toolget_secretdo this for you. - The grant ends at its time, or earlier if someone revokes it. Tokens already issued are revoked too.
This is the flow for a fresh approval. Two experimental features give access without a new approval: an existing standing grant (Always) can be used again, and a personal credential set to Always approved lets the people it's shared with use it through their own requester key without asking. Keep both off, as Approvals and access duration describes.
If OpenBao is unavailable when a grant ends, revoking the tokens already issued can be delayed, so check what bouncer revoke reports. Ending a grant never affects a value that was already copied, or a session that's already open.
A program can never approve its own request. Only a signature from a paired device approves.
Setting up a program
- Install the CLI.
- Set up a requester with the key your admin gives you.
- Use the CLI, or connect an AI agent through MCP.
- Read Patterns for workloads and agents before you put this in a pipeline.
For SSH hosts, keep revocations up to date on every destination. Exit codes and errors and the CLI reference have the details.
Platform status
| Client | Status on 17 November 2026 |
|---|---|
| Linux CLI and MCP server (x86_64) | In the private release as a static tarball with an installer, and as .deb and .rpm package files. Not yet public, and there's no package repository yet |
| Windows CLI and MCP server (x86_64) | Since 0.5.1, as a zip with a per-user installer, in the private release. Not yet public, and not code-signed yet |
| macOS CLI | Not available, and not tested |
Some features are Linux-only: bouncer exec --file (it uses a Linux in-memory file) and bouncer self-update. bouncer exec --stdin works on Linux and Windows.
Platforms and status says which releases are published.
Install the CLI
Linux (x86_64)
The Linux release contains bouncer, bouncer-mcp and bouncer-admin as static binaries. They run on any x86_64 Linux, including Debian, Ubuntu, Fedora and Alpine, with nothing else installed except the system's CA certificates. (A slim container image may lack them; install its ca-certificates package.)
Before you start: get these three files into one empty folder. There's no public download page or package repository yet. The files are in Bouncer's private release, so ask whoever gave you access to Bouncer for them (Get Bouncer):
SHA256SUMSinstall.shbouncer-cli-<version>-x86_64-linux.tar.gz
Then:
grep ' install.sh$' SHA256SUMS | sha256sum -c -
sh install.sh
bouncer --version
- The first line checks the installer before you run it.
install.shchecks the tarball againstSHA256SUMS, checks every file inside it, and installsbouncerandbouncer-mcp. It installs to~/.local/binas a normal user, to/usr/local/binwhen run as root (sudo sh install.sh), or to--prefix DIR. It downloads nothing and never touches your key.- If it says
~/.local/binisn't on yourPATH, add it as it shows.
Expected result: bouncer 0.5.0+27 (bouncer.v1), with your release's version.
bouncer-admin stays in the tarball. It only belongs on the Bouncer server.
Or install the .deb or .rpm
The release also has the packages, bouncer-cli_<version>-1_amd64.deb and bouncer-cli-<version>-1.x86_64.rpm. Download the one you need with SHA256SUMS, check it with sha256sum -c SHA256SUMS --ignore-missing, and install the file:
sudo apt install ./bouncer-cli_<version>-1_amd64.deb # Debian or Ubuntu
sudo dnf install ./bouncer-cli-<version>-1.x86_64.rpm # Fedora
There's no apt or dnf repository to add yet, so the package manager won't find updates by itself: install each new release's package the same way.
If a checksum doesn't match, the installer stops and installs nothing. Download the files again; if it still fails, don't use them, and tell whoever publishes your releases.
Updates
| How you installed | How to update |
|---|---|
install.sh | Install the new release the same way. bouncer self-update exists, but only works with release builds that have an update key built in; current builds say "This build has no update key built in" |
.deb or .rpm | Install the new release's package file the same way. Updates through apt or dnf need a package repository, and none is public yet |
bouncer self-update checks a signed release manifest and each binary's checksum, keeps the old binaries for --rollback, and refuses to touch a copy that a package manager owns.
Build from source
If you have the Rust toolchain the repository pins:
cargo build --release -p bouncer-cli -p bouncer-mcp
The binaries are target/release/bouncer, target/release/bouncer-admin and target/release/bouncer-mcp.
Uninstall
rm -f ~/.local/bin/bouncer ~/.local/bin/bouncer-mcp ~/.local/bin/.bouncer.old ~/.local/bin/.bouncer-mcp.old
shred -u ~/.config/bouncer/key
rm -r ~/.config/bouncer
Use /usr/local/bin (with sudo) or your --prefix folder if you installed there. The .old files exist only after a self-update. Ask your Bouncer admin to disable the requester as well, so the key can't be used from a copy elsewhere.
Windows (x86_64)
From 0.5.1, bouncer.exe and bouncer-mcp.exe run natively on x86_64 Windows 10 and 11. They aren't code-signed yet, so Windows SmartScreen may warn about them.
Before you start: get these three files into one folder. As on Linux, they're in Bouncer's private release, so ask whoever gave you access to Bouncer for them:
SHA256SUMSinstall-windows-cli.ps1bouncer-cli-<version>-x86_64-windows.zip
Then, in PowerShell, as the user who'll run Bouncer (no administrator rights needed):
powershell -NoProfile -ExecutionPolicy Bypass -File .\install-windows-cli.ps1
- The installer checks the zip against
SHA256SUMS, and every file inside the zip against the zip's own sums. If one doesn't match, it installs nothing. - It installs both programs to
%LOCALAPPDATA%\Programs\Bouncer CLI\binand adds that folder to your ownPATH(not the machine's). It never touches your key.
Then open a new PowerShell window, so it picks up the new PATH, and run bouncer --version.
Expected result: bouncer followed by your release's version, such as bouncer 0.5.2+29 (bouncer.v1).
bouncer-admin isn't in the zip: it only runs on the Bouncer server's own machine.
Saving your key on Windows
bouncer key save reads the key from standard input and saves it to %LOCALAPPDATA%\bouncer\key, readable only by your Windows account and encrypted with Windows' data protection (DPAPI) so that only your account can decrypt it:
Get-Content .\web01.key | bouncer key save
Remove-Item .\web01.key
Set-Content -Encoding ascii "$env:LOCALAPPDATA\bouncer\server" https://bouncer.example.com
bouncer refuses a key file that anyone other than you, SYSTEM or Administrators may open. DPAPI stops another Windows account opening a copy of the file; anything running as you, and administrators, can still open it.
What's different on Windows
execgives a secret in an environment variable (--env) or on standard input (--stdin).--fileis Linux only, andbouncernever writes a secret to a temporary file.- There's no
bouncer self-update: run the next release's installer the same way.
How this was checked
The --version output is from the 0.5.0 binaries built from the source for this guide. The installer's behaviour is from scripts/release/install-linux-cli.sh and the project's release notes (docs/releases/linux-cli.md), which record it being checked on fresh Debian, Ubuntu, Fedora and Alpine containers. We didn't rerun the installer for this page.
The Windows section is from scripts/release/install-windows-cli.ps1, docs/releases/windows-cli.md and the CLI README's Windows notes in the source. On the project's Windows CI runner, the build script builds the zip and installs it into a temporary folder, without changing PATH, to check it; we didn't install it on a PC for this page.
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.
Use the CLI
This page shows the everyday bouncer commands. The resource IDs and field names are examples; bouncer resources shows yours. The full option list is in the CLI reference.
There is no dedicated command that prints a secret. bouncer exec delivers values to a child command through its environment, standard input or a Linux in-memory file. That command can still print or log the values, so check its output with a fake secret before you use a real one (Patterns for workloads and agents).
See what you may ask for
bouncer resources
It lists each resource's ID, name, kind, field names, the durations it offers, whether it accepts new values (WRITE), and anything open now: your pending request or the grant exec would use. It never shows a value. bouncer resources --json gives the same for scripts.
Ask for access
bouncer request prod-db-password --for 15m --reason "Run the March billing migration"
Expected result: the request ID, then two lines about it:
req_01jbx3k9m2p4q6r8s0t1v3w5y7
Asked for Production database password (prod-db-password) for 15 minutes. The approver has until 2026-11-15T06:43:32Z to decide.
Wait for the decision with: bouncer wait req_01jbx3k9m2p4q6r8s0t1v3w5y7
The request ID alone goes to standard output, and the other two lines go to standard error. So in a script, capture the ID and use it in the commands below:
REQ=$(bouncer request prod-db-password --for 15m --reason "Run the March billing migration")
--foris a whole number and a unit (30s,15m,6h,7d), oralwaysfor a standing grant where the server allows it. Ask for the shortest time that does the job.--reasonis up to 280 characters. The approver reads it before deciding, labelled as reported by you, so say what the task is.--hostand--clientchange the machine name and program name shown to the approver. They are also labelled as reported, never verified.
Wait for the decision
bouncer wait "$REQ"
| Outcome | Message | Exit code |
|---|---|---|
| Approved | Approved by Alice on Alice's phone. Grant grt_..., for 15 minutes. | 0 |
| Denied | Denied by Alice on Alice's phone. | 3 |
| Nobody decided in time | 4 | |
| Cancelled | Cancelled. | 5 |
Or ask and wait in one go: bouncer request prod-db-password --for 15m --reason "..." --wait.
wait keeps going through short network outages or a server restart, for up to 5 minutes.
Run a command with the secret
bouncer exec prod-db-password -- ./migrate.sh
exec finds your active grant, fetches a short-lived OpenBao token, reads the secret, and runs the command with the values in its environment. It names each variable after the field, in capitals: the field password becomes PASSWORD. Before running the command it tells you which variables it set, never their values:
bouncer: Set from kv/apps/billing/db-password: PASSWORD.
The command's exit code becomes bouncer's. The token expires by itself. Values copied by the command, and sessions it opens, can outlive it.
Choose how the command gets the value
| Option | What it does |
|---|---|
--env NAME=field | Sets the environment variable NAME from field. Repeatable. Once you use it, only the fields you name are passed |
--file NAME=field | Puts the field in a private in-memory file (never on disk, mode 0600, and locked so it cannot be changed) and sets NAME to its path, such as /dev/fd/3. Linux only |
--stdin field | Gives the field to the command on its standard input, without a trailing newline. One field only. Linux and Windows (from 0.5.1) |
--prefix P | Puts P in front of every default variable name |
Examples, with a fake secret whose field is api_key:
bouncer exec demo --env DEMO_KEY=api_key -- sh -c 'test -n "$DEMO_KEY" && echo set'
bouncer exec demo --file KEYFILE=api_key -- sh -c 'test -s "$KEYFILE" && echo readable'
bouncer exec demo --stdin api_key -- sh -c 'v=$(cat); test -n "$v" && echo "read from stdin"'
bouncer: Set from kv/apps/demo: DEMO_KEY.
set
bouncer: Set from kv/apps/demo: KEYFILE (a file).
readable
bouncer: Set from kv/apps/demo: standard input.
read from stdin
Use --stdin or --file for tools that won't read the environment. docker login --password-stdin is a common case:
bouncer exec registry --stdin password -- docker login registry.example.com --username ci --password-stdin
Which fields become variables
Field names come from whoever wrote the secret, so by default exec only sets a variable whose name looks like a secret's: KEY, TOKEN, SECRET, PASSWORD or PASSPHRASE, or ending in _KEY, _TOKEN, _SECRET, _PASSWORD, _PASSPHRASE or _ID. Other fields (url, username) are skipped, with a notice. Name them yourself to use them:
bouncer exec prod-db-password --env DB_HOST=host --env DB_USER=username --env DB_PASSWORD=password -- ./migrate.sh
exec refuses to run, and runs nothing, if:
- a default variable name is protected: a name that changes how programs run or where they connect, such as
PATH,LD_PRELOAD,GIT_*,*_PROXY,VAULT_*andBOUNCER_*(bouncer exec --helplists them all); - the variable is already set;
- two fields would get the same name.
To set a protected name on purpose, name it with --env and add --allow-env-name NAME.
No grant yet
With --reason, exec files a request itself and waits for approval, then runs:
bouncer exec prod-db-password --for 15m --reason "Run the March billing migration" -- ./migrate.sh
Without --for, it asks for the resource's first duration and says so. With --no-request (or without --reason) it never asks, and exits 8 when there's no active grant. Use that from cron and CI.
List and end your grants
bouncer grants # active grants
bouncer grants --all # including ended ones
GRANT=$(bouncer grants --resource prod-db-password --id-only | head -n 1)
bouncer revoke "$GRANT"
Expected result of revoke:
Grant grt_01jbx3n4q6s8t0v2w4x6y8z0a2 is revoked as of 2026-11-15T06:28:34Z. No new tokens can be issued for it.
Token iss_01jbx3q6s8t0v2w4x6y8z0a2b4, due to expire 2026-11-15T06:33:21Z: revoked at OpenBao
A secret value that was already read can't be recalled. If it was read, rotate it.
End a grant as soon as the job is done. It exits 10 if OpenBao didn't confirm every token's revoke; the grant is still ended.
Withdraw a request
bouncer cancel "$REQ"
The approvers' notifications are withdrawn.
Check on requests
bouncer status # your recent requests
bouncer status "$REQ" # one in full
Save a new value
For a resource that accepts writes (WRITE yes in bouncer resources), for example after you rotate an API key at its provider:
printf %s "$NEW_KEY" | bouncer put deploy-token --field token --reason "Rotated after the March incident"
bouncer put deploy-token --field token --file ./new-token.txt --reason "Rotated after the March incident"
put files a request that names the fields, never the values, waits for approval, then sends the values once. Other fields in the secret are kept. With several --fields, the input is a JSON object with one string per field. It exits 0 once saved, 3 if denied, 4 if the request expired.
SSH to a host
For an SSH host resource, bouncer ssh makes a new key, has Bouncer get it a short-lived certificate, and connects:
bouncer ssh web1-deploy --to web1.example.com --reason "Restart the web service"
bouncer ssh web1-deploy --to web1.example.com -- systemctl status nginx
The private key stays on your machine and is deleted afterwards. A revoke stops new logins on a host only once that host has fetched and installed Bouncer's revocation list and its sshd reads it through RevokedKeys. The host's timer tries every 15 seconds, but Bouncer can't confirm delivery, so bouncer revoke says NOT confirmed for each certificate. With --json, each one has "outcome": "unknown" and "pending": "krl_delivery". The certificate also expires at its own end time. An SSH session that's already open stays open. Follow Keep SSH revocations up to date to install and monitor the host's KRL pull service.
Not verified for this page: put and ssh weren't part of our test run. Their behaviour is from bouncer put --help, bouncer ssh --help and the CLI's tests.
Scripting
--jsonprints the server's answers exactly as they came. On an error, it still prints one JSON document on standard output and the explanation on standard error.bouncernever prompts and never reads the terminal, so it behaves the same in a shell, cron, systemd, CI or an agent.- Every failure has a specific exit code: see Exit codes and errors.
How this was checked
The messages on this page are checked against the CLI source. A historical 0.5.0 run with fake secrets has no retained transcript in this manual's evidence. The fake-data operator tests later reran exec reading a stored value and exec --no-request exiting 8 after a revoke. Resource names and IDs use the examples from this guide.
Keep SSH revocations up to date
An SSH host needs Bouncer's revocation list, called a KRL, to reject a certificate before its expiry. This page installs the supplied pull script and systemd timer on a Linux destination host. It assumes the SSH issuer and the host's resource are already set up with the SSH role kit, and that you have the host's CA and account changes ready but not yet turned on. You turn them on in step 4, after the first fetch.
The timer tries every 15 seconds. Delivery depends on a successful fetch and on the host's SSH daemon reading the installed list. Bouncer cannot confirm that each host has received a revoke. A session already open stays open after revocation or certificate expiry.
Before you start
Use a disposable host and fake accounts for the first check. You need:
- the matching server deployment kit, including
deploy/ssh-krl/, from the release you install (Get Bouncer); - root access to the destination host, with Bash, curl,
ssh-keygenand systemd available, and an independent way to administer it; - a working SSH host resource,
its separate OpenBao signer login, and the host's reviewed CA and account
configuration. The kit's
deploy/openbao-role-kit/ssh/README.mdcovers the issuer setup. A principal is an account name, not a host restriction: use a distinct non-root account name for each host; - HTTPS connectivity from the host to Bouncer, with the correct server name
and trusted certificate issuer. Use
BOUNCER_CA_FILEfor a private CA. No particular VPN is required; - access to
bouncer-adminon the Bouncer server to create a requester for this host. It uses the local admin socket, not the host's network login.
The host-trust helper mentioned in the role kit README is
scripts/ops/ssh-host-trust.sh in a matching source checkout. It is not
included in the server deployment kit. The host's CA and account trust need
separate preparation; installing these KRL files alone does not establish it.
Check the host's effective SSH configuration, including its Match blocks.
RevokedKeys must name /etc/ssh/bouncer/revoked.krl for the connections
that use Bouncer certificates. A setting in another matching block can
select a different file or turn this check off. Keep your existing admin
session and recovery route open while changing SSH trust.
Fetch a valid KRL before enabling that trust. If RevokedKeys names a
missing or unreadable file, OpenSSH refuses every public-key login, not only
Bouncer certificates. An empty placeholder with no working delivery does
not provide early revocation.
The names below are examples: resource web1-deploy, host requester
web1-krl, and destination web1.example.com. Use the host and account
recorded in your own inventory.
1. Give the host its own requester key
On the Bouncer server, in the Compose directory, capture just the key in a private file:
(umask 077; docker compose exec -T bouncer bouncer-admin requester add web1-krl --kind host > web1-krl.key)
The explanation goes to standard error; only the key goes to the file. Transfer that file to the destination host over your existing trusted admin route. On the destination host, as root:
install -d -m 700 /etc/bouncer
install -m 600 web1-krl.key /etc/bouncer/krl-host.key
Remove the transfer copies once the installed file is checked. Keep the key out of command arguments, chat and tickets. The pull script accepts key-file modes 600 or 400.
Only an active requester of kind host can fetch the revocation list. Being a host doesn't limit what the key can do: it can also ask for access to any resource whose policy allows it. If this host only fetches revocations, check each resource's requesters list and leave this requester out. A resource with no requesters list, or with "*", lets any requester ask.
2. Install the files and settings
On the destination host as root, from the unpacked kit's root directory:
install -m 755 deploy/ssh-krl/bouncer-krl-pull /usr/local/sbin/
install -m 644 deploy/ssh-krl/bouncer-krl.service deploy/ssh-krl/bouncer-krl.timer /etc/systemd/system/
install -m 600 deploy/ssh-krl/krl.env.example /etc/bouncer/krl.env
install -d -m 755 /etc/ssh/bouncer
Edit /etc/bouncer/krl.env so it has these values. The example file has the
same settings, plus an admin-socket option that applies only on the Bouncer
server's own machine. The requester key itself stays in its separate file:
BOUNCER_URL=https://bouncer.example.com
BOUNCER_KEY_FILE=/etc/bouncer/krl-host.key
BOUNCER_KRL_FILE=/etc/ssh/bouncer/revoked.krl
BOUNCER_KRL_MAX_AGE=120
# BOUNCER_CA_FILE=/etc/bouncer/server-ca.pem
The service loads this file with systemd's EnvironmentFile. Running the
pull script by hand does not load it automatically. Use the service for
the first fetch so it uses the same settings as the timer.
The deploy/ssh-krl/README.md in the 0.5.5 and 0.5.6 kits runs the pull script
directly for the first fetch. That does not load /etc/bouncer/krl.env, so
it stops with set BOUNCER_URL, reports STALE and does not enable the
timer. Follow the steps on this page instead. The README correction in
source is included from 0.5.7.
3. Fetch once, then enable the timer
On the destination host as root:
systemctl daemon-reload
systemctl start bouncer-krl.service
/usr/local/sbin/bouncer-krl-pull --check
Stop if the service fails or the freshness check is stale. Inspect its log before continuing:
journalctl -u bouncer-krl.service --since "10 minutes ago"
A successful fetch installs or retains a valid KRL and records its version
and fetch time. --check fetches nothing: it checks the local last-success
record. With the default paths and 120-second limit above, it must exit 0
and report a fresh fetch. It does not test the running SSH daemon.
Run by hand, --check uses the script's defaults, not krl.env. If you
change BOUNCER_KRL_MAX_AGE or the state folder there, base your monitoring
on the service's failures, which use your settings.
Only after that first fetch succeeds:
systemctl enable --now bouncer-krl.timer
systemctl list-timers bouncer-krl.timer
Verify the timer has a next run, the service keeps succeeding, and the KRL stays readable by the SSH daemon. The service runs once and exits, so between runs it shows as inactive even when it is working. Inspect its result and log, not just whether it is currently active.
4. Turn on the host's CA and account trust
Only after the first fetch succeeds, apply the host's CA and account trust
as the role kit README describes, with ssh-host-trust.sh or by hand, and
reload the SSH daemon. Keep your existing admin session open. Then check
the effective settings again, including Match blocks, as described under
Before you start, and log in once with a Bouncer
certificate before relying on it.
Check a revoke and its limits
From the requester's machine, use a fake host resource and account first:
bouncer ssh web1-deploy --to web1.example.com --reason "Check the SSH evaluation host" -- id -un
bouncer grants --resource web1-deploy --id-only
bouncer revoke <grant-id>
Use the grant ID from your own check. A committed revoke stops Bouncer
issuing another certificate for that grant. For certificates already issued,
the normal output says NOT confirmed. This output was captured with fake
data in the isolated check described below, with example identifiers substituted:
Grant grt_example is revoked as of 2026-11-17T23:38:44Z. No new tokens can be issued for it.
SSH certificate iss_example_1, due to expire 2026-11-17T23:43:43Z: NOT confirmed: it's in Bouncer's revocation list, and each host refuses it once it has fetched that list (normally within 15 seconds)
SSH certificate iss_example_2, due to expire 2026-11-17T23:43:43Z: NOT confirmed: it's in Bouncer's revocation list, and each host refuses it once it has fetched that list (normally within 15 seconds)
2 token(s) weren't confirmed revoked. They still expire on their own by the times shown.
With bouncer --json revoke <grant-id>, each affected entry in credentials
has "outcome": "unknown" and
"pending": "krl_delivery". Neither output confirms host enforcement. With
an unconfirmed certificate, bouncer revoke exits 10 even though the grant
cutoff committed. Inspect the report rather than treating that exit as a
failed cutoff.
Check the host service's log for successful fetches after the revoke and
run /usr/local/sbin/bouncer-krl-pull --check there. This checks delivery
freshness. It does not by itself prove that the running SSH daemon rejects a particular
certificate. Repeating bouncer ssh creates a fresh key and asks Bouncer
again, so that alone does not test a previously issued certificate either.
A full host-enforcement check needs an isolated test with that certificate.
The CLI's "normally within 15 seconds" is how often the host's timer tries to fetch the list when it can reach the server. It isn't a deadline, and it isn't a confirmation.
A host that can't reach Bouncer keeps the last list it installed. In 0.5.6, hosts are also stuck on their last list while OpenBao is sealed, out of reach, or refusing the login of Bouncer or of its SSH signer. In that case, if Bouncer and its database are up, the revoke still takes effect in Bouncer, but hosts can't fetch the new list until OpenBao recovers. Bouncer answers their fetches with HTTP 503, or HTTP 500 if it can't read the CA key. This comes from the source, and wasn't tested in the isolated run. From 0.5.7, Bouncer stores every SSH CA public key it has read, so hosts can fetch newly committed revokes while OpenBao is down, including after Bouncer restarts, as long as Bouncer and its database are up. An installation that has never read the CA, including one just upgraded from 0.5.6 that hasn't read it yet, can't serve a list until OpenBao answers once. In 0.5.5, a server that starts or restarts while OpenBao is unavailable stops instead, so hosts get no answer from it at all.
From 0.5.7, Bouncer records a CA rotation the next time it reads the CA public key successfully. It logs a warning, and the approval log export gets an ssh_ca_changed entry naming the old and new public-key digests. Bouncer keeps every CA public key it has seen, and every revoked grant stays in the list for each of them. The serial numbers of replacement certificates apply only to the CA that issued them. After upgrading, let Bouncer read the CA once before you rotate it: older serial records are tied to the first CA it reads. Bouncer can't rebuild a CA it never saw. Updating which CA a host trusts is always a deliberate step for the host's owner.
The revoke report from that release also includes krl_available while list delivery is pending. false means Bouncer can't build the list at the moment, and the CLI says so instead of estimating when hosts will fetch it. true means a list can be built, not that any host has fetched or enforced it. Older servers leave the field out.
Until a host installs a list that names them, or they expire, certificates that were already issued can still start new logins on that host. Neither the list nor expiry ends a session that's already open.
Monitor and recover delivery
Alert on bouncer-krl.service failures and stale fetches. The default
maximum age is 120 seconds. --check exits 2 if nothing has ever been
fetched or the last successful fetch is too old. A failed fetch keeps the
installed KRL; becoming stale does not automatically close SSH access.
From 0.5.7, BOUNCER_KRL_STALE_POLICY=keep makes this
existing behaviour explicit in krl.env. It is the default and only supported
policy: retain the last good list, report STALE and exit 2 after the freshness
limit. A misspelled policy exits 64. A revoke committed since the last good
fetch waits for the next successful fetch or certificate expiry.
| Symptom | What to check |
|---|---|
| No connection or a TLS error | Bouncer's address, DNS, the chosen network path, and whether the server's certificate name and issuer are trusted. Set BOUNCER_CA_FILE when needed |
| A local key-file error | The configured key path, readability and mode (600 or 400) |
| HTTP 401 or 403 | The key, the requester's enabled state and its host kind. Replace a lost or exposed key through the admin route |
| HTTP 404 | In 0.5.6: no SSH signer is configured. From 0.5.7: no signer is configured and no CA public key has been stored. Check the server's SSH settings |
| HTTP 500 | An error on the server, such as a database problem in 0.5.6 or a failure to read the CA key. Check the server's log with docker compose logs bouncer |
| HTTP 503 | In 0.5.6: Bouncer or OpenBao isn't ready. From 0.5.7: PostgreSQL is unavailable, or Bouncer has never read its SSH CA public key and OpenBao can't supply it. Follow When Bouncer is unavailable. The host keeps its installed list, and certificates missing from it keep working until the next successful fetch or until they expire. To stop Bouncer logins on a host sooner, delete the account's principals file under /etc/ssh/auth_principals/, or remove its trust as in Retire a host |
| An older KRL version is refused | Find out whether the server or its database was restored, and reconcile revokes made since the backup. The script keeps its newer installed list. Only after an intended restore or rollback, follow Reset host version state. Do not clear it just to silence an unexplained error |
| Fresh fetches, but a revoked certificate still logs in | Confirm which RevokedKeys the running SSH daemon uses for that connection, including Match blocks, and test with the same certificate. A fresh fetch alone is not an SSH configuration check |
After fixing the cause, start bouncer-krl.service again and repeat the
freshness and timer checks. If you change its environment file, the next
service run reads it; if you change the unit files, run systemctl daemon-reload
first.
Retire a host
The KRL file goes last, because an SSH daemon that still names a missing
RevokedKeys file refuses every public-key login.
-
Find the SSH daemon that serves logins. Keep your admin session open. Before running the host-trust helper, find the process ID of the daemon serving logins with
ss -ltnp | grep sshd, as root. Ifssh.serviceorsshd.serviceis active, the helper tries those units first. Runsystemctl show -p MainPID ssh.service sshd.serviceand check that one of them shows the same process ID. If neither is active, check the SSH daemon's PID file:sshd -T | grep -i pidfileThe named file must hold the process ID of the daemon serving logins. The helper does not check either identity.
-
Remove the host's Bouncer CA and account trust, then reload the daemon. If you applied the trust with
ssh-host-trust.sh, runssh-host-trust.sh --rollbackas root. It reloads the SSH daemon before it stopsbouncer-krl.timerand removes the CA and KRL. It keeps the KRL and exits 1 if the daemon could still be reading it. If you made the change by hand, first delete the account's principals file under/etc/ssh/auth_principals/, which stops Bouncer certificates at once without a reload. Then remove theTrustedUserCAKeys,RevokedKeysandAuthorizedPrincipalsFilelines you added, and reload the SSH daemon. -
Check CA trust and list references are gone. Check that no SSH configuration file still names Bouncer's CA or list. This should print nothing:
grep -rn 'bouncer/trusted-user-ca.pub\|bouncer/revoked.krl' /etc/ssh/sshd_config /etc/ssh/sshd_config.d/Check the effective settings for both the Bouncer account and your independent recovery account with
sshd -T -C user=<account>,host=<client name>,addr=<client address>. Include every connection detail yourMatchblocks test. Neithertrustedusercakeysnorrevokedkeysmay name a file under/etc/ssh/bouncer/. If you omit a detail aMatchblock tests, sshd skips that block, so the check can look clean when it isn't. Stop here if rollback fails or you cannot verify the listening daemon has stopped using those files. Keep the KRL and delivery working until the cause is fixed. The by-hand retirement commands are checked against the source; this sequence hasn't been run as written. -
Only after step 3 succeeds, stop delivery and remove the host's copy of the list, Bouncer's CA key and the host's requester key. If the helper already did part of this, these commands change nothing:
systemctl disable --now bouncer-krl.timer rm -f /etc/ssh/bouncer/revoked.krl /etc/ssh/bouncer/trusted-user-ca.pub /etc/bouncer/krl-host.keyBefore closing your admin session, open a new SSH session with your independent recovery key. If it is refused, restore an empty list at once from the open admin session:
install -m 644 /dev/null /etc/ssh/bouncer/revoked.krlAn empty list revokes nothing. It is safe here only because step 2 removed the principals files, so no Bouncer certificate can log in even if the running daemon still trusts Bouncer's CA. If a principals file for that CA is still in place, delete it first; otherwise a revoked certificate that hasn't expired could log in again. Other logins still go through the daemon's normal checks. Find which daemon or setting still names the KRL file, correct it, and test a new recovery login before proceeding or closing your admin session.
-
On the Bouncer server, disable the host's KRL requester:
docker compose exec -T bouncer bouncer-admin requester disable web1-krl
How this was checked
This procedure is checked against the source: the kit's pull script, service and timer, release packaging, host-trust checks, CLI and revoke report. 0.5.7 keeps the SSH CA public keys it has read and adds explicit stale-policy configuration and the report field described above; the hardened service and timer are unchanged. The initial 14 KRL pull checks passed with fake keys and a local stub server. The expanded 19 checks also pass, including the stale setting and deliberate restore reset with the installed list kept on fetch failure.
On 18 November 2026, a separate test run with fake data exercised the KRL procedure and its SSH issuer and account-trust prerequisites in a disposable Debian container with systemd as PID 1. It used a real OpenBao 2.7.2 dev sandbox, the built 0.5.6 server and CLI candidate, and the unmodified shipped pull script, hardened service and timer. Fake TLS, local transfers and a software stand-in for an approving device supplied the fixtures.
The same certificate was accepted before delivery and refused after the timer installed its revoke, with 285 seconds of validity left. An existing session stayed open. The default freshness limit detected staleness at 121 seconds; delivery failures, recovery and retirement also passed. The HTTP 503 check used a forwarder fault, not an OpenBao outage. These are observations from that isolated run, not a delivery deadline. This procedure hasn't been run on a real host or with the real apps.
Further isolated checks ran this chapter's commands and the kit README's commands from the source after 0.5.6, where the README is fixed. They created a requester, installed its key and fetched the first list, starting from clean states. The README in the 0.5.5 and 0.5.6 kits was not run. They also tested missing-KRL refusal and recovery. A separate check with an offline fake CA removed the principals file first in the retirement procedure while leaving the old daemon settings loaded. The empty-list undo restored the independent recovery login while the same revoked, unexpired certificate stayed refused. The listener and service PID examples were also run. That focused SSH check did not run Bouncer or OpenBao.
A further source build containing the changes now labelled 0.5.7 passed the existing
end-to-end systemd test with fake data on 18 November. Built before the
version bump, it still reported 0.5.6+33. OpenBao was stopped
and Bouncer restarted into that outage. New issuance was refused without
adding an issuance record. The timer delivered a committed revoke and the
same certificate was refused with 283 seconds left, while a session
that was already open kept working. After OpenBao recovered, an outage in the host's
connection to Bouncer's list endpoint left its installed list, version and
freshness record unchanged. The default 120-second limit
reported STALE at 121 seconds; scheduled recovery installed a newer list and
refused the same certificate with 171 seconds left. A separate recovery
login confirmed that the refusal wasn't sshd penalising the test's source
address. Retirement and
missing-list recovery also passed, and the development host's state was
unchanged after teardown. Automated server checks separately cover a fresh
start with no observed CA, an upgraded installation before its first CA
read, and audited rotations. These were isolated source builds and automated
tests.
Connect an AI agent through MCP
bouncer-mcp lets an AI agent ask a person for access to a secret, wait for the decision, and then use the secret. It speaks the Model Context Protocol (MCP) over standard input and output, so any MCP client can start it.
A requester key can't sign an approval. bouncer-mcp has no tool to approve, deny, pair or change policy. Its tools can make and cancel requests, revoke the agent's own grants, and save values once a save is approved, where policy allows it.
Give the agent its own requester of kind agent. Never give it your own key: a human requester's key can get access to a personal credential set to Always approved without anyone approving on a device (Approvals and access duration).
Before you start
bouncer-mcpinstalled on the agent's machine (Install the CLI). Installbouncerbeside it too, so the agent can deliver a secret to a command without fetching it throughget_secret. The command must keep the value out of its output and logs.- A requester of kind agent, made for this agent, and its key in a private file (Set up a requester). Use a separate file, for example
~/.config/bouncer/agent-key, so it isn't confused with your own key.
bouncer-mcp only runs with an agent's key. At start-up it asks the server who the key belongs to, and stops if it's a person's or a host's. That keeps the approver's label honest: the app shows "Your own agent", not "Self-approval", and the agent can't use grants you got for yourself.
1. Check the settings
BOUNCER_URL=https://bouncer.example.com BOUNCER_KEY_FILE=~/.config/bouncer/agent-key bouncer-mcp --check
Run this yourself, in a terminal. It prints for you, not for the agent. Expected result (with the address and paths changed):
Bouncer server: https://bouncer.example.com
Instance: Example home (example-home)
Requester: build-agent (rqr_01jbx1q3s5t7v9w1x3y5z7a9b1), an AI agent, owned by alice
Key file: /home/alice/.config/bouncer/agent-key
Run with: BOUNCER_URL=https://bouncer.example.com BOUNCER_KEY_FILE=/home/alice/.config/bouncer/agent-key /home/alice/.local/bin/bouncer exec <resource> -- <command>
The settings work. Agents using this server can ask for access; a human approves each request on their phone.
The Run with line is always printed. When bouncer-mcp finds the bouncer command beside it or on your PATH, it shows the command as above. Otherwise it says no bouncer CLI was found, so the agent can only read values with get_secret; install bouncer so the agent can use exec instead (Keep values out of the conversation).
With a host's key instead, it exits 7 and says how to make an agent requester.
2. Register it with your client
Claude Code:
claude mcp add bouncer \
--env BOUNCER_URL=https://bouncer.example.com \
--env BOUNCER_KEY_FILE="$HOME/.config/bouncer/agent-key" \
-- "$HOME/.local/bin/bouncer-mcp"
Check it's registered and starts:
claude mcp list
Expected result: a bouncer line that says it's connected. If it says it failed, run the --check command from step 1 with the same settings.
Clients that read a JSON config (Claude Desktop, or a project's .mcp.json). JSON doesn't expand $HOME or ~, so write your own home folder in full where this example has /home/alice:
{
"mcpServers": {
"bouncer": {
"command": "/home/alice/.local/bin/bouncer-mcp",
"env": {
"BOUNCER_URL": "https://bouncer.example.com",
"BOUNCER_KEY_FILE": "/home/alice/.config/bouncer/agent-key"
}
}
}
}
Restart the client, then check that its list of MCP servers or tools shows bouncer.
Only the key file's path goes in the client's settings. bouncer-mcp never reads the key from an environment variable, because MCP clients store those in their settings files, and a project's .mcp.json may be committed.
| Variable | Meaning |
|---|---|
BOUNCER_URL | The Bouncer server's address. HTTPS, or plain HTTP to this machine only |
BOUNCER_KEY_FILE | Required. The agent's key file. It must be private (chmod 600) |
BOUNCER_CA_FILE | Optional. Extra CA certificates (PEM) for Bouncer and OpenBao |
The tools
| Tool | Arguments | What it does |
|---|---|---|
list_resources | none | Lists what this agent may ask for, with each resource's durations, decision time and token lifetime |
request_access | resource, duration, reason | Files a request and returns at once with its ID, status (pending) and deadline. If the agent already has a pending request or an active grant (with at least 2 minutes left) for the resource, it returns that instead of asking again |
get_request_status | request_id | One request, without waiting |
wait_for_decision | request_id, optional timeout_seconds | Waits for the decision, 55 seconds by default and at most 120. If it's still pending, the agent calls it again |
get_secret | resource | For an active grant, fetches a short-lived token, reads the secret and returns its field values. Never returns the token |
list_grants | optional include_ended | The agent's grants |
revoke_grant | grant_id | Ends one of the agent's grants now |
cancel_request | request_id | Withdraws a pending request |
request_store | resource, fields, reason | Asks permission to save new values into a resource that allows writes. Field names only |
save_secret | request_id, values | After approval, saves the values once |
The usual flow is list_resources, request_access, wait_for_decision (repeated while pending), then either get_secret or the bouncer exec command the result suggests, and revoke_grant when done. The server gives the client this flow in its MCP instructions.
The approver sees the request as coming from the agent's requester, with the MCP client's name (for example claude-code via bouncer-mcp) and the machine's name, both labelled as reported by the requester.
Keep values out of the conversation
get_secret gives the values to the model. From then on they are in the conversation, and may be in the client's logs and the model provider's records. Revoking the grant doesn't take a value back; only rotating the secret does. Every get_secret result says so.
When the task only needs to run something with the secret, use the bouncer exec command that wait_for_decision suggests, when bouncer is installed beside bouncer-mcp. (--check shows the same command for the operator.) This avoids returning the value as an MCP tool result, but the child command can still print, log, save or send it. Its standard output and standard error may enter the conversation and the client's logs. Choose a command whose output you have checked with fake data; don't use env, shell tracing or a command that echoes credentials. Only give an agent access to secrets you'd be willing to rotate.
Logs
bouncer-mcp logs to standard error, one line per tool call: the tool's name, and for a refusal the first line of its message. It never logs arguments, values, tokens or the key.
How this was checked
The --check output, tool list and arguments are checked against mcp/src/main.rs and mcp/src/tools.rs. A historical 0.5.0 run has no retained transcript in this manual's evidence. The tools were not driven from a real MCP client for this page; the project's mcp/tests drive the real binary over standard input and output.
Patterns for workloads and agents
These patterns keep values out of arguments, shell history and files on disk. The command you run still gets the value, so check what it prints or logs with fake data first.
Never put a secret in a command's arguments
Every user on a Linux machine can read every process's arguments (ps, /proc/<pid>/cmdline). So this leaks the password even though Bouncer handed it over safely:
# Don't: the shell puts the value into mysql's arguments.
bouncer exec prod-db-password -- sh -c 'mysql --password="$PASSWORD" billing'
Use whatever the tool offers instead, in this order of preference:
- Standard input, if the tool can read a secret there:
bouncer exec ... --stdin password -- tool --password-stdin. - A file, if the tool takes a path:
bouncer exec ... --file DB_PASSWORD_FILE=password -- sh -c 'tool --password-file "$DB_PASSWORD_FILE"'. The single quotes matter: the variable only exists inside the commandbouncerstarts, so your own shell must not expand it. The path is not secret, so it's fine in the arguments. The file exists only in memory and disappears when the command exits. - An environment variable the tool reads itself:
bouncer exec ... --env MYSQL_PWD=password -- mysql billing.
exec does not put a value in the child's arguments itself. It passes through the child's standard output and standard error without redaction. Disable shell tracing and credential logging, and avoid commands such as env that print their environment. An agent that can choose arbitrary commands can also choose one that reveals the value.
Give each workload its own requester
One requester per agent, host or pipeline means:
- the approver sees exactly who is asking;
- you can disable one without affecting the others;
bouncer-admin requester listshows when each was last used.
Anyone who can read a key file can ask as that requester, so keep key files chmod 600, owned by the user that runs the workload.
Scheduled jobs and CI
Unattended jobs shouldn't file requests nobody will see. Approve a grant ahead of time, then let the job use it. File the request with the job's own requester key: only the requester that asked for a grant can use it. Both commands below run as the job's user, who owns the key file:
# Beforehand, with the job's key. An approver approves it on their phone or PC.
BOUNCER_KEY_FILE=/etc/nightly-export/bouncer-key bouncer request nightly-export --for 7d --reason "Nightly export, week of 16 November"
# The job, from cron, with the same key:
BOUNCER_KEY_FILE=/etc/nightly-export/bouncer-key bouncer exec nightly-export --no-request --env API_TOKEN=token -- /opt/export/run.sh
With --no-request, a job without an active grant exits 8 at once instead of waiting. Alert on that exit code.
Grants of a week or more are a trade-off: anyone holding the key can use the secret for that long. Keep them as short as the schedule allows, and scope each resource to one job.
Long-running services
bouncer exec reads the values once, when it starts the command. The command keeps them for as long as it runs, but the OpenBao token behind them expires within minutes, so the service can't read anything new later. A service that runs for weeks with a copied value has the same exposure as any static secret (Copied secrets).
Agents
- Use the MCP server with an agent requester, not your own key (Connect an AI agent).
- Prefer the
bouncer execcommand the MCP tools suggest overget_secretto avoid returning the value directly to the model. Check the command's output as described above. - Ask the agent to give the grant up with
revoke_grantwhen it finishes. - Give agents only secrets you'd be willing to rotate.
Ending access early
When a job finishes early, end its grant:
bouncer revoke "$(bouncer grants --resource nightly-export --id-only | head -n 1)"
This stops new tokens at once. It can't take back a value the job already read.
Containers
The static binaries run in any Linux container that has CA certificates. Mount the key file read-only, owned by the container's user with mode 0600, and set BOUNCER_URL and BOUNCER_KEY_FILE. Don't bake the key into an image, and don't pass it with -e BOUNCER_KEY=..., which shows it in docker inspect.
Exit codes and errors
bouncer and bouncer-admin share one table of exit codes, so a script can read any of them the same way. It's also printed at the end of bouncer --help.
Exit 16, database_unavailable, and exit 7 for resource_not_provisioned are from 0.5.7. Check the client build as well as the server. Older clients use
their own mapping for a server code they don't know, described below.
| Code | Meaning |
|---|---|
| 0 | Done. For wait, request --wait and exec: the request was approved |
| 1 | Something went wrong: the server couldn't be reached, failed (HTTP 5xx or 429), or sent something this version can't read |
| 2 | The command line was wrong |
| 3 | The request was denied |
| 4 | The request expired without a decision |
| 5 | The request was cancelled or superseded |
| 6 | The server refused: the key wasn't accepted, the caller isn't allowed, the object doesn't exist, or the input was invalid. Also: OpenBao refused a read with the issued token |
| 7 | Configuration: no server address, no key, a key file others can read, plain HTTP to another machine, or (for bouncer-admin) an admin socket that can't be opened. From 0.5.7, also a server resource whose role-kit setup needs repair (resource_not_provisioned) |
| 8 | No active grant for the resource, including a grant that has just ended |
| 9 | The deadline passed while the request was in a state this version doesn't know |
| 10 | Revoked, but OpenBao didn't confirm the revoke of every issued token. The grant is still ended |
| 11 | bouncer-admin revoke --all wasn't confirmed (no yes, or no --yes when not on a terminal) |
| 12 | The server is running, but its vault (OpenBao) is sealed (backend_sealed). An outage, not a refusal: the server's administrator must unseal it |
| 13 | The server is running, but can't reach its vault (backend_unreachable). An outage, not a refusal |
| 14 | The server is running, but its vault refused the server's own login (backend_auth_failed). An outage, not a refusal of your key: the server's administrator must fix the server's login |
| 15 | Can't reach the server: the proxy in front of it (such as tailscale serve) answered 502, 503 or 504 with no Bouncer error, because the server didn't answer. It's down or restarting |
| 16 | From 0.5.7: the server is running, but PostgreSQL is unavailable (database_unavailable). The server's administrator must check the database |
| 126 | exec: the command was found but couldn't be started |
| 127 | exec: the command wasn't found |
Once exec has started the command, the exit code is the command's own.
bouncer-mcp uses 0 for success, 1 when it cannot start or the MCP session fails, 2 for unknown arguments, 7 for a configuration problem (such as a key that is not an agent's), and 12 to 15 as above when the server cannot serve. From 0.5.7, it also uses 16 for a database outage. Inside an MCP session, errors are returned to the agent as tool errors it can read. From 0.5.7, resource_not_provisioned makes one call and returns an error saying the server's administrator must repair it, without retrying; the matching CLI exit is 7. When Bouncer can't serve, the tool error says it isn't a denial, says what's wrong, and asks the agent to tell the person it's working for.
Codes 12 to 16 are outages, not refusals (16 is from 0.5.7). Nothing is wrong with your key or your request, so don't rotate keys or treat them as an attack. Each message says who has to act, usually the server's administrator. See When Bouncer is unavailable.
Server error codes
When the server refuses something, it answers with an application/problem+json body that has a machine-readable code. With --json, bouncer prints that body as it came. The codes a requester is most likely to see:
| Code | HTTP | Meaning | Exit code |
|---|---|---|---|
unauthenticated | 401 | No key, or not a valid one | 6 |
requester_disabled | 403 | This requester has been disabled | 6 |
forbidden | 403 | A valid key, but not allowed to do this | 6 |
not_requestable | 403 | This requester may not ask for this resource | 6 |
not_found | 404 | No such object, or not visible to this requester | 6 |
invalid_body | 400 | The request doesn't match the API | 6 |
reason_invalid | 422 | The reason is empty, too long, or has hidden characters | 6 |
duration_not_permitted | 422 | The duration isn't allowed for this resource | 6 |
request_not_pending | 409 | The request was already decided, expired or cancelled | 6 |
grant_not_active | 409 | The grant has expired, been revoked or been suspended | 8 |
idempotency_conflict | 409 | The same idempotency key was used with a different request | 6 |
rate_limited | 429 | Too many attempts; try again later | 1 |
issuance_failed | 502 | Bouncer couldn't release a credential | 1 |
write_failed | 502 | OpenBao didn't save the values | 1 |
internal | 500 | Something failed on the server; its log has the details | 1 |
backend_sealed | 503 | The server is running, but its vault (OpenBao) is sealed | 12 |
backend_unreachable | 503 | The server is running, but can't reach its vault | 13 |
backend_auth_failed | 503 | The server is running, but its vault refused the server's own login | 14 |
resource_not_provisioned | 503 | From 0.5.7: this resource needs the server's administrator to repair its role-kit token role or policy. One call, no retries | 7 |
database_unavailable | 503 | From 0.5.7: the server is running, but PostgreSQL failed its readiness probe | 16 |
| (none: a bare 502, 503 or 504) | The proxy in front of the server got no answer from it | 15 |
A code this version doesn't know is read by its HTTP status: a 4xx is 6 (except 429, which is 1), and a 5xx is 1. A 4xx answer is the server saying no (The server said no: ...); a 5xx with a Bouncer error is it failing (The server couldn't do it: ...). The HTTP API reference lists every code.
Retries
bouncer makes up to four attempts at each call: the first, and up to three retries. It waits as long as the server's Retry-After says, or else 1, 2, then 4 seconds.
- Calls that are safe to repeat (reads, revokes, filing a request and fetching a token, which carry an idempotency key) are retried on a dropped connection, a timeout, and HTTP 429, 500, 502, 503 or 504.
- Every other call is retried only on HTTP 429 or 503, or when the connection failed before anything was sent.
- Never retried: the server's
backend_sealed,backend_unreachableandbackend_auth_failed, and (from 0.5.7)resource_not_provisioned. They need the server's administrator, sobouncersays so at once rather than after a minute of retries.
From 0.5.7, database_unavailable follows the HTTP 503
retry rule, with up to four attempts per HTTP call and Retry-After: 5.
An MCP tool reports the problem to the agent and asks it to tell the person it's working for. It doesn't ask the agent to keep calling the tool.
It never follows a redirect, so a key or token can't be sent on to another host.
How this was checked
The table is from cli/src/exit.rs and cli/src/http.rs, the retries from cli/src/client.rs, and the server codes and statuses from server/src/error.rs and the contract. The fake-data operator tests saw exec --no-request exit 8 after a revoke. The other exit codes are checked against source only.
The database case (exit 16) was checked against the source at commit b6acf52, including its CLI and MCP tests. It hasn't been run in a test with a live server.
Overview and prerequisites
These pages are for the person who installs and looks after a Bouncer server. If you only use the apps, see the app pages instead. If you connect scripts, agents or the command line to a server someone else runs, see Integrate.
What you are running
A Bouncer installation has three parts:
- The Bouncer server (
bouncer-server). It stores requests, checks signed decisions, keeps the approval log, and asks OpenBao for short-lived tokens. It handles plaintext when a device views or saves a secret, and when someone creates a personal credential, while OpenBao stores the values. - PostgreSQL, where the server keeps its records: people's devices, requesters, requests, grants and the approval log.
- OpenBao, where the secrets live. OpenBao is an open-source fork of HashiCorp Vault, managed by the Linux Foundation. Bouncer logs in with a scoped role that can issue resource tokens, read viewing paths, and read and write personal credential namespaces. Where enabled, it can also save resource values and read version metadata; from 0.5.7, it reads provisioning metadata too. Bouncer enforces the approval policy; OpenBao does not verify the person's decision.
There's a kit for each part. They come in a release download's compose kit, or in the source repository (Get Bouncer says which releases have a download):
| Folder | What it sets up |
|---|---|
deploy/compose | The Bouncer server and PostgreSQL 18, with Docker Compose or Podman |
deploy/openbao-role-kit | The role kit: Bouncer's narrow role on your OpenBao, with its login, its policies and one token role per resource. It also has the emergency stop, which cuts Bouncer off from OpenBao without needing Bouncer |
deploy/openbao | A dedicated single-node OpenBao, if you don't already run one |
requesters (CLI, MCP) phones and PCs
\ /
HTTPS (443) on your private network
|
HTTPS reverse proxy (the kit's examples use tailscale serve)
|
127.0.0.1:8080 bouncer-server
| | \
admin socket PostgreSQL OpenBao
(bouncer-admin) (socket only) (your own)
Requesters also talk to OpenBao directly: Bouncer hands them a short token, and they read the secret from OpenBao with it. So OpenBao must be reachable from the machines your requesters run on, not only from the Bouncer server.
Before you start
You need:
- A Linux machine or VM of your own for the Bouncer server, with:
- either rootful Docker Engine 25 or later with the Compose plugin, or rootless Podman 5 with
podman-compose. Rootless Docker doesn't work with this kit (see TLS and networking); - about 1 GB of free memory to run;
- if you build the image from the source rather than load it from a release download:
git, to fetch the repository, and 4 GB or more of memory while the image builds (3 to 10 minutes).
- either rootful Docker Engine 25 or later with the Compose plugin, or rootless Podman 5 with
- OpenBao 2.7 or later, reachable from the server and from your requesters. You need an admin token for it once, while you run the role kit. The kit also needs the
baocommand,jqand bash 4.4 or later on the machine where you run it. - A private network and HTTPS in front of the server, with a certificate your devices trust for the server's name. Any network your devices can reach works: a LAN, or a VPN. The kit's examples use Tailscale with
tailscale serve, but a VPN is optional (TLS and networking says exactly what was checked). Nothing in the kit opens a port to the internet. - At least one phone with the Bouncer app, to approve requests. A Windows PC with the Bouncer app can approve too, once it has a Windows Hello key.
Bouncer's config file and your role kit files describe your policy. Keep them in a Git repository you control (not the Bouncer repository), because whoever can change them controls what Bouncer allows.
Preparation checklist
Write down these choices before changing OpenBao or starting the containers. The memory and build-time figures above are planning estimates. Measure resource use and storage growth in your test deployment before sizing it for your workload.
| Check | What to have ready |
|---|---|
| Version and files | Choose a server release or source commit, and its matching image and kit. Keep the release guide and checksums with them. Check any feature marked as needing a later release or unreleased source before choosing (Get Bouncer). |
| Existing OpenBao | Record its address, certificate authority, KV version 2 mount and the paths Bouncer will use. Arrange the operator access needed for the role kit. Do not initialise an existing OpenBao again. If you need a new one, follow OpenBao for Bouncer. |
| Independent recovery | Make sure an operator can reach the host, administer OpenBao and obtain its recovery material without an approval from the Bouncer instance being recovered. Keep backup decryption and unseal material available independently too (Recovery). |
| Host and storage | Choose one of the container engines above. Record where the persistent database volume, config and secret files will live, and where backups will be copied off the server. Keep secret files outside the checkout (Install, Backup and restore). |
| Addresses and trust | Choose Bouncer's HTTPS name and OpenBao's address. Check the network path from phones, PCs and requesters to Bouncer, and from both the server and requesters to OpenBao. Plan certificate trust for each client; the names must match the certificates. A particular VPN is not required (TLS and networking). |
| First identities and policy | Choose the stable instance ID, first person, approvers and test requester. Match the resource ID, KV mount and path in Bouncer's config and the role kit. Use a fake credential first, and keep standing grants off, as in Configure the server. |
| Notifications | With the official apps, your server needs a service-account key authorised for the app's Firebase project; installing the app does not supply one. If that route is unavailable, leave push off and use the apps while open (Push notifications). |
| First verification and recovery drill | Plan to pair a device, request and approve access to the fake credential, use it and revoke the grant. Arrange off-server backups and an isolated restore drill before relying on the deployment (Pairing, Backup and restore). |
The order of work
- Set up OpenBao, or check the one you have: running, unsealed, with a KV version 2 mount.
- Install the server: the OpenBao role, the config, the secret files, the image, and the first start.
- Set up HTTPS and networking.
- Add people, requesters and devices, and pair the first phone.
- Try a request end to end, then run the kill switch once so you know it works.
- Schedule backups and set up health checks.
These pages call the kit's folder ~/bouncer, as a checkout of the source would be. If you installed from a release download, it's ~/bouncer-releases/bouncer-server-<version> instead (Install the server, step 1a).
Limits to plan for
Known limits lists what Bouncer doesn't do yet. Two matter for every installation: people are defined in the config file (there's no single sign-on yet), and a static secret that someone has read can't be taken back.
How these pages were checked
These pages describe Bouncer 0.5.7. Some example output comes from a fake-data 0.5.0 test; not every procedure has been run again since. Platforms and status separates source, release and installed versions.
The preparation checklist was checked against the source and existing instructions on 18 November 2026. It has not yet been followed as a new installation from scratch, and supplies no measured capacity or recovery time.
Two kinds of testing are mentioned on these pages:
- Our test run means what we ran ourselves while writing these pages: a throwaway copy of the kits on one machine, with fake secrets and made-up names, torn down afterwards. The install, pairing, a request, a backup, a restore, and a new OpenBao from first start to the role kit's check were run that way.
- The project's tests means the automated tests in the repository, such as the kits'
test-in-sandbox.shandtest-in-docker.sh. We say which ones we ran.
Each page ends with a "How this was checked" note. Where a page describes something that couldn't be run either way (a real push provider, TPM auto-unseal, a public certificate), it says so.
OpenBao for Bouncer
OpenBao stores the secret values. Bouncer's database holds metadata, but the running server handles plaintext when a device views or saves a secret, and when someone creates a personal credential. Its role can read viewing paths and personal credential namespaces, write configured save paths and namespaces, and issue short-lived tokens for requesters. OpenBao enforces that scope; Bouncer enforces the approval policy (How Bouncer protects access).
Set OpenBao up before you install the server. You can use an OpenBao you already run, or set up a dedicated one with deploy/openbao as this page describes. Either way, Bouncer reaches it through the narrow role that the role kit (deploy/openbao-role-kit) creates in Install the server, step 2.
Terms used on this page
- Sealed and unsealed. OpenBao encrypts everything it stores. When it starts, it is sealed: it can't read its own data until it is given the key to unseal it. While sealed, it answers nothing useful, so Bouncer can't issue any tokens.
- Unseal shares (Shamir). By default, the unseal key is split into several shares when OpenBao is first set up, and a minimum number of them, the threshold, is needed to unseal. This page uses three shares with a threshold of two.
- Root token. A token with every permission, which OpenBao prints once, when it is initialised. Bouncer never uses it.
- Admin token. Any token allowed to manage OpenBao's policies, token roles and login methods. The root token is one. The role kit needs one every time it runs.
- KV version 2. The OpenBao secrets engine Bouncer reads from. Each secret is a set of named fields at a path, for example the field
passwordatapps/billing/db-password. - Raft snapshot. A backup of OpenBao's own storage.
A dedicated OpenBao with deploy/openbao
deploy/openbao runs OpenBao 2.7.2 as a single Raft node in Docker. It is not highly available: after a restart it stays sealed until someone unseals it. Run it on a dedicated Linux VM with rootful Docker. Keep swap off or encrypted.
You need two machines for the steps below:
-
the OpenBao VM, with a copy of the Bouncer kit at
~/bouncer: a release download's compose kit, unpacked (Get Bouncer), or a clone of the repository (ask whoever gave you access to Bouncer for the repository link); -
your recovery workstation, a machine you trust. It needs:
sshaccess to the VM, and a network route to OpenBao's address (for example on the same Tailscale network), becausebaoandcurltalk to OpenBao directly;- its own copy of the Bouncer kit at
~/bouncer, the same way, for the role kit; - bash 4.4 or later (the role kit's scripts stop on anything older; macOS ships bash 3.2), the
baocommand,jq,curl,python3andage; - an
agekey pair that you already use for recovery material.
The unseal shares and the root token only ever exist on this machine, in memory or encrypted.
The commands use <identity> for your age private key file, <recipient> for its public key, and <vault folder> for a folder off the VM where the encrypted recovery file lives.
1. Start it
On the OpenBao VM:
sudo install -d -m 0755 /etc/bouncer/openbao
sudo install -m 0644 ~/bouncer/deploy/openbao/openbao.hcl /etc/bouncer/openbao/openbao.hcl
cd ~/bouncer/deploy/openbao
cp .env.example .env # set OPENBAO_API_ADDR to the address clients will use
docker compose up -d
sudo tailscale serve --bg --https=8443 http://127.0.0.1:8200
docker compose exec -T openbao bao status
OpenBao listens on 127.0.0.1:8200 on the VM, and tailscale serve puts HTTPS on port 8443 in front of it (TLS and networking). Never bind the plain listener to your LAN, and never publish OpenBao to the internet.
Expected result: bao status exits 2 and shows a new, empty vault:
Seal Type shamir
Initialized false
Sealed true
Storage Type raft
2. Initialise it once
Initialising creates the unseal shares and the root token. OpenBao shows them only once, so send them straight into encryption, never to a terminal or a file on the VM.
First check that age works with your key, and that the destination is writable. A failure after initialising can lose the only copy of the shares:
echo dummy | age -r <recipient> | age -d -i <identity> # prints "dummy"
touch <vault folder>/write-test && rm <vault folder>/write-test
Then, on the recovery workstation:
set -o pipefail
umask 077
ssh admin@openbao.example.com 'cd ~/bouncer/deploy/openbao && docker compose exec -T openbao bao operator init -format=json -key-shares=3 -key-threshold=2' |
age -r <recipient> -o <vault folder>/openbao-init.json.age
Check that the file decrypts and holds three shares and a root token, without printing any of them:
age -d -i <identity> <vault folder>/openbao-init.json.age |
jq -e '(.unseal_keys_b64 | length) == 3 and (.root_token | length) > 0' > /dev/null &&
echo "The file decrypts and holds 3 shares and a root token."
Expected result: that sentence, and nothing else. Keep a second encrypted copy somewhere else, and test that you can reach it.
Three shares encrypted to one key give you a backup, not three separate keyholders. If you want different people to hold the shares, encrypt each one to its holder instead.
3. Unseal it
After every restart, give OpenBao two of its shares. Each share goes as a small JSON object ({"key":"<share>"}) on standard input, so it never appears on screen or as a command-line argument. From the recovery workstation:
for n in 0 1; do
age -d -i <identity> <vault folder>/openbao-init.json.age |
jq -c --argjson n "$n" '{key: .unseal_keys_b64[$n]}' |
ssh admin@openbao.example.com 'cd ~/bouncer/deploy/openbao && docker compose exec -T openbao bao write sys/unseal -'
done
bao operator unseal doesn't work for this, because it reads the share from a terminal. Each bao write prints the progress; after the second share, sealed is false. Then check on the VM:
cd ~/bouncer/deploy/openbao
docker compose exec -T openbao bao status
Expected result: it exits 0, and shows:
Seal Type shamir
Initialized true
Sealed false
Total Shares 3
Threshold 2
Version 2.7.2
Storage Type raft
HA Enabled true
HA Mode active
Restart the container once (docker compose restart openbao), check that bao status says Sealed true again, and unseal it again. Then you know the procedure works before you need it.
4. Make a KV mount and a test secret
Bouncer reads secrets from a KV version 2 mount. On a new vault there isn't one yet. Use the root token for this first setup, read straight from the encrypted file into your shell, never printed. On the recovery workstation:
export BAO_ADDR=https://openbao.example.com:8443
read -r BAO_TOKEN < <(age -d -i <identity> <vault folder>/openbao-init.json.age | jq -r .root_token)
export BAO_TOKEN
bao secrets enable -path=kv -version=2 kv
printf '%s' 'not-a-real-secret' | bao kv put -mount=kv bouncer-test/hello value=-
bao kv get -mount=kv -field=value bouncer-test/hello
Expected result: Success! Enabled the kv secrets engine at: kv/, then the new secret's version 1, then not-a-real-secret.
Use this test secret as your first resource while you check everything works. In the role kit's resources file it is the line:
bouncer-test kv bouncer-test/hello
and in Bouncer's config a resource bouncer-test with kv: {mount: kv, path: bouncer-test/hello}. Add your real secrets once the role kit's check and a first request work.
5. Run the role kit, then revoke the root token
Keep the same shell open, with the root token in BAO_TOKEN, and follow Install the server, step 2. If you'd rather run the kit with less than root, its README shows how to make a scoped bouncer-kit-admin token from the root token (./setup.sh --print-admin-policy). Such a token is a child of the root token, so it stops working when you revoke root below. It can't be your way back in afterwards.
Before you revoke the root token, decide how you will get an admin token again. The role kit needs one every time it runs, and you may need it in a hurry: the emergency stop runs on OpenBao with an admin token. There are two ways:
- Your own admin login on OpenBao, such as a user and password or your organisation's single sign-on. Give it at least the kit's admin policy (
./setup.sh --print-admin-policy), plus the SSH kit's (./ssh/setup-ssh.sh --print-admin-policy) if you use SSH hosts. Before revoking root, log in with it and run./setup.sh --verifyand./emergency-stop.sh --dry-runto check that it can read everything the stop needs. The SSH kit's admin policy must match yourkit.envandssh/ssh-resources. - Make a new root token from the unseal shares when you need one. OpenBao 2.5.3 and later turn this off by default, and the kit's
openbao.hcldoesn't turn it on, so it needs a config change and two restarts, each followed by an unseal. See Make a new root token. This takes several minutes, which matters in an emergency. The tokenless endpoints it uses (sys/generate-root) have also been deprecated since OpenBao 2.6.0, in favour of the authenticatedsys/generate-root-token, so a later version may remove them. An admin login of your own is the approach that will last.
Then revoke the root token:
bao token revoke -self
unset BAO_TOKEN
A token that was created from the root token, such as a bouncer-kit-admin token, is revoked with it.
Make a new root token
This is tested only in our sandbox, against OpenBao 2.7.2. Use it when you have no other admin token.
-
On the VM, allow root generation from the shares. Add this line inside the
listener "tcp"block of/etc/bouncer/openbao/openbao.hcl:disable_unauthed_generate_root_endpoints = falseThen
docker compose restart openbao, and unseal it. -
On the recovery workstation, start the attempt with a one-time password. It is sent to OpenBao to start the attempt, but it stays off the screen and out of files:
export BAO_ADDR=https://openbao.example.com:8443 OTP_LENGTH=$(curl -s "$BAO_ADDR/v1/sys/generate-root/attempt" | jq .otp_length) OTP=$(head -c 64 /dev/urandom | base64 -w0 | tr -dc 'A-Za-z0-9' | head -c "$OTP_LENGTH") NONCE=$(jq -n --arg otp "$OTP" '{otp: $otp}' | curl -s -X PUT --data @- "$BAO_ADDR/v1/sys/generate-root/attempt" | jq -r .nonce) -
Give it two shares, the same way as for unsealing. The second answer holds the new token, encrypted with your one-time password:
for n in 0 1; do age -d -i <identity> <vault folder>/openbao-init.json.age | jq -c --arg nonce "$NONCE" --argjson n "$n" '{key: .unseal_keys_b64[$n], nonce: $nonce}' | ssh admin@openbao.example.com 'cd ~/bouncer/deploy/openbao && docker compose exec -T openbao bao write -format=json sys/generate-root/update -' done | jq -r 'select(.data.complete) | .data.encoded_token' > encoded-token -
Decode it into your shell, without printing it:
read -r BAO_TOKEN < <(OTP="$OTP" python3 -I -c ' import base64, os, sys enc = base64.b64decode(sys.stdin.read().strip() + "==") print(bytes(a ^ b for a, b in zip(enc, os.environ["OTP"].encode())).decode())' < encoded-token) export BAO_TOKEN rm encoded-token; unset OTP NONCE OTP_LENGTH bao token lookup -format=json | jq -c '.data.policies' # ["root"](
bao operator generate-root -decodedoesn't work here: it needs a token before it decodes one.) -
Do what you needed the token for, then
bao token revoke -selfandunset BAO_TOKEN. -
Take the line out of
openbao.hclagain,docker compose restart openbao, and unseal it.
Auto-unseal with the VM's TPM
The repository also has an alternative to typing in shares after every restart: deploy/openbao/auto-unseal/. It uses OpenBao's static seal, whose key is held in a credential that only the VM's TPM 2.0 (Trusted Platform Module, a security chip, here a virtual one) can decrypt at boot. OpenBao then unseals itself after a reboot or a container restart.
Know what it does and doesn't protect before you choose it:
- It protects against someone who copies the VM's disk without its TPM state.
- It doesn't protect against root on the running VM, or anyone who controls the hypervisor. A virtual TPM is software, and a VM backup that includes the TPM state is a copy of the vault that unseals itself.
- If you lose both the TPM state and the escrow copy of the seal key, the vault can't be recovered, even from snapshots.
Not verified for this page. The project tested this only in a virtual machine with a software TPM. We didn't run it for this guide. A complete procedure for configuring and recovering auto-unseal on your own server is not published in this manual. Do not choose it without an independently tested recovery plan.
Bouncer and a sealed OpenBao
While OpenBao is sealed or unreachable:
- the Bouncer server keeps running (from 0.5.6; older servers exited and restarted in a loop), and answers almost every call,
/v1/healthincluded, with HTTP 503 andbackend_sealedorbackend_unreachable; - nothing is issued, and clients say it's an outage, not a refusal: the CLI exits 12 or 13, and the apps say the server's vault is sealed or out of reach;
- revokes are still accepted through
bouncer-adminand the public API. Bouncer stops new issuance at once and revokes existing tokens at OpenBao once it answers. SSH certificates depend on each host fetching the updated revocation list. In 0.5.6 and earlier, hosts can't fetch it while OpenBao is unavailable, so a revoked certificate can keep starting new logins until OpenBao recovers and each host fetches the new list, or until it expires. From 0.5.7, Bouncer serves the list from its database during the outage, once it has read the CA public key (SSH revocation); - once you unseal OpenBao, the server notices by itself within a minute, sooner if something calls it.
From 0.5.6, BOUNCER_WAIT_FOR_OPENBAO isn't needed and is ignored. When Bouncer is unavailable explains every message. Monitor OpenBao's /v1/sys/health as well (Health checks).
Audit logging in OpenBao
OpenBao's audit log records every request made to it, so everything Bouncer does in OpenBao is recorded there too. See Audit for how this fits with Bouncer's own approval log.
With deploy/openbao, it's already on. The kit's openbao.hcl declares a file audit device that writes to /openbao/logs/audit.log, on the container's openbao-audit volume. Because it's declared in the config file, it can't be turned off through the API. To check it, on the recovery workstation, with an admin token:
bao audit list -detailed
and on the VM:
cd ~/bouncer/deploy/openbao
docker compose exec -T openbao ls -l /openbao/logs/
Expected result: a file/ device with file_path=/openbao/logs/audit.log, and that file growing as you use OpenBao.
The container can only write to /openbao/file (its data) and /openbao/logs, so keep audit files in /openbao/logs. To rotate the file, rename it inside that folder and send OpenBao a HUP signal, so it opens a new one:
docker compose exec -T openbao /bin/sh -c 'mv /openbao/logs/audit.log /openbao/logs/audit.log.1 && kill -HUP 1'
Check that a new request adds a line to the new audit.log before you compress or copy away the old file. Don't use copy-and-truncate, which can lose records, and don't use docker compose kill -s HUP, which can stop the container coming back after a reboot. The repository's deploy/openbao/README.md explains both.
With an OpenBao you already run, turn on at least one audit device yourself, in its server configuration. OpenBao refuses requests it can't write to at least one audit device, so consider two.
Backups of OpenBao
deploy/openbao/snapshot.sh and restore.sh take and restore Raft snapshots. A snapshot doesn't include the audit log, the host configuration or Bouncer's PostgreSQL database. See Backup and restore.
How this was checked
We ran steps 1 to 5, the audit check and Make a new root token in a sandbox on one machine: the kit's own compose.yaml and openbao.hcl with only the ports and project name changed, OpenBao 2.7.2, a throwaway age key, and docker compose exec in place of ssh. Every command above is the one we ran, with addresses and folders changed. The outputs are from that run. The role kit's setup, verify and check passed against the new KV mount; the issued secret_id lasted 32 days until we raised the AppRole mount's maximum lease time (Install, step 2d); after bao token revoke -self, the old root token was refused. tailscale serve, a second machine and a real recovery workstation weren't part of the run, and nor were TPM auto-unseal or an admin login of your own.
Upgrade the role kit (from 0.5.7)
This section is for an existing installation moving to 0.5.7. A new installation can skip it.
From that release, upgrade the role kit before the server, using that release's kit or a later compatible kit. The newer kit lets the server check each resource's OpenBao setup, and you need it before you turn on credential lifecycle.
- Keep the pre-upgrade backup and the old release's files.
- In the new release's
deploy/openbao-role-kit, copyresourcesandkit.envfrom the old kit, andssh/ssh-resourcesif you use SSH hosts. Log in to OpenBao with an authorised admin token. Run./setup.sh --dry-runand read every change it proposes. - Apply it with
./setup.sh. A kit policy that nobody edited by hand needs no extra flag. If it asks for--accept-unrevocable-tokens, stop and find out what differs before you continue. - With the single-use check login from Install, step 2c, run
./check.shto check the role's permissions. Do not give it the admin login. - Run
./setup.sh --verify. It must exit 0. - Run the new server's configuration check as its service user. It must exit 0 before you switch to the new server or add a resource to the live config.
If an earlier upgrade already used the 0.5.6 kit, do these steps again with the newer kit. On an installation that is otherwise up to date, only the bouncer-server policy changes: it can now read the token-role and resource-policy settings the check needs. An installation whose resource policies an older kit wrote also gets policies that refuse reads of older secret versions. No token role should change.
If you upgrade the server before the kit, it keeps issuing tokens as before. It logs a warning once for each resource and reports upgrade_needed, and the configuration check exits 4. That's expected, but it isn't a pass: without those settings the server can't confirm a role or policy is right, and older policies can still allow reads of earlier secret versions. Until you upgrade the kit, OpenBao's audit log can also show a permission-denied entry about once a minute for each resource. Failed creates and config reloads can cause extra checks.
Keep using the newer kit's scripts afterwards, including its emergency stop, even if you roll the server back. The 0.5.6 server works with the newer policy. An older kit reads the added lines as a hand edit: its --verify reports drift, its emergency stop cannot confirm a stop, and its setup.sh asks for --accept-unrevocable-tokens.
This procedure was checked against the source for 0.5.7. The project's automated tests, with fake data and OpenBao 2.7.2, ran the kit setup and the configuration check for a ready kit, an older kit, a missing role and a sealed OpenBao. The full procedure hasn't been run end to end.
Install the server
This page installs the Bouncer server and PostgreSQL with Docker Compose, and connects them to your OpenBao. It takes about an hour the first time, most of it reading.
Before you start: read Overview and prerequisites and complete its preparation checklist. OpenBao must already be running and unsealed, with a KV version 2 mount. Do not initialise an existing OpenBao again. If you don't run OpenBao yet, set it up first with OpenBao for Bouncer.
The examples use bouncer.example.com for the Bouncer server's address and openbao.example.com for OpenBao. Use your own.
Step 1: get the files onto the server
There are two ways, and the rest of the page is the same for both except step 4:
- From a release download: you load a ready-made image, so the server needs no access to the source and never compiles anything. 0.5.5 was the first release with the server files; check them with the release's combined
SHA256SUMSand--ignore-missing. The 0.5.6 build introduced its ownbouncer-server-<version>-SHA256SUMS, which lists only the server files. The private 0.5.7 release uses the same layout. Get Bouncer says what they are. - From the source: you clone the repository and build the image on the server in step 4. This needs access to the source repository, and 4 GB or more of memory while it builds.
Do either one as a normal user who can run docker.
.env, which both ways make, holds settings, never secrets: the port, the folders and the image name. The defaults are a good start: port 8080, the config in /etc/bouncer/config, the secret files in /etc/bouncer/secrets.
1a. From a release download
The release's INSTALL-SERVER.md has these steps with that release's exact names, commit and image ID. Follow it, except for its checksum step: in 0.5.5 the guide runs sha256sum -c SHA256SUMS, which also lists the app and CLI files and reports the ones you didn't download as missing. Use step 1 below instead. Put the image, kit, guide and checksum file in one folder, then:
-
Check the files against the release's combined
SHA256SUMS. For 0.5.5:sha256sum -c SHA256SUMS --ignore-missingIt must say
OKfor each file you downloaded. If one saysFAILED, download it again and don't use it.--ignore-missingskips app and CLI files you didn't download. For a release that includesbouncer-server-<version>-SHA256SUMS, usesha256sum -c bouncer-server-<version>-SHA256SUMSinstead; it lists only the three server files. -
Load the image:
gunzip -c bouncer-server-<version>-image.tar.gz | docker loadIt ends with
Loaded image: localhost/bouncer-server:<short commit>. With Podman:podman load -i bouncer-server-<version>-image.tar.gz. -
Check the image is the release's. Read its revision and version labels:
docker image inspect localhost/bouncer-server:<short commit> \ --format '{{index .Config.Labels "org.opencontainers.image.revision"}} {{index .Config.Labels "org.opencontainers.image.version"}}'It must print the release's full commit and version, exactly as
INSTALL-SERVER.mdshows them. If it doesn't, stop. -
Unpack the kit into a folder of its own, so the release before it stays for a rollback, and point
.envat the image you loaded:mkdir -p ~/bouncer-releases tar -xzf bouncer-server-<version>-compose.tar.gz -C ~/bouncer-releases cd ~/bouncer-releases/bouncer-server-<version>/deploy/compose cp .env.example .env sed -i 's|^BOUNCER_IMAGE=.*|BOUNCER_IMAGE=localhost/bouncer-server:<short commit>|' .env printf 'BOUNCER_VERSION=%s\nBOUNCER_REVISION=%s\n' '<version>' '<full commit>' >> .envThe last two lines record the release in
.envand in the image's labels.
From here on, wherever these pages say ~/bouncer, your folder is ~/bouncer-releases/bouncer-server-<version>. The role kit is in it, at deploy/openbao-role-kit.
1b. From the source
Clone the repository. Ask whoever gave you access to Bouncer for the repository link. Check out a release tag, or a commit you have chosen:
git clone <repository URL> ~/bouncer
cd ~/bouncer
git checkout <tag or commit>
cd deploy/compose
cp .env.example .env
A strict umask
If your umask is stricter than the usual 022 (umask prints 0077 or 0027), PostgreSQL's user inside its container can't read the kit's folder and stops at its first start. This applies to both ways. Make the folder readable; nothing in it is secret:
chmod -R a+rX ~/bouncer/deploy/compose
Our test run hit this: PostgreSQL exits with code 2 and its log repeats ls: cannot open directory '/docker-entrypoint-initdb.d/': Permission denied.
Step 2: set up Bouncer's role on OpenBao
Bouncer logs in to OpenBao with AppRole, OpenBao's login method for programs. A program logs in with two values: a role_id, which names the role, and a secret_id, which works like a password. The role kit (deploy/openbao-role-kit) creates that role, with policies that only let Bouncer issue short tokens for the secrets you list, and revoke them.
Run the kit on any machine that has an OpenBao admin token, a token allowed to manage policies, token roles and login methods. It doesn't have to be the Bouncer server. On a new dedicated OpenBao, that's the root token on your recovery workstation (OpenBao for Bouncer, step 5).
2a. Choose kit settings
List your secrets in the kit's resources file:
cd ~/bouncer/deploy/openbao-role-kit
cp resources.example resources
$EDITOR resources
Each line of resources is one secret:
# <resource-id> <kv-mount> <kv-path> [max-ttl-seconds]
prod-db-password kv apps/billing/db-password 120
deploy-token kv services/deploy/token
The resource ID is Bouncer's name for the resource. The KV mount must be a KV version 2 mount, and the path is the secret's path inside it, without data/. You will list the same resources in Bouncer's config file in step 3. While you test, use a secret that doesn't matter, such as the bouncer-test secret from OpenBao for Bouncer, step 4.
Then decide two settings in the kit's kit.env, before setup.sh runs for the first time. Changing them later makes the kit treat the change as a possible hand edit and ask for extra flags. Without a kit.env, the defaults apply.
cp kit.env.example kit.env
$EDITOR kit.env
SECRET_ID_TTL: how long Bouncer's secret_id lasts, 90 days by default. OpenBao also caps it at the AppRole mount's maximum lease time, often 32 days; step 2d shows the real lifetime.SECRET_ID_BOUND_CIDRS: the addresses Bouncer may log in from, for example10.0.0.10/32. Off by default.
2b. Apply the kit
export BAO_ADDR=https://openbao.example.com:8443
bao login # your admin token, unless BAO_TOKEN is already set
./setup.sh --dry-run # read what it would do
./setup.sh # apply it; type yes
./setup.sh --verify # must say everything matches
Expected result: setup.sh ends by telling you to run the check, and --verify exits 0.
2c. Run the check
The check logs in as Bouncer with a single-use login and lists what the role can and can't do:
(umask 077
bao read -field=role_id auth/bouncer-approle/role/bouncer-server/role-id > check.role_id
bao write -f -field=secret_id auth/bouncer-approle/role/bouncer-server/secret-id ttl=10m num_uses=1 > check.secret_id)
BOUNCER_ROLE_ID=$(cat check.role_id) BOUNCER_SECRET_ID=$(cat check.secret_id) ./check.sh
rm -f check.role_id check.secret_id
Expected result: it ends with Summary: N checks, N ok. and exits 0. Against a fresh OpenBao 2.7.2, our test runs reported Summary: 47 checks, 47 ok. with the example resources, and Summary: 34 checks, 34 ok. with only the bouncer-test resource. The number depends on your resources. Don't carry on until it passes.
2d. Make Bouncer's own credentials
First check how long OpenBao will let the secret_id last. OpenBao caps it at the AppRole mount's maximum lease time, whatever SECRET_ID_TTL says:
bao read -field=max_lease_ttl sys/auth/bouncer-approle/tune
It prints seconds. 2764800 (32 days) is OpenBao's usual default. For the full 90 days the answer must be at least 7776000. To raise it, use a full admin token (a scoped bouncer-kit-admin token, described in OpenBao for Bouncer, step 5, can't change it):
bao auth tune -max-lease-ttl=2160h bouncer-approle
Then make the two values straight into files, in a new private folder outside the repository, so they never appear on screen or in your shell history. The commands also print how long the secret_id really lasts. Copy the files to the Bouncer server and destroy the copies here:
HANDOVER=$(mktemp -d)
(umask 077
bao read -field=role_id auth/bouncer-approle/role/bouncer-server/role-id > "$HANDOVER/bouncer-role-id"
bao write -f -format=json auth/bouncer-approle/role/bouncer-server/secret-id > "$HANDOVER/secret-id.json"
jq -j .data.secret_id "$HANDOVER/secret-id.json" > "$HANDOVER/bouncer-secret-id"
jq -r '"The secret_id lasts \(.data.secret_id_ttl / 86400) days."' "$HANDOVER/secret-id.json"
shred -u "$HANDOVER/secret-id.json")
scp "$HANDOVER/bouncer-role-id" "$HANDOVER/bouncer-secret-id" admin@bouncer.example.com:
shred -u "$HANDOVER"/* && rmdir "$HANDOVER"
Expected result: The secret_id lasts 90 days., or fewer if you kept a lower limit.
If you run the kit on the Bouncer server itself, leave out scp and shred, and install the files from "$HANDOVER" in step 3.
Write down when the secret_id expires. When it does, the server can no longer log in to OpenBao. Replacing the secret_id explains how to renew it.
Keep the kit's resources file next to the kit's scripts. The emergency stop needs it.
Step 3: the config and the secret files
Make the folders on the Bouncer server:
sudo install -d -m 0755 /etc/bouncer /etc/bouncer/config
sudo install -d -m 0700 -o 10001 -g 10001 /etc/bouncer/secrets
User ID 10001 is the user the server runs as inside its container. It doesn't need to exist on the host.
Install the three secret files, readable only by that user. They are mounted read-only into the container at /run/secrets/<name>, and never put into an environment variable or the image.
# The two files from step 2d, in your home folder:
sudo install -m 0400 -o 10001 -g 10001 ~/bouncer-role-id ~/bouncer-secret-id /etc/bouncer/secrets/
shred -u ~/bouncer-role-id ~/bouncer-secret-id
# The database password: a random one you never need to type.
head -c 32 /dev/urandom | od -An -tx1 | tr -d ' \n' |
sudo install -m 0400 -o 10001 -g 10001 /dev/stdin /etc/bouncer/secrets/bouncer-db-password
With rootless Podman, user 10001 inside the container is a different user outside it. Make the files yours, then hand them over inside Podman's user namespace:
sudo chown -R "$USER": /etc/bouncer/secrets
podman unshare chown -R 10001:10001 /etc/bouncer/secrets
Now the config file. Start from the example and change every value marked CHANGE:
cd ~/bouncer/deploy/compose
sudo install -m 0644 bouncer.yaml.example /etc/bouncer/config/bouncer.yaml
sudo $EDITOR /etc/bouncer/config/bouncer.yaml
The settings to change first:
instance.id: a short name such asexample-home. Pick it once and never change it: it goes into every signed approval.instance.url: the HTTPS address people's apps will use, for examplehttps://bouncer.example.com. It must match what your reverse proxy serves (TLS and networking).people: the people who approve, one entry each.openbao.address: your OpenBao, as both the server and your requesters reach it. If its certificate isn't publicly trusted, save the CA certificate as/etc/bouncer/config/openbao-ca.pemand setca_file: /etc/bouncer/openbao-ca.pem(the config folder is mounted at/etc/bouncerinside the container).resources: one entry per resource, with the same IDs and KV paths as the role kit'sresourcesfile.pairing: leaveallow_software_keys: false. Addallow_user_verified_keys: trueif anyone will approve from an iPhone, andallow_webauthn_keys: trueif anyone will approve from a Windows PC with Windows Hello. Both are off by default, and without them those devices can't approve (Pair a device).defaults.durations.always: set it tofalse, and takealwaysout ofdefaults.durations.presets. The example file allows standing grants, grants with no end time, and the Bouncer project hasn't decided their policy yet (Approvals and access duration).- Leave
push: nullfor now (Push notifications).
Configure the server explains each section, and Resources and policy explains what each resource setting does.
Step 4: build the image
If you installed from a release download, skip this step. You loaded the image in step 1a, and .env names it.
From the source:
cd ~/bouncer/deploy/compose
docker compose build --build-arg BOUNCER_VERSION="$(git describe --tags --always)" \
--build-arg BOUNCER_REVISION="$(git rev-parse HEAD)"
This makes the image localhost/bouncer-server:local. On a machine with little memory, add --build-arg BUILD_JOBS=1. The build downloads two base images (Rust, and Debian for the runtime) and the crates in Cargo.lock, and nothing else. Both base images are pinned by digest.
With Podman, build from the repository root instead:
podman build --format docker -f deploy/compose/Dockerfile -t localhost/bouncer-server:local .
--format docker keeps the image's health check.
Step 5: start it
docker compose up -d --wait --wait-timeout 120
docker compose ps # both services "healthy"
docker compose logs bouncer # look for "bouncer-server is up"
curl -s http://127.0.0.1:8080/v1/health
--wait waits for the containers' health checks, for up to 120 seconds.
If it fails or times out, inspect the logs and health checks
before continuing. A running container alone does not mean start-up has
finished. If the log shows OpenBao is sealed or refusing Bouncer's login, fix that (When Bouncer is unavailable), then check health again.
With Podman, start the stack and use a bounded HTTP retry for the health check instead of Docker Compose's wait flags:
podman-compose up -d
podman-compose ps
podman-compose logs bouncer
curl --fail --silent --show-error --retry 24 --retry-delay 5 \
--retry-connrefused --retry-max-time 120 --max-time 5 \
http://127.0.0.1:8080/v1/health
Expected result: the health answer names your instance and the server version you installed. This example is from our 0.5.0 test run, so your version will differ. It shows the shape of the answer; newer servers add fields:
{"status":"ok","instance":{"id":"example-home","name":"Example home","url":"https://bouncer.example.com","contract":"bouncer.v1","version":"0.5.0+27","android_key_attestation":true,"credential_types":true},"server_time":"2026-11-15T10:00:00Z"}
At start-up the server connects to PostgreSQL, runs migrations, checks the config, creates a human requester for each person, and checks its OpenBao login and token roles. Invalid config, a database error or an OpenBao login with the wrong powers stops start-up. From 0.5.6, if OpenBao is sealed, unreachable or refuses the AppRole login, the server keeps running, answers 503 (backend_sealed, backend_unreachable or backend_auth_failed) and issues nothing. Earlier servers, such as 0.3.8, can exit and restart instead. Troubleshooting lists the messages. A healthy answer doesn't prove every resource can be issued, so make the test request in Next steps, step 3.
Next steps
-
Try a request from a requester machine (Integrate):
bouncer request prod-db-password --for 15m --reason "First test" --wait # approve on the phone bouncer exec prod-db-password --env PASSWORD=password -- sh -c 'test -n "$PASSWORD" && echo "got it"'This example assumes the resource has a field named
password. Use the actual field name with--env; for the OpenBao test secret whose field isvalue, use--env PASSWORD=value. -
Run the kill switch once, so you know it works before you need it:
docker compose exec bouncer bouncer-admin revoke --allIt asks you to type
yes, then ends every grant, cancels every pending request and asks OpenBao to revoke every token Bouncer issued. Check its report for any revoke it couldn't confirm.
How this was checked
Steps 1 to 5 were run in our first test run, against a fresh OpenBao 2.7.2 and with Docker, with made-up names and secrets. In a second run, against a new OpenBao set up as in OpenBao for Bouncer, we ran steps 2a to 2d again, including the lifetime check in 2d: the mount's limit read 2764800 (32 days) until we raised it, and then the secret_id lasted 90 days. The scp was replaced by a local copy. The Podman commands in step 5 weren't run; they are the same commands through podman-compose.
The earlier 0.5.4 download instructions are checked against source only; no transcript of that installation is retained. On 17 November 2026, a fake-data test followed the release-download installation with a real OpenBao sandbox using 0.5.6, then upgraded and rolled back from 0.5.5. This did not test production or physical devices.
TLS and networking
The Bouncer server speaks plain HTTP, on 127.0.0.1:8080 by default (--listen). Something on the same machine must put HTTPS in front of it. Apps and requesters always use HTTPS: the CLI refuses plain HTTP to any other machine.
What talks to what
| From | To | Port (defaults) | Notes |
|---|---|---|---|
| Phones, PCs, requesters | Your HTTPS front end | 443 | The address in instance.url |
| HTTPS front end | Bouncer server | 127.0.0.1:8080 | Plain HTTP, on the same machine |
| Bouncer server | PostgreSQL | none | A Unix socket on a shared volume. PostgreSQL has no network at all |
| Bouncer server | OpenBao | 8443 with deploy/openbao, or whatever your OpenBao uses | Use HTTPS. The config accepts plain HTTP too, but then tokens cross the network unencrypted; use it only when OpenBao is on the same machine |
| Requesters | OpenBao | the same | Requesters read secrets from OpenBao directly with the short tokens Bouncer gives them |
| Bouncer server | Firebase (Google) | 443, outbound | Only if push is on |
bouncer-admin | Bouncer server | none | A Unix socket, /run/bouncer/admin.sock in the container |
Nothing in the kit opens a port to the internet. Keep it that way: put Bouncer on a private network or VPN that only your people and machines reach.
What the apps need
The apps need a network path to the address in instance.url, and a certificate they trust for that name. They don't need any particular network product: a LAN, ordinary HTTPS on a private network, or a VPN all work, if your devices can reach the server over them. The apps don't detect, install or require a VPN. Whether people need one is your deployment's choice, so say so in your own instructions if they do.
Before pairing, the Windows app checks the address it's given (The server check on Windows). It asks GET /v1/health with no credential, and stops unless the certificate is trusted by the PC, in date and for the name typed, and the answer is a Bouncer API the app speaks. It never skips certificate checks, never falls back to plain HTTP, and never follows a redirect, so the address people type must be the server's own HTTPS address. A private CA has to be installed in each PC's certificate store (for example by Group Policy) before that PC can pair.
One option: tailscale serve
The kit's examples use tailscale serve, so it's described here. It's one way to put HTTPS in front of the server; your devices then need Tailscale connected to reach it. Any other front end that meets Other reverse proxies works the same for the apps.
Tailscale is a VPN that gives each machine an address on your private network (your "tailnet") and can issue HTTPS certificates for the machines' names. tailscale serve then terminates HTTPS and forwards to a local port.
-
In the Tailscale admin console, turn on MagicDNS and HTTPS certificates.
-
On the Bouncer server:
sudo tailscale serve --bg --https=443 http://127.0.0.1:8080 tailscale serve status -
tailscale serve statusshows the HTTPS address (it ends in.ts.net). Setinstance.urlin the config to exactly that address, then rundocker compose exec bouncer bouncer-admin config reload. -
From another machine on your tailnet:
curl -s https://<the address from step 3>/v1/healthExpected result: the same health answer as on the server itself, with
"status":"ok"and yourinstance.url, which is your.ts.netaddress (the example uses this guide's placeholder):{"status":"ok","instance":{"id":"example-home","name":"Example home","url":"https://bouncer.example.com", ...If
curlcomplains about the certificate, HTTPS certificates aren't on for your tailnet yet (step 1).
Use exactly the form --https=443 http://127.0.0.1:<port>. Never use tailscale funnel, which puts the service on the internet, and never use --tcp or --tls-terminated-tcp, which pass the caller's own headers through.
Why the server trusts 127.0.0.1 as a proxy
Behind a reverse proxy every caller seems to come from 127.0.0.1. The server uses the caller's real address for three things: the rate limit on wrong pairing codes, a device's "paired from" address, and the network address shown on the approval card. So the compose file starts the server with --trusted-proxy 127.0.0.1, and the server takes the address from the X-Forwarded-For header, but only on connections from 127.0.0.1.
The proxy must put the real client address last in X-Forwarded-For, either by replacing the header or appending that address. Bouncer takes the right-most address it does not trust. Tailscale's source code does replace it. The project's tests check the server side, not tailscale serve itself (see How this was checked). The repository's deploy/compose/README.md ("How it was tested") has a check you can run on your own machine.
Anything else on the machine that can reach 127.0.0.1:8080 can claim any address. That can change the address shown on approval cards and spread wrong pairing-code guesses across claimed addresses, though pairing codes have 60 bits of entropy. It cannot approve anything or get past a requester key. Keep the machine for Bouncer.
Other reverse proxies
Not tested. Any HTTPS reverse proxy on the same machine can work if it:
- forwards to
http://127.0.0.1:8080; - sets
X-Forwarded-Forto the real client address, or appends that address as the last hop. Bouncer uses the right-most hop it does not trust; - uses a certificate your devices trust, for the name in
instance.url.
The iOS, Android and Windows apps need a certificate their system trusts. A private CA works only if it's installed on every device.
Why not rootless Docker
Rootless Docker puts the container's "host" network in a namespace of its own, so the server's 127.0.0.1 isn't the machine's, and tailscale serve can't reach it. Don't work around it by publishing a port: the server would then see Docker's gateway as the caller, and --trusted-proxy 127.0.0.1 would stop matching. Use rootful Docker or rootless Podman.
OpenBao's certificate
If OpenBao's certificate isn't from a public CA, give its CA to both sides:
- the server: save the CA certificate as
/etc/bouncer/config/openbao-ca.pemand setopenbao.ca_file: /etc/bouncer/openbao-ca.pem, then restart; - each requester: set
BOUNCER_CA_FILEto the same PEM file (Environment variables).
How this was checked
The kit's examples use Tailscale because the kit was built around it, not because we tested it: Tailscale wasn't part of our test run. What we checked, on rootful Docker 29: the server listened on 127.0.0.1 only, PostgreSQL had no network, and X-Forwarded-For was believed only on connections from 127.0.0.1. The tailscale serve commands and the expected answer above come from the repository's deploy/compose/README.md and the health endpoint's own answer, not from a tailnet. No public certificate was used.
Configure the server
All of Bouncer's policy comes from one YAML file, /etc/bouncer/config/bouncer.yaml in the compose kit. It says who the people are, which resources exist, who may ask for each one, who approves, and for how long. It holds no secrets, only the paths of the files that do.
Keep your real file in a Git repository you control and review changes to it. Whoever can change the file controls Bouncer's policy.
This page explains the sections and how changes take effect. The config file reference lists every setting with its default and range.
A small complete example
version: 1
instance:
id: example-home # never change this once devices are paired
name: Example home
url: https://bouncer.example.com # the address apps and requesters use
people:
- id: alice
name: Alice
- id: bob
name: Bob
defaults:
request_wait: 15m # how long a request waits for a decision
credential_ttl: 5m # how long each OpenBao token lasts
durations:
presets: [5m, 15m, 1h, 6h, 24h]
min: 1m
max: 24h
always: false
self_approval: true
notification_approval: true
openbao:
address: https://openbao.example.com:8443
ca_file: null
kit_prefix: bouncer
approle:
mount: bouncer-approle
role_id_file: /run/secrets/bouncer-role-id
secret_id_file: /run/secrets/bouncer-secret-id
pairing:
allow_software_keys: false
push: null
resources:
- id: prod-db-password
name: Production database password
kind: stored_secret
kv:
- mount: kv
path: apps/billing/db-password
fields: [password]
approvers: [alice]
requesters: [alice, build-agent]
The sections
| Section | What it holds |
|---|---|
version | Always 1 |
instance | The instance ID, a display name and the HTTPS address. The ID goes into every signed approval, so a signature made for one Bouncer can't be used on another |
people | Everyone who pairs a device and approves. Each person also gets a human requester with the same name, for requests they make themselves |
groups | Optional named groups of people, used by personal credential sharing |
defaults | The policy every resource gets unless it sets its own: waiting time, token lifetime, the duration choices, self-approval and approval from notifications |
openbao | Where OpenBao is, its CA file, the role kit's prefix, and the AppRole files |
pairing | Which kinds of approval key may pair (see Device keys) |
push | Firebase push settings, or null for no push (Push notifications) |
resources | One entry per secret Bouncer guards (Resources and policy) |
personal_credentials | Optional storage areas where people create their own credentials from the apps |
People are config entries. There is no single sign-on or directory integration in this version. A person exists because they are listed here, and they prove who they are by holding a device that was paired as them. Removing a person from the file stops them being an approver for any resource; revoke their devices as well (People, requesters and devices).
Durations
Durations are a whole number and a unit: s, m, h or d, for example 90s, 15m, 6h or 7d. A grant can last from 1 minute to 365 days.
The duration presets can also contain always, a standing grant: a grant with no end time. The Bouncer project hasn't decided the policy for standing grants yet. Keep them off. Set durations.always: false and leave always out of the presets, as in the example above. The example file in the repository turns them on. Approvals and access duration says what the source does with them.
How changes take effect
Most changes take effect with a reload, without restarting:
docker compose exec bouncer bouncer-admin config reload
The server reads the file again and checks it. If it isn't valid, the reload is refused with the reason, and the old file stays loaded. Expected result on success: the loaded time, resource and person counts, and new revision. From 0.5.7, the output also lists resources that need particular kinds of approval key. Policy-loosening warnings are in the approval log, not this output; read them in the affected person's app History or export the log.
Two kinds of change need a restart instead, because the server connects to OpenBao only at start-up:
- any change to the
openbaosection; - adding a new resource.
docker compose up -d --force-recreate --wait --wait-timeout 120 bouncer
docker compose logs bouncer # look for "bouncer-server is up"
This recreates the container and waits for its health check. If the wait
fails or times out, inspect the log before continuing. For Podman, run
podman-compose restart bouncer, then the bounded HTTP health retry in
Install, step 5.
A reload that tries one of these is refused with a message saying a restart is needed, and the old config stays loaded. Removing a resource, and changing people or policy, only need a reload.
Changes that loosen policy are announced. When a reload makes a resource's policy or the pairing settings less strict (a longer maximum duration, a new requester, self-approval turned on, a weaker pairing setting), the server writes a policy_loosened entry in the approval log naming each change, and tells the affected approvers' devices. Only a reload is compared. A restart or recreated container, including after an edit while stopped, logs only config_loaded, with no description or alert to approvers. To keep the alert, reload a policy loosening separately from changes that need a restart.
Changes to a resource's policy end its standing grants. Each resource has a revision computed from its policy. A standing grant approved under one revision is suspended when the revision changes, and the requester must ask again. A resource's name, description, folder and credential_type don't count towards the revision.
Checking a file before you deploy it
From 0.5.7, the new server can check a config file before you install it. These pages call this the configuration check, or preflight. Run it as the Bouncer service user, with access to the AppRole credential files and any CA files the new config names:
bouncer-server --config /path/to/candidate.yaml --check-config
With the Compose image, run it from the new release's Compose folder, whose .env names the new image. Save the new file as candidate.yaml next to the live config, in the config folder (/etc/bouncer/config on the host by default). This starts a temporary container as the image's service user; it doesn't replace the running server:
docker compose run --rm --no-deps --entrypoint /usr/local/bin/bouncer-server \
bouncer --config /etc/bouncer/candidate.yaml --check-config
The check needs no database, opens no port, applies nothing and runs no migrations. It logs in to OpenBao, which creates a server login token that expires (after one hour with the kit's defaults), and reads the settings of each resource's token role and policy. It creates no token for any resource. It prints a report on standard output. Read every line, and check the exit status:
| Exit | Meaning |
|---|---|
| 0 | All checks passed |
| 1 | Global setup or login failure |
| 2 | Command usage error |
| 3 | A definite resource gap, such as a missing or unsuitable role or policy |
| 4 | Kit upgrade needed, or a transient check that could not finish |
If a resource has a definite problem, the exit is 3 even when other checks couldn't finish. Before the role kit upgrade, exit 4 with upgrade_needed is expected for policies an older kit wrote: the resource still works, but the check hasn't passed. After upgrading the kit, the check must exit 0 before you install new resources and restart. A new resource takes its durations from defaults unless it sets its own; you don't need to shorten them because the resource is new.
These configuration-check instructions were checked against the source for 0.5.7 and its isolated OpenBao 2.7.2 checks. The full manual sequence, including the temporary Compose command, has not been run end to end.
On 0.5.6 and earlier there is no --check-config. Reload checks an edit
while keeping the old config if it is refused; bouncer-admin exits 6 and
says why. Newer servers also retain that reload behaviour. The server answers in this form:
bouncer-admin: The server said no: The config file was refused; the old one stays loaded
(config_invalid, HTTP 422). the config file isn't valid: - defaults.durations: min (2h) is more than max (1h)
bouncer-admin: The server said no: The config file was refused; the old one stays loaded
(config_invalid, HTTP 422). The resource example-new is new, which only takes effect when
the server starts. The old config is still loaded: restart the server to use the new one.
A reload that loosens policy succeeds and leaves an entry like this in the approval log:
policy_loosened config revision 263141bd3bd1 loosened resource llm-provider: durations.max went from 1d to 7d
The environment file
deploy/compose/.env sets how the containers run, not policy. See Environment variables.
Resources and policy
A resource is one thing Bouncer guards: usually a secret in OpenBao, sometimes SSH access to one host. Each resource in the config file says what it is, who may ask for it, who approves, and for how long access can last. This page explains those settings in Bouncer 0.5.7.
The basic resource
resources:
- id: prod-db-password
name: Production database password
kind: stored_secret
description: The billing service's PostgreSQL password.
folder: Databases/Production
kv:
- mount: kv
path: apps/billing/db-password
fields: [password]
approvers: [alice]
requesters: [alice, build-agent]
| Setting | Meaning |
|---|---|
id | The resource's ID: lower-case letters, digits and single hyphens, up to 40 characters. Requesters use it (bouncer exec prod-db-password). It must match the role kit's resources file. IDs starting with pc- are reserved |
name, description | What people see in the apps and in bouncer resources |
folder | Where the apps' library files it, as folder names joined by /. Leave it out for "Unfiled". Changing it doesn't affect any grant |
kind | stored_secret, stored_api_key or ssh_host. The first two behave the same way; the kind is a label for people. ssh_host is different (see SSH hosts) |
credential_type | Optional. What the value is (api_key, password, access_token, certificate, certificate_with_private_key, ssh_private_key, secret_key, key_pair, recovery_codes, otp_seed or other), so the apps can show a matching icon. It's a label only, not policy |
kv | The OpenBao KV version 2 secrets behind it: one or more mount and path pairs |
fields | Optional. The field names in the secret, shown to requesters so they know what to ask for. Names only, never values |
approvers | The people (by their id in people) who may approve requests for it |
requesters | Who may ask for it: a list of requester names, or ["*"] for any active requester. Leaving it out also means any active requester |
A requester that isn't allowed to ask for a resource doesn't see it in its list, and a request for it is refused as if the resource didn't exist.
How long access lasts
Each resource takes the defaults and can override any of them:
- id: prod-db-password
# ...
request_wait: 10m # how long a request waits for a decision: 1m to 24h
credential_ttl: 2m # how long each OpenBao token lasts: 30s to 1h
durations:
presets: [15m, 1h] # the quick choices on the approval screen
min: 5m # the allowed range for a custom duration
max: 4h
always: false # whether a standing grant may be approved
Two different times matter here, and it helps to keep them apart:
- The grant's duration is how long the approval lasts. The requester asks for one, and the approver can approve it, shorten it, or (after a confirmation) lengthen it within the range above.
- The token lifetime (
credential_ttl) is how long each OpenBao token lasts. A requester fetches a fresh token each time it uses the grant. A token never outlives its grant.
The approver's choices are checked by the server. A duration outside the range, or a preset you disabled, is refused, never quietly shortened. Presets above max are shown disabled, with the reason.
The limit lives only in this file. The apps show it ("Up to 15 minutes for this credential. Your Bouncer administrator sets this in the server's settings."), but no app screen can change it. The CLI asks for the first enabled preset when no --for is given, so keep a short one first.
To change one resource's limit, follow docs/operations/approval-durations.md in the repository. It covers editing only that resource's lines, committing and reloading, the policy_loosened entry, why requests that were waiting must be asked again, checking the result with bouncer resources --json, and rolling back.
If the role kit's resources file gives a resource a shorter max-ttl-seconds, keep credential_ttl within it. OpenBao enforces the kit's cap.
Add a resource
On 0.5.6 and earlier, add the resource to the role kit's resources file and run ./setup.sh, add it to the config file, then restart the server (Keeping the two lists in step).
From 0.5.7, add a stored secret or API key resource in this order:
- Add its line to the role kit's
resourcesfile, then run the kit upgrade and permission checks. - Make a copy of the config file with the new resource in it, and run the new server's configuration check on that copy. Once the kit is upgraded, it must exit 0.
- Install the checked config. The resource takes its durations from
defaultsunless you set its own; you don't need a shorter maximum because it's new. - Restart the server. The server learns a new token role's name only when it starts, so a reload isn't enough. Then try a request with fake data, and use the result, before you rely on the resource.
If a resource's OpenBao token role or policy is missing or wrong, the server refuses only that resource, with HTTP 503 resource_not_provisioned and Retry-After: 5. Other resources keep working. Fix the kit entry, then apply and verify the kit; the server checks again by itself. A sealed or unreachable OpenBao, or one that refuses the server's login, is still an outage of the whole server, not a problem with one resource.
This check covers requesters' requests, issuing their tokens, and saves requesters make under those grants. Saves, views and replacements made from the apps use the server's own OpenBao policy and have their own checks. SSH hosts and personal credentials keep their existing checks. This was checked against the source for 0.5.7; the whole sequence hasn't been run end to end.
Who may approve
self_approval: true # may people approve their own requests?
notification_approval: true # may they approve from the notification?
require_hardware_uv: false # must approvals come from a hardware biometric key?
require_hardware_key: false # must they come from a hardware key checked each time? (from 0.5.7+34)
self_approval(defaulttrue). When it'strue, a person may approve requests from their own human requester and from agents or hosts they own. The apps label these "Self-approval" and "Your own agent". When it'sfalse, those requests need another approver. Denying is always allowed. See Separation of duties.notification_approval(defaulttrue). Allows approving straight from a notification, without opening the app. Each device must also opt in, and only the requested duration can be approved that way. Only the Android app offers it.require_hardware_uv(defaultfalse). Whentrue, only a phone key that asks for a biometric check on every signature (platform-hw-uv) can approve this resource. Windows Hello keys and older phone keys can still deny. See Device keys and user verification.require_hardware_key(defaultfalse). Introduced in 0.5.7; earlier servers refuse a config that sets it. In the current source (not yet released), it accepts verified Android-key evidence plus biometric verification, or verified TPM evidence plus a WebAuthn UV assertion. An unverifiedplatform-hw-uvclaim and a hardware-unlocked key both fail. The server's evidence must belong to this key and epoch. No real PC has yet passed the TPM verifier; physical acceptance remains separate.require_hardware_uvkeeps its existing enrolled-label and biometric-statement rule. It still accepts declared claims until an operator opts in to verified evidence. Setting both flags requires both; a TPM key verified with a PIN cannot meet the biometric flag.- Denying is independent of these resource flags. The explicit server-wide
pairing.require_verified_approval_keysopt-in also applies whenever a key signs. Device keys describes recovery and the default, which activates no policy. - Turning either requirement off is logged as a loosening, including dropping verified evidence while UV remains. Replacing the biometric requirement with hardware-key policy also removes the biometric requirement and is reported.
Saving new values: allow_write
allow_write: true
Off by default. With it, a requester can ask to save new values into the secret (for example after rotating an API key) with bouncer put or the MCP request_store tool. The request names the fields, never the values; the values are sent only after approval, once. A resource with allow_write must list exactly one kv entry, and the role kit's resources line for that secret needs the word write.
With allow_write and self_approval both on, an approver can also save values from their own paired app.
Viewing the value in the app: view
view: grant_holder # off (the default), grant_holder or approver
off: nobody sees the value in the apps.grant_holder: a person whose own human requester holds an active read grant for the resource can view it on a paired device. An agent's grant never counts.approver: the resource's approvers can view it, grant or not.
Every view is signed by the device's approval key and logged as secret_viewed. It accepts a hardware-backed phone key or a Windows Hello key, including an Android key that needs only the phone unlocked. A view uses the check the key was set up with, so an unlocked-phone key asks for nothing more. If every view must check the person, also set require_hardware_uv: true on the resource. Turning it on counts as a loosening and is announced. It needs exactly one kv entry, and the word view on that line of the role kit's resources file.
Credentials from other systems: downstream
downstream:
system: Example cloud API
kind: static_token
expires_at: "2027-06-30T00:00:00Z"
Use this when the secret is a token issued by another system (a cloud API key, a Proxmox API token). Bouncer can revoke its own OpenBao tokens but not the copied value at that system. With this block, Bouncer tracks when the value has been released and the grant has ended, and bouncer-admin downstream list shows ROTATE yes. You rotate it at the system, update the secret in OpenBao, then record it:
docker compose exec bouncer bouncer-admin downstream rotated example-api-key
Bouncer trusts your word here: it doesn't contact the other system. See Copied secrets and revocation limits.
SSH hosts
- id: web1-deploy
name: Web server 1
kind: ssh_host
description: "SSH to web1.example.com"
ssh:
principal: deploy # the one account on the host; never root
approvers: [alice]
requesters: [build-agent]
credential_ttl: 5m
An ssh_host resource has no kv entry. Instead of a stored key, each use gets a fresh OpenSSH certificate for one account, signed by OpenBao, lasting at most credential_ttl. It needs the SSH signer's own login in openbao.ssh and the SSH role kit (deploy/openbao-role-kit/ssh/), and each host must fetch Bouncer's revocation list (deploy/ssh-krl/). Requesters connect with bouncer ssh (Use the CLI).
This page's SSH example was not run. A separate fake-data test exercised SSH issuance, host trust, KRL delivery and retirement in a disposable systemd container (SSH revocation). It establishes no real-host or production acceptance.
Personal credentials
personal_credentials lets people create their own credentials from the apps, in a storage area you define (a KV mount and a path prefix), and share them with other people or groups. Each area has ceilings for the token lifetime and durations. It's off unless you add the section. The full set of options is in the config file reference.
Keeping the two lists in step
Every resource with kv entries must also be in the role kit's resources file, with the same ID and paths. On 0.5.6 and earlier, a wrong role ID can stop start-up. From 0.5.7, a missing or wrong role or policy refuses only that resource with 503 resource_not_provisioned. If only the KV paths differ, issuing a token can succeed but OpenBao refuses its secret read with "permission denied". Change both files together, run ./setup.sh for the kit, then restart Bouncer for a new resource.
Credential expiry, replacement and history
Credential lifecycle (the lifecycle setting) lets a person expire a stored
value, now or on a schedule, and save a replacement under the same
credential. The credential's ID, name, folder, owner, sharing and the
reference that scripts and agents use to fetch it stay the same; only the
value changes. Each save creates a new version of the secret at the same
path in OpenBao's KV version 2 store.
It is off by default, and the operator chooses whether to enable it for a resource or a personal storage area. Lifecycle first appeared in 0.5.3. The device-key checks here need Bouncer 0.5.7 on both the server and the app. For source builds, record the commit used to build each component. For a server built with the Compose kit's default image name, check its revision label after building the image:
docker image inspect localhost/bouncer-server:local \
--format '{{index .Config.Labels "org.opencontainers.image.revision"}}'
Use your own image name if you changed it. Compare the label with the
source commit you chose to build. The /v1/health
version string alone could not identify these changes in the earlier tests:
source builds tested before the 0.5.7 version bump still reported
0.5.6+33. Check
Platforms and status and the
upgrade instructions before changing configuration.
Verification on 18 November 2026: these procedures were run with fake data, through the server's API and operator commands, against a server built from source after 0.5.6. Steps changed after that run were run again. App screens, real hardware keys, downstream sessions and rollback to a server without lifecycle support weren't run.
What expiry and replacement change
| Action | Effect |
|---|---|
| Expire now | Bouncer stops handing out the current value and tries to revoke the OpenBao tokens it issued for it, including unused wrapping tokens. A wrapping token lets the requester collect a response from OpenBao once; for a personal credential, that response holds the value. Failed revocations are recorded and retried. The app reporting the expiry doesn't mean every revoke at OpenBao has succeeded |
| Schedule expiry | Bouncer stops handing out the value at the scheduled time, even if its background task runs late. New tokens are issued to end no later than that time. Bouncer tries to revoke tokens issued before the schedule was set when it processes the expiry, and an outage can delay those revocations |
| Replace | Bouncer saves a new version only if the version the person saw is still current. Existing grants can use the replacement; they belong to the credential, not a version |
Replacing a configured resource does not revoke the OpenBao tokens already issued for it. While a token is still valid, it can read the replacement. Replacing a personal credential tries to revoke its unused wrapping tokens, because the responses they hold could still contain the old value. Neither recalls a value someone has already read.
An expired current value stays unavailable until it is replaced. Bouncer never supplies an older value instead. When lifecycle is on, Bouncer also refuses retrieval if it can't read OpenBao's version metadata.
Expiry does not delete a value. OpenBao keeps the values encrypted in its version history; Bouncer's database keeps version numbers, who made each change, and when. The server handles plaintext during replacement and authorised viewing, as it does for other app saves and views.
A copied password or API key still works at its issuer until it is rotated or revoked there. Expiry and replacement do not close an existing SSH, database or application session. Keep these apart: a grant's end time, a standing grant's review date, a version's scheduled expiry, and a downstream credential being marked rotated are separate things. Keep standing access disabled; enabling lifecycle does not resolve its open policy questions.
Who may do what
These permissions apply while lifecycle is on:
| Operation | Configured resource | Personal credential |
|---|---|---|
| List version history, without values | Its approvers | Its owner and people it is shared with |
| Expire, schedule or remove a scheduled expiry | Its approvers | Its owner, Editors and Managers |
| Replace | Its approvers, with allow_write: true and self_approval: true | Its owner, Editors and Managers |
| View an old version's value | Its approvers, with view enabled | Owner only, where the namespace permits reveal |
Expiring, scheduling, replacing or viewing an old value needs a paired device whose key checks it's you on every use (user verification): a biometric phone key or Windows Hello. The server also applies the resource's key settings. Windows Hello alone does not prove hardware attestation or satisfy every resource policy. See Device keys and user verification.
Viewing an old value is signed and logged separately; it is for authorised
inspection, not a fallback for normal use. Requester keys, the CLI and MCP
cannot manage lifecycle or view old versions. There are no bouncer-admin
commands for history, expiry, scheduling or replacement yet.
Before enabling it
- Check the server and app source commits, and take the usual backups. Make sure you can still administer and recover OpenBao without the credential you're changing.
- Use the role kit from 0.5.5 or later, with its upgrade handling for earlier policies. Follow the kit upgrade instructions in the release or repository; do not copy new scripts over an old kit's files and assume the upgrade is complete.
- Check the KV mount's and the secret's
max_versions, and anydelete_version_aftersetting, with your OpenBao administrator. Bouncer refuses a save that would make OpenBao permanently remove (prune) an old version. It can't stop an OpenBao administrator, or an automatic deletion setting, from removing values. - Decide who should be able to expire values and inspect old ones using
the table above. Enabling lifecycle on a resource with
viewenabled also gives its approvers the separate old-value view, and a reload records this as apolicy_loosenedentry in the approval log.
Enable a configured resource
Use this for a stored secret or API key resource with exactly one kv
entry. SSH host resources don't have this option. Upgrade the role kit
before you turn lifecycle on in Bouncer.
-
In the role kit's
resourcesfile, addlifecycleto the resource's line. For the example in step 3, the line is:example-api-key kv apps/example/api-key lifecycleThe
lifecycleword grants the server read access to the secret's version metadata and the mount's settings. It does not grant a value read, metadata changes or deletion. Thewriteandviewwords control their own data permissions. -
Apply and check the role kit as in Install, step 2, including its permission check. Its resource token policies must deny reads that specify
version, so requesters can't bypass current-only retrieval. -
Add
lifecycle: trueto the resource. This example is a resource section to merge into your existing configuration. It permits expiry and history, with app saves, app viewing and self-approval off:resources: - id: example-api-key name: Example API key kind: stored_api_key kv: - mount: kv path: apps/example/api-key fields: [api_key] approvers: [alice] requesters: [alice] lifecycle: true allow_write: false self_approval: false view: "off"If you choose to allow replacement from the app, it also needs
writeon the role-kit line,allow_write: trueandself_approval: true. Self-approval also lets Alice approve her own access requests, so review that policy separately. App viewing needsviewin both places. See Resources and policy. -
For an existing resource, reload from your Compose folder:
docker compose exec bouncer bouncer-admin config reloadA new resource needs a server restart instead.
-
Check the reload succeeded, then read the approval log for any
policy_loosenedentries. The reload output does not show them. From your Compose folder, this exports the last hour and filters those entries:docker compose exec -T bouncer bouncer-admin log export --since 1h \ | jq -c 'select(.kind == "policy_loosened")'Match the entry's time and config revision to your reload. Change
1hif you need a longer period. You can also read the affected person's app History; Audit explains full exports.
To verify, open the credential's Details on an authorised paired app and check that Versions appears. Use fake data to check expiry and refusal of retrieval before relying on the procedure. Check replacement too if you separately choose to permit it.
Enable a personal storage area
A personal storage area is a personal_credentials namespace in the
configuration. The setting applies to every credential in it.
-
Add
lifecycleto the namespace's line in the role kit:personal kv bouncer-personal personal lifecycle -
Apply and check the role kit, as for a resource above.
-
Add
lifecycle: trueto the namespace. This example keeps reveal and automatic approval off:personal_credentials: - id: personal label: Personal credentials kv: {mount: kv, prefix: bouncer-personal} creators: [alice] lifecycle: true ceilings: credential_ttl: 5m durations: presets: [5m, 15m, 1h] min: 1m max: 1h always: false reveal: false always_approved: false -
Reload Bouncer, as above.
Existing values stay at their paths. An old save that Bouncer did not record shows as "Saved (date) outside Bouncer" when OpenBao supplies its creation time, or "Saved before Bouncer kept its history" when no date is available. To verify, check a newly created fake credential and an existing one, including what a shared Viewer and Editor can do. The app's version instructions cover expiry and replacement.
Retention and refused replacements
Bouncer never deletes or destroys an OpenBao version or changes retention settings, and there is no way to confirm pruning an old value. There is no Bouncer retention setting or pruning command. A way to prune deliberately has been proposed but not built.
In OpenBao 2.7.2, the version we checked, the number of versions kept is the
larger of the secret's and the mount's max_versions, or 10 when neither is
set. Lowering a secret's limit below its mount's doesn't make it smaller.
At that limit, Bouncer refuses the next save rather than let OpenBao remove
an old value. Before a replacement can succeed, review and raise the
OpenBao limit that applies. Keep the retained values and their backups
protected as secrets.
Other refused replacements:
- If someone else changed the current version first, the replacement is refused. Reopen the credential and check the new current version before retrying.
- If Bouncer reports that OpenBao's answer was lost, the save may have happened. Check Versions before retrying. A successful but unrecorded save shows as "Saved (date) outside Bouncer", without an author. For a personal credential, this failed response also means the replacement did not revoke its unused wrapping tokens, which may still hold the old value.
- If the current version was deleted (but not destroyed) in OpenBao, Bouncer can't replace it. An OpenBao administrator must resolve that first.
Don't use an old value as a workaround.
Turn lifecycle off
Before turning it off, remove any scheduled expiries you no longer want.
Then set lifecycle: false on the resource or namespace and reload. This is
recorded as policy_loosened in the approval log; read it with the
export command above or in the affected person's app History. The app
no longer shows version history,
old-value viewing or version changes; new personal credentials in that
namespace get no lifecycle history.
Scheduled expiries still take effect. You cannot remove them from the
app while lifecycle is off. Recorded expiries still hold, and saves to
credentials that already have history are still refused if they would
prune an old value. Keep the role kit's lifecycle permission while those
credentials remain in use. Without it, Bouncer can't read their version
metadata, so retrieval and saves can fail. Turning the setting off doesn't
reset expiries and isn't a way round the retention limit.
If that permission has already been removed, put lifecycle back on the
role-kit line, apply and check the kit, then either enable lifecycle and
replace from the app, or leave it off and save a new value through Edit.
Do not remove database history rows to bypass an expiry.
Restore or roll back
A database restore loses expiries recorded after its backup. Before reopening access, use the approval log kept off the server to identify those versions, then expire them again or save replacements. Check the current version for each credential first. If the log does not cover the whole period, keep access closed until you have reconciled every value that may have been expired. Also follow the other restore reconciliation steps.
Before rolling back to a server without lifecycle support, replace every expired current version while the current server still runs. An older server does not enforce version expiry and could hand those values out again. Rotate external credentials at their issuer as needed, then save the new values; do not re-enter an expired value as its replacement. Turning lifecycle off does not provide this protection. Follow the rollback procedure as well.
People, requesters and devices
Bouncer has three kinds of identity. This page explains each one and the bouncer-admin commands that manage them.
| Identity | What it is | Credential |
|---|---|---|
| Person | Someone who approves. Listed in the config file | The devices paired as them |
| Requester | Whoever asks for access: a person at the command line, an AI agent, or a host such as a build server | A requester key, a random string starting brk_, kept in a file |
| Device | A phone or PC paired to a person, which shows requests and signs approvals | A device token (starting bdt_) and, for approving, an approval key that stays on the device |
A requester key can ask, but can never approve. Only a signature from a paired device's approval key approves.
Running bouncer-admin
bouncer-admin runs on the server's own machine and talks to the server over a local Unix socket, never the network. With the compose kit, run it inside the container:
cd ~/bouncer/deploy/compose
docker compose exec bouncer bouncer-admin <command>
Whoever can run that command is the admin. There is no separate admin password. Limit who has a shell on this machine and who is in the docker group.
Use docker compose exec -T (with -T) whenever you redirect the output to a file, so that only the command's standard output lands in the file.
People
People are entries in the config file:
people:
- id: alice
name: Alice
Add or remove a person by editing the file and reloading (bouncer-admin config reload). When the server loads the file, it creates a human requester named after each new person, without a key. That's the requester the person uses when they ask for access themselves.
There is no single sign-on in this version. A person proves who they are only by holding a device paired as them, so pair devices in person or over a channel you trust.
Requesters
Create one
Give every person, agent and host its own requester, so the approver can tell them apart and you can disable one without affecting the others.
umask 077
docker compose exec -T bouncer bouncer-admin requester add build-agent --kind agent --owner alice > build-agent.key
-
--kindisagent(an AI agent or other automation acting for a person),host(a machine, such as a build server) orhuman. -
--ownerlinks it to a person. Their own agents' requests are then labelled "Your own agent" on their phone. -
The key alone goes to standard output, so the redirect captures just the key. The explanation goes to the screen. Expected result:
Created requester build-agent (rqr_01..., agent, owned by Alice). Its key is below. It's shown only this once: store it now.
The key is shown only once. Bouncer keeps only a hash of it. Move the file to the machine that will use it (Set up a requester), then delete this copy with shred -u build-agent.key.
A person's human requester already exists, without a key. Give it one the same way:
(umask 077; docker compose exec -T bouncer bouncer-admin requester rotate-key alice > alice.key)
List them
docker compose exec bouncer bouncer-admin requester list
From 0.5.7, the list has a KEY ID column after
LAST USED. Version 0.5.6 and earlier don't have that column. With
fake records, the command prints:
REQUESTER NAME KIND OWNER STATUS KEY ISSUED LAST USED KEY ID
rqr_01jbx1p2r4s6t8v0w2x4y6z8a0 alice human alice active 2026-11-15T06:31:02Z never 6a7b8c9d0e1f
rqr_01jbx1q3s5t7v9w1x3y5z7a9b1 build-agent agent alice active 2026-11-15T06:28:32Z 2026-11-15T06:29:04Z a1b2c3d4e5f6
KEY ID is the first 12 lower-case hexadecimal characters of the hash Bouncer stores for the key. It's a label for telling keys apart. It isn't secret, and it can't be used to make a request. Each new key gets a different KEY ID, even when two are issued in the same second and show the same KEY ISSUED time. A requester that hasn't been given a key shows -, and so does every requester if you run a newer bouncer-admin against an older server. Before you restore a backup, save a copy of this list so you can tell afterwards which keys changed: see Backup and restore, step 4.
Replace a key
If a key may have leaked, or a machine is rebuilt:
(umask 077; docker compose exec -T bouncer bouncer-admin requester rotate-key build-agent > build-agent.key)
The old key stops working at once. Replacing a key suspends the requester's standing grants: a suspended grant never becomes active again, so the requester asks again and someone approves afresh. Its time-limited grants carry on until they end.
Disable one
docker compose exec bouncer bouncer-admin requester disable build-agent
This stops its key, cancels its pending requests and revokes its grants and their tokens. requester revoke is another name for the same command. A disabled requester can't be turned back on, and its name stays taken: if you need it again, create a new requester with a different name.
Devices
Pair a device
See Pair a device.
List devices
docker compose exec bouncer bouncer-admin device list
DEVICE NAME PERSON PLATFORM STATUS APPROVES KEY MEETS PAIRED LAST SEEN
dev_01jbx2a7c9e1g3h5j7k9m1n3p5 Alice's phone alice Android active yes hardware_uv, hardware_key 2026-11-15T06:28:32Z 2026-11-15T06:29:30Z
APPROVES says whether the device has an approval key. A Windows PC shows no until its owner turns on Windows Hello approvals.
KEY MEETS is new in 0.5.7. Version 0.5.6 and earlier don't have that column. It says which key settings that key can satisfy: hardware_uv (require_hardware_uv), hardware_key (require_hardware_key), hardware_key (TPM attested) for a Windows Hello key whose TPM attestation the server verified, or neither. A key that meets neither can still approve resources that set neither, and any key can deny.
Revoke a device
docker compose exec bouncer bouncer-admin device revoke dev_01jbx2a7c9e1g3h5j7k9m1n3p5
From then on the device can't sign in, approve, deny or see anything. Standing grants it approved are ended. Time-limited grants it approved stay active until they end, and the command lists them so you can decide about them. Lost or stolen device has the full procedure.
People can also remove their own device from the app (signing out revokes it on the server). The apps can't revoke other devices; only the admin can.
When someone leaves
- Check which resources list them in
approvers. Where they are the only approver, add another with a paired device and reload before revoking anything. A resource must keep at least one approver or the reload is refused. - Revoke each of their devices (
device list, thendevice revoke). - Disable each requester they own, including their human requester (
requester disable). - Remove them from
people, from every resource'sapproversand from anygroups, then reload and check that it succeeded. Their name stays in old log entries. - If they could read static secrets, rotate those secrets at their source (Copied secrets).
Pair a device
Pairing links a phone or PC to a person. Afterwards the device shows that person's requests and, if it has an approval key, can approve and deny them. This page covers the admin side. The person's side is in the app pages.
Before you start:
- The person must be in
peoplein the config file. - Their device must be able to reach the server's HTTPS address (
instance.url). - For an iPhone, the config must have
pairing.allow_user_verified_keys: true. Every iPhone approval key needs Face ID or Touch ID for each signature, and the server refuses that kind of key unless this is on. - For a Windows PC that will approve, the config must have
pairing.allow_webauthn_keys: true. Windows Hello keys are refused without it. The PC still pairs, but it can't approve.
Both are off by default. After changing them, run docker compose exec bouncer bouncer-admin config reload. Which keys may pair has the full list.
Make a pairing code
On the server, in a terminal big enough to show a QR code:
cd ~/bouncer/deploy/compose
docker compose exec bouncer bouncer-admin device pair --person alice
Expected result: two lines, a QR code between blank lines, then the same information in two other forms:
Scan this with the Bouncer app.
It works once, for 5 minutes, and pairs as Alice.
(the QR code, drawn with block characters, about 20 lines)
Or copy this pairing string and choose Paste pairing string in the app:
bouncer-pair:v1?code=K7QM2XRD9FTA&server=https%3A%2F%2Fbouncer.example.com
Or type these into the app:
Server address https://bouncer.example.com
Pairing code K7QM-2XRD-9FTA
The code expires at 2026-11-15T10:05:00Z.
The code works once, and expires after 5 minutes. --ttl changes that, from 1m to 30m:
docker compose exec bouncer bouncer-admin device pair --person alice --ttl 15m
How each app takes the code:
| App | How |
|---|---|
| Android, iOS | Scan the QR code, or type the address and code |
| Windows | Paste the pairing string, or type the address and code. The Windows app has no QR scanner |
The QR code and pairing string carry the code itself. Treat them like a password for the next few minutes: show them only to the person who is pairing, and don't paste them into chat.
Check the result
docker compose exec bouncer bouncer-admin device list
The new device appears as active, with the name the person gave it. APPROVES is yes for a phone. For a Windows PC it says no until the person turns on Windows Hello approvals in the app's settings (which needs pairing.allow_webauthn_keys: true in the config).
When the new device pairs, the person's other active devices get a "New device paired" alert, and the approval log records device_paired with the address it paired from. If someone gets that alert and didn't pair anything, revoke the new device at once.
Which keys may pair
The pairing section of the config decides which approval keys the server accepts. The defaults are the strict ones:
| Setting | Default | Meaning |
|---|---|---|
allow_software_keys | false | A key kept in software rather than the device's secure hardware. Leave it off; only test setups turn it on |
allow_user_verified_keys | false | Phone keys that need a biometric check on every signature (platform-hw-uv). iPhones only pair with this on, because every iOS key is this kind |
allow_webauthn_keys | false | Windows Hello keys on Windows PCs |
android_attestation | prefer | Whether an Android phone's claim to hold a hardware key must be proven with Google's key attestation: required, prefer or off |
Device keys and user verification explains what each one means for security.
When pairing fails
| What the person sees, or the log says | What to do |
|---|---|
| The code is refused as invalid or expired | Codes work once and for a few minutes. Make a new one |
rate_limited | More than 10 wrong codes from one address in 10 minutes. Wait, then try again with a fresh code |
| The app can't reach the server | The device must reach instance.url over HTTPS. Check the address and the device's network or VPN, and that instance.url matches what your reverse proxy serves |
| An iPhone is refused with "Your server doesn't accept keys that need Face ID or Touch ID, and every approval key on iPhone does" | Set pairing.allow_user_verified_keys: true and reload |
An Android phone is refused under android_attestation: required | The phone couldn't prove a hardware key. Check the app is the official build; see Device keys |
How this was checked
In our test run, a pairing code was made with bouncer-admin device pair, and a command-line stand-in for the phone (a test-only program in the repository) paired with it and then approved and denied requests. The QR code itself, and pairing real Android, iOS and Windows apps, weren't part of that run.
Push notifications
Push wakes a phone when a request arrives. Without push, Bouncer still works: the apps see every request whenever they're open. Push is off until you turn it on.
What a push contains
Bouncer sends pushes through Firebase Cloud Messaging (FCM), Google's push service. FCM is not end-to-end encrypted, so a push carries only an event ID, never a name, resource, reason, duration or credential:
{"v": "bouncer.v1", "event_id": "evt_01jbx3k9n3q5s7t9v1w3x5y7z9"}
The phone wakes, fetches the details from your Bouncer server with its device token, and builds the notification itself. If it can't reach your server, it shows a generic notification instead.
Only three kinds of event are pushed: a new request, a request that closed (so the phone can take the notification down), and a new device paired to the same person. The others (a grant revoked, a grant suspended, a policy loosened) are seen when an app next looks.
What each platform gets
| Platform | Push |
|---|---|
| Android | FCM, with the event ID only |
| iOS | FCM, delivered through Apple's push service. The alert text is fixed ("Open Bouncer to check your inbox."); the app fetches the details when it's opened |
| Windows | No remote push. The Windows app follows events only while it or its tray icon is running. Nothing arrives while it's closed |
Push works only with app builds made for the Firebase project your server sends to. Each app build carries one Firebase project's settings, and a phone's push address belongs to that project only. What matters is the target project, fcm.project_id: the server sends through that project, with a service-account key that is allowed to send for it. Usually the key comes from the same project, but a service account can also be given permission to send for another one.
So, for the apps your people install:
- The official builds, the ones the Bouncer project makes and hands out, carry the Bouncer project's own Firebase settings. Your server can push to them only with a service-account key for that project. This guide doesn't cover getting one; ask whoever gave you access to Bouncer. Without it, leave push off: the apps still work, and see requests whenever they're open.
- Apps you build yourself can carry your own Firebase project's settings (the repository's
app/lib/push/firebase_config.dartsays how). Then use a key from your own project, as below.
To move phones from one Firebase project to another, the server can send through more than one project: see push.fcm_also in the config reference.
Turn push on
You need a Firebase project and its service-account key file, a JSON file you download from the Firebase console under Project settings, Service accounts. The key file is a secret: it lets anyone send pushes as your project. Keep it out of chat, Git and backups that aren't encrypted.
-
Put the key file on the server, readable only by the server's user:
sudo install -m 0400 -o 10001 -g 10001 ./service-account.json /etc/bouncer/secrets/fcm-service-account.json shred -u ./service-account.json -
In
/etc/bouncer/config/bouncer.yaml, replacepush: nullwith:push: fcm: project_id: example-firebase-project service_account_file: /run/secrets/fcm-service-account.json -
In
deploy/compose/.env, add the push compose file, which mounts the key file:COMPOSE_FILE=compose.yaml:compose.push.yaml -
Recreate the container, so it gets the new secret file, and check the log:
docker compose up -d --wait --wait-timeout 120 docker compose logs bouncerWait for the command to succeed before testing push. If it fails or times out, inspect the log and fix the start-up fault first.
A key file that is missing or isn't a service-account key stops start-up, with a message naming the file. Its contents are never shown.
Expected result: when a request arrives, each push sent leaves a log line push sent with the event ID, the device ID, the Firebase project and the delay. The log never holds a phone's push token or the key.
To turn push off again, set push: null and run docker compose exec bouncer bouncer-admin config reload.
If a bad key prevents start-up, set push: null, remove compose.push.yaml (and compose.push2.yaml, if present) from COMPOSE_FILE, then run the Compose start command again. Fix the key before enabling push again.
Moving to another Firebase project
fcm_also needs server build 0.3.8+25 or later.
A phone's push token belongs to the Firebase project in its app build. If you move to a new project while some phones still have the old build, list both: the new one under fcm, the old one under fcm_also, each with its own key file (and add compose.push2.yaml to COMPOSE_FILE for the second file). Bouncer tries them in order. When no push sent line names the old project any more, remove fcm_also. The repository's deploy/compose/README.md has the step-by-step version.
Limits
- If a phone is offline while five or more requests are pending, FCM may drop the pushes for some of them. The requests are still in the app's inbox.
- Pushes are retried for a while if FCM is busy, and given up at the request's deadline.
- A failed push never approves or denies anything.
How this was checked
Not verified for this page. Our test run had push turned off, because it needs a real Firebase project and key. The behaviour above comes from the server source (server/src/push.rs) and its tests, which run against a fake FCM.
Health checks
What to watch
| Check | How | Healthy answer |
|---|---|---|
| Bouncer readiness | curl -s http://127.0.0.1:8080/v1/health on the server, or https://bouncer.example.com/v1/health from elsewhere | HTTP 200 with "status":"ok" and your instance ID. From 0.5.6, backend_* with 503 means OpenBao isn't ready. From 0.5.7, database_unavailable with 503 means PostgreSQL isn't ready. A bare 502 means the proxy could not get an answer |
| The containers | docker compose ps | Both services healthy |
| OpenBao | curl -s https://openbao.example.com:8443/v1/sys/health | HTTP 200 (initialised, unsealed and active) |
| Backups | The newest file in your backup folder, and the backup timer's status | Less than about a day old |
| Disk space | Your usual monitoring | Under 80% on the Docker volumes and OpenBao's data and audit volumes |
| OpenBao secret_id expiry | The date you noted at install | Renew before it passes (Maintenance) |
What Bouncer's health check does and doesn't tell you
GET /v1/health needs no credential. In 0.5.6, its 200 answer
means the process is running and its OpenBao readiness check passed.
From 0.5.7, it also checks PostgreSQL. Version
0.5.6 and earlier do not check the database. Earlier servers, such as
0.3.8, do not have the OpenBao readiness behaviour either.
A healthy answer does not prove every resource's role, secret path, SSH signer operation or push delivery works. Verify those separately with fake data. Readiness results can be cached; health is not a fresh issuance test. This example from our 0.5.0 test run shows the shape of the answer; newer servers add fields:
{"status":"ok","instance":{"id":"example-home","name":"Example home","url":"https://bouncer.example.com","contract":"bouncer.v1","version":"0.5.0+27","android_key_attestation":true,"credential_types":true},"server_time":"2026-11-15T06:28:31Z"}
With the database available, while OpenBao is sealed, can't be reached, or refuses the server's own login, the server stays up and answers 503 with backend_sealed, backend_unreachable or backend_auth_failed, and so does every other public call except revokes and cancels. When Bouncer is unavailable explains each one and who acts.
On health calls, Bouncer refreshes its OpenBao readiness check at most once every 5 seconds. It also checks OpenBao every minute on its own. Monitor OpenBao's /v1/sys/health as well, and alert when it isn't 200: it doesn't depend on Bouncer, and it tells "sealed" (503) from "not initialised" (501).
Database readiness from 0.5.7
From 0.5.7, Bouncer probes PostgreSQL with SELECT 1
on a separate connection, so a busy application connection pool does not
itself fail the probe. Connecting and running the query share a one-second
deadline. The result is cached for five seconds, so an outage or recovery
can take until the next check to appear.
A failed probe returns 503 database_unavailable with Retry-After: 5.
The server stays up and issues nothing while that readiness gate is closed.
It notices database recovery on a later check without a restart. If both
PostgreSQL and OpenBao are down, the database error comes first; after the
database recovers, a remaining backend_* error becomes visible.
This handles a database outage under a running server. Starting the server
still needs PostgreSQL to apply migrations and load state. The source builds tested before the 0.5.7 version bump still reported
0.5.6+33; check their source revision as well as their version.
Resource counts from 0.5.7
From 0.5.7, health can include two optional counts:
unprovisioned_resources for definite token-resource gaps and
provisioning_upgrade_needed for resources whose metadata needs the newer
kit. The endpoint is unauthenticated, so anyone who can reach it can read
these counts. It publishes no resource names or paths through those fields.
They are last-known counts, not fresh network probes. Successful resource
checks are cached for 60 seconds and gaps for five; start-up, reload and
periodic checks refresh them. Health can still be HTTP 200 while a resource
is refused. Alert on a nonzero gap count and investigate with the
preflight report.
A nonzero provisioning_upgrade_needed count means you should apply the current role kit. It doesn't mean there's an outage, and it isn't a passed configuration check.
Provisioning changes have resource_provisioning_changed entries in the
approval log and events naming the resource sent to
its approvers only. Apps fetch those events by polling; there is no push
notification for this event kind. OpenBao outages do not write false
provisioning transitions. This was checked against the source for 0.5.7, and hasn't been run end to end.
The containers' own health checks
The compose file gives each container a health check, which Docker or Podman runs:
- bouncer:
GET /v1/healthon the server's own address, every 30 seconds. It's unhealthy while OpenBao isn't ready and, from 0.5.7, while PostgreSQL isn't ready. Docker doesn't restart it for that; the server recovers after a seal, network or database outage once its dependencies are ready. A refused login needs repair; a login with unsafe powers needs a restart, and a replaced secret_id file needs the container recreated (Maintenance). - postgres:
pg_isready, every 10 seconds, once PostgreSQL has finished its first-start setup.
Both containers use the restart policy unless-stopped, so a crash restarts them, but a container you stopped stays stopped.
With rootless Podman, the health checks run from systemd timers in your user session. Turn on lingering (sudo loginctl enable-linger $USER) so they keep running after you log out. Podman also doesn't start the stack after a reboot by itself: run podman-compose up -d again, or from a systemd user unit of your own.
Diagnose a database outage
In 0.5.6 and earlier, the Bouncer container can remain healthy and /v1/health can return
200 while PostgreSQL is stopped. In our test with fake data, a configured
requester's bouncer resources then failed with HTTP 500 and an internal
error. From 0.5.7, the failed readiness probe instead
reports 503 database_unavailable. The diagnostic steps below apply to both.
From deploy/compose on the server, inspect both containers, including stopped ones,
and their recent logs:
docker compose ps --all
docker compose logs --tail=100 bouncer postgres
In the ps output, check the postgres service's state and health. Older
database failures appear as internal error with a database: cause. From
0.5.7, the readiness check logs the database isn't ready.
PostgreSQL's log
shows shutdowns and start-up failures. If it was stopped, start it:
docker compose up -d postgres
Keep the existing database volume: don't remove it or initialise a new database to get Bouncer working again.
If it is running but unhealthy, fix the cause in its log, such as a full disk or a permission error, then restart it:
docker compose restart postgres
Once PostgreSQL shows healthy, check that it accepts connections:
docker compose exec -u postgres postgres pg_isready --dbname=postgres
Check Bouncer's health again, then run bouncer resources from a client with a configured requester.
That verifies a Bouncer operation using the database without reading a
secret value. A successful pg_isready alone does not verify Bouncer's
database login or query access. If the client still fails, inspect the
Bouncer log for its database connection, socket or authentication error.
For a changed password, follow Change the database password.
Logs
docker compose logs -f bouncer
The server logs at info by default (RUST_LOG in .env sets error, warn, info or debug). Logs rotate at 10 MB, 5 files per container. The log never holds a requester key, device token, pairing code, OpenBao token or secret value. Lines worth alerting on:
- start-up failures (the server stops with a message saying what to fix);
the database isn't ready(from 0.5.7): PostgreSQL failed the readiness probe;the database is ready againrecords recovery;the credential backend isn't ready: OpenBao is sealed, unreachable or refusing the server's login, and the server answers 503 until it's fixed (When Bouncer is unavailable);resource isn't provisionedandresource provisioning is ready again(from 0.5.7): check the named resource and the health gap count;role-kit upgrade needed for the provisioning check(from 0.5.7): apply the current kit and require preflight exit 0;- repeated
revokefailures, which mean OpenBao isn't confirming revokes; BOUNCER_WAIT_FOR_OPENBAO is ignored: remove that setting from.env(it no longer does anything).
How this was checked
The health answer above is the one our test server gave, with only the instance's name, ID and address changed. The test also checked both containers' health checks passed.
The database-readiness description was checked against the source. Automated availability tests cover an unavailable database, its recovery and an exhausted connection pool. The Compose smoke test stops and restarts PostgreSQL and checks that Bouncer did not restart. We haven't run this part ourselves.
When Bouncer is unavailable
This page is for the person who runs a Bouncer server. It explains what people and agents see when Bouncer can't serve, what each message means, and who has to act.
These are outages, not attacks. When a trusted internal client (an agent, the CLI, the app) reports one of the errors below, look for an operational fault first: a sealed vault, a stopped container, a reboot. Nothing here means a key was rejected or someone was refused. Real refusals look different and haven't changed: HTTP 401 or 403, exit code 6, and in the app "This phone was removed" or "Your Bouncer server didn't accept that".
What changes in 0.5.6
The OpenBao readiness changes in this section start in 0.5.6.
The database check described next is from 0.5.7.
Check the server and client builds before expecting the new database message
and exit code. An unreleased source build can still report 0.5.6+33, so
identify it by its source revision as well as its version.
For example, a reboot can leave OpenBao initialised but sealed. Up to 0.5.5, bouncer-server checked OpenBao at start-up and exited when it couldn't log in, so Docker restarted it again and again. With nothing listening, tailscale serve answered every client with a bare 502. Agents saw "The server answered HTTP 502", and a sealed vault was indistinguishable from a broken server.
From 0.5.6 the server stays up when OpenBao is sealed, out of reach, or refuses the server's own login (or, with SSH hosts, the SSH signer's login). Until OpenBao is ready, it answers almost every public call, GET /v1/health included, with HTTP 503 and a problem code that says which of the three it is, plus a Retry-After header. It issues and signs nothing meanwhile. The calls that only take access away, revokes and cancels, still work while PostgreSQL is available (see below). Once OpenBao is ready again it notices by itself, on the next call (at most every 5 seconds) or within a minute. It never unseals OpenBao, and it doesn't retry an unseal. Unsealing stays an operator's job. Automatic unsealing with the VM's TPM is described in OpenBao for Bouncer, but hasn't been verified for this manual.
Some login problems are setup mistakes, not outages, and they still stop start-up with a message saying what to fix: a Bouncer login, or an SSH signer login, with wider powers than the role kit gives (the root policy, for example). In 0.5.6 and earlier, a missing token role for one resource also stops the whole server; from 0.5.7, only that resource is refused (see One resource is not provisioned). If the server started while OpenBao was sealed or out of reach, it can only find out that a login has too much power once OpenBao answers. It then answers 503 backend_auth_failed, and issues and signs nothing, until you fix the login and restart the server.
Database outages from 0.5.7
From 0.5.7, a running server also checks PostgreSQL.
A failed database readiness probe returns 503 database_unavailable
with Retry-After: 5. The server stays up and recovers on a later check
without a restart. Starting the server still needs the database to apply
migrations and load state.
When both PostgreSQL and OpenBao are down, the database error comes first.
Once the database recovers, a remaining OpenBao problem appears as
backend_sealed, backend_unreachable or backend_auth_failed. Work through
both faults; fixing PostgreSQL alone does not unseal or repair OpenBao.
The health checks page
explains the probe and its cache.
In 0.5.6 and earlier, health does not check PostgreSQL and can remain 200 during a database outage. Keep using the database diagnostic route for those versions, and to find the cause on newer versions.
One resource is not provisioned
From 0.5.7, HTTP 503 resource_not_provisioned means that one resource's OpenBao token role or policy is missing or wrong. It comes with Retry-After: 5. Other resources can still work, and health can stay 200 while showing an unprovisioned count. Apply and check the current role kit, then run the configuration check until it exits 0. If the fix adds a new token role, restart the server. The CLI and MCP make one call, without retrying, and report resource_not_provisioned with a message telling the operator to repair the role kit. The CLI exits 7; an MCP tool returns an error to the agent. Exit 7 now includes a server-side setup problem, as well as local configuration problems (Exit codes).
If the kit's permissions are older, or an older kit wrote a policy, the configuration check reports upgrade_needed and exits 4 instead, and the server keeps issuing tokens as before. Upgrade the kit so the check can finish. A sealed OpenBao, a network fault or a refused server login is still reported as an outage (backend_*), never as an unprovisioned resource. This was checked against the source for 0.5.7. The full recovery sequence hasn't been run end to end.
What each message means
| Server answer | bouncer CLI (exit code) | MCP tool error | Apps | What's wrong | Who acts, and how |
|---|---|---|---|---|---|
503 database_unavailable (from 0.5.7) | "The Bouncer server is running, but it can't reach its database (PostgreSQL) …" (16) | The same, plus "… the Bouncer operator needs to check PostgreSQL. Don't retry in a loop" | "Your Bouncer server can't reach its database" | PostgreSQL is stopped, unreachable, or cannot answer Bouncer's readiness probe | The operator follows Diagnose a database outage. The apps, including the Windows check before pairing, ask for the server's database to be fixed |
503 backend_sealed | "The Bouncer server is running, but its vault (OpenBao) is sealed, so it can't issue anything. This is an outage, not a refusal: the operator must unseal OpenBao." (12) | The same, plus "This isn't a denial … Tell the human that the Bouncer operator needs to unseal OpenBao. Don't retry in a loop" | "Your Bouncer server's vault is sealed" | OpenBao restarted (a reboot, a container restart) and is sealed | The operator unseals OpenBao: OpenBao for Bouncer, step 3, or the deployment's own unseal procedure. Nothing to do on the clients |
503 backend_unreachable | "The Bouncer server is running, but it can't reach its vault (OpenBao) …" (13) | The same, plus "… needs to check OpenBao. You can try again in a few minutes" | "Your Bouncer server can't reach its vault" | OpenBao is stopped, crashing, or not reachable from the Bouncer server (network, DNS, TLS, or a proxy in front of OpenBao) | The operator checks that OpenBao is running and reachable at the config's openbao.address |
503 backend_auth_failed | "The Bouncer server is running, but its vault (OpenBao) refused the server's own login … not a refusal of your key" (14) | The same, plus "… needs to fix the server's OpenBao login" | "Your Bouncer server can't sign in to its vault" | OpenBao is unsealed, but refused the server's AppRole login: the secret_id expired or was destroyed (for example by the role kit's emergency stop), or the role_id or secret_id file is missing. The same for the SSH signer's own AppRole, with SSH hosts configured. Or, after OpenBao came back, a login with the wrong powers (see above) | The operator replaces the secret_id, or fixes the file. The server reads the file only when it logs in to OpenBao again; with the Compose kit, recreate the container as the maintenance procedure shows, to remount a replaced file and verify the new login. A login with the wrong powers needs the role kit's setup.sh --verify and a restart |
| A bare 502, 503 or 504 (no Bouncer error in the body) | "Can't reach the Bouncer server: the proxy in front of it got no answer (HTTP 502). The server may be down or restarting." (15) | The same, plus "… needs to check that the server is running. You can try again in a minute" | "Your Bouncer server isn't answering" | tailscale serve (or another proxy) is up, but bouncer-server isn't answering behind it: stopped, restarting, or failed at start-up | The operator checks the container: docker compose ps, then docker compose logs bouncer |
| No connection at all | "Can't reach the Bouncer server (…). Check the address, and that Tailscale is on" (1, current CLI wording) | The same | "Can't reach your Bouncer server" | The client can't reach the address: network, DNS, a required VPN or the whole machine is down. The CLI mentions Tailscale even when your deployment uses another network | Check the configured address and your deployment's network path. Tailscale is needed only if the operator chose it. If others can't reach the server either, the operator checks the machine |
Bouncer's 503 answers are application/problem+json. The detail is the server's own sentence, without credentials or backend connection details. The database readiness log also omits the database address, credentials and driver error.
The CLI's HTTP client doesn't retry a backend_* answer, because it needs an operator. It does retry a bare 502, 503 or 504 a few times, since a restarting server may be back in seconds. The full exit-code table is in Exit codes and errors.
From 0.5.7, database_unavailable uses the CLI's bounded
503 retries, up to four attempts per HTTP call, respecting Retry-After. MCP
reports the outage to the agent and asks it to tell the human, rather than
keep calling the tool in a loop.
The readiness check
From 0.5.6, GET /v1/health needs no credential and checks the process and OpenBao readiness:
- 200 with
"status":"ok": the server is up and OpenBao is ready. From 0.5.7, the database probe has passed too. - 503 with
backend_sealed,backend_unreachableorbackend_auth_failed: the server is up, OpenBao isn't ready. - 503 with
database_unavailable, from 0.5.7: the server is up, PostgreSQL isn't ready. This takes precedence over an OpenBao outage. - 502 with an empty body, or no answer: the server isn't running behind the proxy, or the machine is unreachable.
In 0.5.6 and earlier, health does not check PostgreSQL. It can stay 200 and the Bouncer container can stay healthy while a database outage makes requester calls fail with HTTP 500. Follow Diagnose a database outage to inspect both containers and logs, recover PostgreSQL and verify a real operation. From 0.5.7, the cached readiness probe also needs to pass; a 200 still does not prove every resource can issue a credential.
For example, on the server while OpenBao is sealed (some headers left out):
curl -si http://127.0.0.1:8080/v1/health
HTTP/1.1 503 Service Unavailable
content-type: application/problem+json
retry-after: 30
{"type":"https://contracts.bouncer.invalid/errors/backend_sealed","title":"Bouncer is running, but its vault is sealed","status":503,"detail":"Bouncer is running, but OpenBao, the vault it issues credentials from, is sealed. Nothing can be issued until an operator unseals it. This is an outage, not a refusal.","code":"backend_sealed"}
The container's health check uses the same address, so the bouncer container shows unhealthy while OpenBao isn't ready and, from 0.5.7, while PostgreSQL isn't ready. Docker doesn't restart a container for being unhealthy. A seal, network or database outage recovers on later checks once the dependency is ready. A refused login needs repair; unsafe powers need a restart, and a replaced secret_id file needs the container recreated (Maintenance).
A monitor that calls /v1/health through the proxy can distinguish a healthy answer, a 503 with a Bouncer dependency code, and a bare gateway error or no answer. Inspect the problem code to distinguish OpenBao from PostgreSQL on builds from 0.5.7. Keep monitoring PostgreSQL separately and OpenBao's own /v1/sys/health as well. The latter doesn't depend on Bouncer, and tells "sealed" (503) from "not initialised" (501). Health checks has the full list.
bouncer-admin still works while OpenBao isn't ready, because calls through the admin socket don't wait for OpenBao. You can list requesters and devices, and run the kill switch. These operations still need the database.
Revokes are accepted during an OpenBao outage while the database is available. Besides the admin socket, these public calls still work while OpenBao isn't ready, because they only take access away:
POST /v1/grants/{id}/revoke(bouncer revoke, the MCP revoke tool, and the app);POST /v1/devices/self/revoke, a device signing itself out;POST /v1/requests/{id}/cancel, cancelling a request that's still pending.
The cutoff is recorded at once, so nothing more is issued for that grant. OpenBao can't revoke a token while it's sealed, so the answer lists each such token as revoke_failed, and bouncer revoke says Bouncer keeps trying. The server revokes them at OpenBao once OpenBao is ready again: it tries after 5 seconds, then less and less often, at least every minute, until each token is revoked or has expired. Each token still ends on its own at the time shown. In 0.5.6 every other public call answers 503. From 0.5.7, authenticated host fetches of GET /v1/ssh/krl also work once Bouncer has stored its SSH CA public key. The remaining public calls answer 503, including the ones that could give access back (a decision, sharing, enabling) and disabling or deleting a personal credential, which needs a fresh challenge.
If PostgreSQL is unavailable, revokes and cancels cannot commit their cutoffs.
From 0.5.7, the database gate refuses these public calls
with 503 database_unavailable too. Do not assume a failed change was
recorded; check and repeat it once the database recovers. For an urgent stop
independent of Bouncer, follow Recovery.
SSH certificates are different. In 0.5.6 a revoke is recorded, but hosts cannot fetch the updated revocation list while OpenBao is unavailable: their fetches answer 503. From 0.5.7, Bouncer builds the list from its database and retained CA public keys, including after a server restart while OpenBao is down. An installation that has never read its CA, including one just upgraded from 0.5.6, needs one successful OpenBao read before it can serve the list. PostgreSQL and Bouncer must still be available; new signing always needs OpenBao. Until a host fetches the list, or the certificate expires, a previously issued certificate can still start new logins. Existing sessions are unchanged. See SSH revocation, or Retire a host for an urgent host-side cutoff.
In the server's log
| The log says | Meaning |
|---|---|
the database isn't ready; answering 503 database_unavailable until it is | From 0.5.7: the PostgreSQL probe failed. Check the database; Bouncer stays up |
the database is ready again | From 0.5.7: the probe passed after an outage. A remaining OpenBao outage can still prevent issuance |
the credential backend isn't ready. The server is starting anyway, and answers 503 backend_sealed until it is | Started while OpenBao was sealed. The reason follows, for example Bouncer's "OpenBao is sealed" |
the credential backend isn't ready. Answering 503 backend_unreachable until it is | OpenBao stopped answering while the server ran |
the credential backend is ready again | OpenBao is back, and the server issues again |
the credential backend answers again, but fails the start-up check | OpenBao came back, but Bouncer's login now has the wrong powers. Nothing is issued. Fix it (setup.sh --verify in the role kit) and restart the server. Logged once |
the SSH signer answers again, but fails the start-up check | The same for the SSH signer's login, for example the root policy. Nothing is issued or signed. Fix it (the SSH role kit) and restart the server |
the SSH signer isn't ready. Answering 503 backend_auth_failed until it is | OpenBao refused the SSH signer's own AppRole login. Replace its secret_id and recreate the Compose container, as in Replace the OpenBao secret_id |
bouncer-entrypoint: BOUNCER_WAIT_FOR_OPENBAO is ignored | Remove that line from deploy/compose/.env. It used to hold the server back until OpenBao was unsealed, which meant clients saw a bare 502 |
BOUNCER_WAIT_FOR_OPENBAO
Up to 0.5.5, setting BOUNCER_WAIT_FOR_OPENBAO=127.0.0.1:8200 made the container's entrypoint wait for OpenBao before starting the server. That avoided the restart loop, but nothing listened while it waited, so clients still got a bare 502. From 0.5.6 the setting is ignored, and the entrypoint logs that it is. Remove it from .env. If you run an older server, it's still better than the restart loop.
How this was checked
- The server's behaviour is from
server/src/readiness.rs, and is tested inserver/tests/availability.rs: starting while OpenBao is sealed, unreachable, or refusing the login (the server's or the SSH signer's); nothing issued while sealed; recovering after unseal; a login with too much power still stopping start-up, and an SSH signer with too much power found after an unseal staying refused until a restart; revokes, a device's own revoke and a cancel accepted while sealed and completed at OpenBao after; OpenBao asked at most once every 5 seconds; each problem logged once; and a 401 still being a 401. - The CLI's and MCP's words and exit codes are from
cli/src/http.rsandmcp/src/tools.rs, with their tests. The apps' are fromapp/lib/ui/copy.dart, tested inapp/test/screens/inbox_test.dartandapp/test/desktop/desktop_screens_test.dart. - The OpenBao and proxy cases in the table were also run end to end on a throwaway stack with fake data only (OpenBao 2.7.2 and PostgreSQL 18.6 in containers, the server, and a stand-in for
tailscale serve), before and after the 0.5.6 change. The transcripts aren't published. - The database case was checked against the source, including the server check and client messages. Automated availability tests cover failure, recovery and an exhausted connection pool; the Compose smoke test stops and restarts PostgreSQL and checks that Bouncer did not restart. We haven't run this case ourselves.
- On 17 November, our test run with fake data also revoked an outstanding token while OpenBao was sealed. After the unseal, the revoke reached
revoke_confirmedbefore the token expired.
Everyday maintenance
Run these from ~/bouncer/deploy/compose on the server.
Common commands
| Task | Command |
|---|---|
| Status | docker compose ps |
| Logs | docker compose logs -f bouncer |
| Reload the config after an edit | docker compose exec bouncer bouncer-admin config reload |
Recreate and wait for health (needed for a new resource or an openbao change) | docker compose up -d --force-recreate --wait --wait-timeout 120 bouncer |
| Stop everything | docker compose stop |
| Start again and wait for health | docker compose up -d --wait --wait-timeout 120 |
| Revoke a device | docker compose exec bouncer bouncer-admin device revoke <device-id> |
| Disable a requester | docker compose exec bouncer bouncer-admin requester disable <name> |
| The kill switch | docker compose exec bouncer bouncer-admin revoke --all |
| Re-confirm a standing grant | docker compose exec bouncer bouncer-admin grant review <grant-id> |
| Export the approval log | docker compose exec -T bouncer bouncer-admin log export --since 7d > log.jsonl |
docker compose down removes the containers but keeps the database. docker compose down -v also deletes the database, with every device, requester and the approval log. Don't use -v unless you mean it, and take a backup first.
Replace the OpenBao secret_id
Bouncer's secret_id expires. The role kit asks for 90 days, but OpenBao caps it at the AppRole mount's maximum lease time, which is 32 days unless you raised it (Install, step 2d). Replace it well before it expires, or at once if it may have leaked. Check the new secret_id's actual lifetime as in step 2d, and schedule the next rotation from that.
On the machine with your OpenBao admin token, note the secret_ids that exist now (by their accessors, which aren't secret), then make a new one into a file:
OLD=$(bao list -format=json auth/bouncer-approle/role/bouncer-server/secret-id | jq -r '.[]')
HANDOVER=$(mktemp -d)
(umask 077; bao write -f -field=secret_id auth/bouncer-approle/role/bouncer-server/secret-id > "$HANDOVER/bouncer-secret-id")
scp "$HANDOVER/bouncer-secret-id" admin@bouncer.example.com:
shred -u "$HANDOVER"/* && rmdir "$HANDOVER"
Bouncer reads the role_id and secret_id files only when it logs in to OpenBao again, not on every request, and a running login can stay valid after its secret_id is replaced. Compose also mounts each secret as a file, so a replaced host file can leave the running container reading the old one. So install the new file and recreate the container: that remounts the file and forces a fresh login.
In our test run, skipping the recreate left the old login working until its token was revoked or expired. After that, the server answered 503 backend_auth_failed (0.5.6 and later) until the container was recreated with the new file.
sudo install -m 0400 -o 10001 -g 10001 ~/bouncer-secret-id /etc/bouncer/secrets/bouncer-secret-id
shred -u ~/bouncer-secret-id
docker compose up -d --force-recreate --wait --wait-timeout 120 bouncer
docker compose logs bouncer # look for "bouncer-server is up"
curl --fail --silent --show-error http://127.0.0.1:8080/v1/health
Check the result before you destroy anything. The log must show bouncer-server is up and no AppRole login error, and the curl must succeed. If the wait fails or times out, stop and read the log. If the new login fails, fix the secret_id file, its permissions or the AppRole settings, and recreate the container again. Keep the old secret_ids, and the $OLD list in your admin shell, until the new login works.
If you use SSH host resources, repeat these steps for the SSH signer's own secret_id. With the kit's default prefix, its AppRole path is auth/bouncer-ssh-approle/role/bouncer-ssh-signer and its configured secret file is /run/secrets/bouncer-ssh-secret-id inside the container. Replace the host file you mounted there, rather than bouncer-secret-id, and use the signer's AppRole path for both listing and destroying its old secret_ids. Keep its accessor list separate from $OLD.
Then, on the admin machine:
for a in $OLD; do
bao write auth/bouncer-approle/role/bouncer-server/secret-id-accessor/destroy secret_id_accessor="$a"
done
Change the database password
PostgreSQL reads the password file only when it first creates the database, so changing the file alone locks the server out. Change it inside PostgreSQL first, from a file, so the value never appears on screen, on a command line or in PostgreSQL's log:
NEW=$(mktemp -d)
(umask 077; head -c 32 /dev/urandom | od -An -tx1 | tr -d ' \n' > "$NEW/bouncer-db-password")
{ echo "SET log_statement = 'none'; SET log_min_error_statement = 'panic';"
printf "ALTER ROLE bouncer PASSWORD '%s';\n" "$(cat "$NEW/bouncer-db-password")"
} | docker compose exec -T -u postgres postgres psql --quiet --set=ON_ERROR_STOP=1
sudo install -m 0400 -o 10001 -g 10001 "$NEW/bouncer-db-password" /etc/bouncer/secrets/bouncer-db-password
shred -u "$NEW/bouncer-db-password" && rmdir "$NEW"
docker compose up -d --force-recreate --wait --wait-timeout 120 bouncer
docker compose logs bouncer # look for "bouncer-server is up"
Between the ALTER ROLE and the recreate, the server can't open new database connections, so do the steps together. Recreating remounts the password file; wait for health before continuing. If it fails, inspect both container logs. The kit's own test checked that the old password was refused and the new one stayed out of PostgreSQL's log; it passed in our run.
Standing grants and their reviews
If you allow standing grants (grants with no end time), each one is suspended when its review is due (90 days after it starts, by default, durations.always_review). The approvers' devices get a review_due event a week before. To keep it, re-confirm it:
docker compose exec bouncer bouncer-admin grant review grt_01jbx3n4q6s8t0v2w4x6y8z0a2
The Bouncer project hasn't decided the policy for standing grants yet. Keep them off. Re-confirming is an admin action, not a fresh approval from a device; it is logged as review_confirmed.
Updating the pinned base images
The PostgreSQL image (in compose.yaml) and the Rust and Debian images (in the Dockerfile) are pinned by digest, so they never change by themselves, and so they don't pick up security fixes by themselves either. Someone has to update the digests from time to time and rebuild. Nothing does this automatically yet.
Upgrade and roll back
The server updates its database itself: each version carries its database migrations (numbered SQL changes), and runs the new ones when it starts. Version 0.5.6 has migrations through 0015. Version 0.5.7 adds more, including 0017, which stores the token records described in Audit. Numbers can be skipped, so check the list in the release you install rather than expecting every number in turn. Back up before starting a new server version. An older image may need the matching database backup to run again.
Check the server's own version. Updating an app or the CLI doesn't upgrade the server, so don't assume a migration has run because a client is newer. The Bouncer project's own production server runs build 0.3.8+25. Version 0.5.7 is published as a private GitLab release (Platforms and status).
For 0.5.7, upgrade the role kit first. Follow Upgrade the role kit, even if an earlier upgrade already used the 0.5.6 kit. If you upgrade the server first, it keeps issuing tokens as before but warns that the kit needs upgrading, and you can't turn on credential lifecycle until you upgrade it. Before you switch to the new server image or add a resource, the new server's configuration check (--check-config) must exit 0.
Read the release notes first. Also compare the new compose.yaml, .env.example and bouncer.yaml.example with the ones you have, for settings you need to add. Some config settings are refused by older servers, so a release may ask you to upgrade the server before you use a new setting.
From 0.5.7, upgrade any stand-alone bouncer-admin
with the server. The copy inside the server container is upgraded with it.
A bouncer-admin from 0.5.6 or earlier, such as one a scheduled export job
runs on the host, parses each page but writes entries one by one. It stops at
the first token_issued, backend_revoke, resource_provisioning_changed or ssh_ca_changed
entry with Can't write an entry as JSON. Earlier entries, including those
from the same page, have already been written. With --cursor-file, it does
not save the cursor, so a retry repeats that output. See
Audit.
0.5.7 also adds migration 0018 for provisioning
events and 0019 for retained SSH CA public keys, after 0017 for token
records. This release also adds ssh_ca_changed approval-log entries;
upgrade stand-alone admin clients as described above. Let Bouncer read its
public CA successfully after upgrading and
before rotating the CA. Returning to 0.5.6 requires the pre-upgrade
database backup and, on SSH destinations, the deliberate host version-state
reset after reconciling
revokes made since the backup. Do not delete migration records or edit their
checksums to force the older binary to start: it cannot show the newer log
and provisioning-event kinds for affected approvers. See
Roll back. This was checked against the source. The earlier
release-download test didn't run these later migrations.
Upgrade from a release download
If you installed from a release download, follow the new release's INSTALL-SERVER.md, "Upgrading to a later release". In short: download the new release's files and check them (sha256sum -c bouncer-server-<new version>-SHA256SUMS), load its image and check its labels, and unpack its kit next to the one you run, without the .env lines (upgrade.sh copies your .env across). For 0.5.7, first apply the new kit and run the configuration check as described above. Then run the new kit's upgrade.sh (below) with the new release's values:
cd ~/bouncer-releases/bouncer-server-<new version>/deploy/compose
./upgrade.sh --release ~/bouncer-releases/bouncer-server-<new version> \
--image localhost/bouncer-server:<new short commit> --version <new version> --revision <new commit>
It takes a backup first, and puts the old release back if the new one doesn't come up healthy. The old release's folder and image stay, for a rollback.
Upgrade by hand
This is for a server built from the source:
cd ~/bouncer
git describe --tags --always > ~/bouncer-previous-version # needed to roll back
git fetch && git checkout <new tag or commit>
cd deploy/compose
BOUNCER_BACKUP_DIR=~/bouncer-backups ./backup.sh pre-upgrade # see Backup and restore
docker compose build --build-arg BOUNCER_VERSION="$(git describe --tags --always)" \
--build-arg BOUNCER_REVISION="$(git rev-parse HEAD)"
docker compose up -d --wait --wait-timeout 120
docker compose logs bouncer # look for "bouncer-server is up"
curl -s http://127.0.0.1:8080/v1/health # check the version in the answer
up -d replaces only the containers whose image or settings changed. The database volume stays. If a migration fails, the server stops at start-up instead of serving.
--wait waits for the containers' health checks before the next command.
If it fails or times out, stop here and inspect the logs and
health checks. Do not treat a container that is still
starting as a failed migration. This wait does not verify every resource
or replace the post-upgrade request test.
Afterwards, docker image prune removes old images.
Upgrade with upgrade.sh
deploy/compose/upgrade.sh does the same on the server and puts the old release back if the new one doesn't come up healthy:
deploy/compose/upgrade.sh --release <new release folder> --image <image> \
--version <version text> --revision <commit> [--install-backup-timer] [--dry-run]
The release folder holds the new release's deploy/ folder (for example from git archive <commit> deploy), and the image must already be loaded. In order, the script:
- finds the running release from Docker's labels, and copies its
.envinto the new release with the new image, version and revision; - checks the image exists, and that OpenBao answers and is unsealed (otherwise, from 0.5.6, the new server would answer 503 and the upgrade would roll back);
- stops the server, so nothing changes after the backup, and takes a backup with
backup.sh; - starts the new release and waits for
/v1/health(240 seconds by default,BOUNCER_WAIT); - if that fails, restores the backup (only when the new server ran migrations) and starts the old release again, then exits 1;
- on success, records the new release in
CURRENTand the old one inPREVIOUSin the releases folder.
--dry-run prints the new .env without changing anything. --install-backup-timer also installs the daily backup timer (Backup and restore).
Build elsewhere with ship.sh
For a server too small to compile Rust, deploy/compose/ship.sh builds the image on the machine you run it on, from exactly one commit, copies the image and that commit's deploy/ folder to the server over SSH, and runs upgrade.sh there:
deploy/compose/ship.sh admin@bouncer.example.com <commit> [--version <text>] [--dry-run] [--install-backup-timer]
Run it from a clean checkout that has the commit. On the server it needs Docker, and sudo -n for mkdir, tee and chmod under /opt/bouncer. Each release lands in /opt/bouncer/releases/<full commit>. Old releases and images aren't removed, so a rollback stays possible.
ship.sh also uses sudo -n chown on the destination, so its account needs that permission.
Roll back
Going back to an older version after a newer one has migrated the database doesn't work by itself. The older server refuses a database that has migrations it doesn't know. So a rollback is a restore of the backup you took before the upgrade. Everything that happened since that backup is lost, and the restore caveats in Backup and restore apply. Read that section first.
Migration 0017, from 0.5.7, is one of these. To go
back to 0.5.6, restore the pre-upgrade backup. Do not delete migration
records to make the older server start: it cannot show the new token
records, so the app's log fails for approvers once a token has been issued,
and so does the export.
A source build reuses the image name localhost/bouncer-server:local, so the upgrade replaced the old image and you rebuild it before you start anything. A release download keeps each image under its commit name, so you load the old one. Do it in this order:
-
Do restore steps 1, record how things stand, and 2, cut off access, while the new version still runs.
Before stopping Bouncer, save the newer database and export the full approval log from the current release's Compose folder. The export needs the running server's admin socket. Keep both files off this server before continuing; the log enables the exact requester-key reconciliation in restore step 4 if it covers every entry since the pre-upgrade backup. Use your own backup host and a private destination folder:
ROLLBACK_DUMP=$(BOUNCER_BACKUP_DIR=~/bouncer-backups ./backup.sh before-rollback) (umask 077; docker compose exec -T bouncer bouncer-admin log export > ~/before-rollback-log.jsonl) scp "$ROLLBACK_DUMP" ~/before-rollback-log.jsonl backup-admin@backup.example.com:/srv/backups/bouncer/Check that the dump, log export and off-server copy all succeeded before continuing. If the log is incomplete, rotate every active requester key during reconciliation.
-
Stop the current server from the folder it runs from: the new release's
deploy/composefor a release download, or~/bouncer/deploy/composefor a source build. Rundocker compose stop bouncerthere. Then use the route that matches your installation:From a release download: use the old release's image and compose kit, with the
.envyou kept before the upgrade. No source checkout or image build is needed. In the folder holding the old download, verify its sums as in Install, step 1a. For 0.5.5, check, load and inspect it:sha256sum -c SHA256SUMS --ignore-missing gunzip -c 'bouncer-server-<old version>-image.tar.gz' | docker load docker image inspect 'localhost/bouncer-server:<old short commit>' \ --format '{{index .Config.Labels "org.opencontainers.image.revision"}} {{index .Config.Labels "org.opencontainers.image.version"}}'The labels must match the old release's
INSTALL-SERVER.md. If you still have the old release folder and its.env, use them. If not, unpack the old compose archive and restore its.envfrom your pre-upgrade copy:tar -xzf 'bouncer-server-<old version>-compose.tar.gz' -C ~/bouncer-releasesDo not unpack over an existing release folder. In its
deploy/compose, confirmBOUNCER_IMAGE,BOUNCER_VERSIONandBOUNCER_REVISIONname the old release, with the same Compose project name, database volume and config paths as before. Stay in this old kit folder for steps 3 and 4:cd "$HOME/bouncer-releases/bouncer-server-<old version>/deploy/compose"From a source checkout: check out the version you recorded before the upgrade and build its image, as in Install, step 4:
cd ~/bouncer/deploy/compose git checkout "$(cat ~/bouncer-previous-version)" docker compose build --build-arg BOUNCER_VERSION="$(git describe --tags --always)" \ --build-arg BOUNCER_REVISION="$(git rev-parse HEAD)" -
For both routes: if the new version added settings the old one refuses (for example
require_hardware_keybefore 0.5.7,credential_typebefore 0.5.0, orpush.fcm_alsobefore build0.3.8+25), take them out of/etc/bouncer/config/bouncer.yamlnow. The old server will not start with them. Removing a security setting such asrequire_hardware_keylets weaker keys approve on the older server. Tell the affected approvers, or keep the resource out of use until you upgrade again.Do restore step 3, replace the database, without its last two lines (
upandlogs). Use the pre-upgrade dump that matches the old server. This discards database changes made since that backup. Use the lists and off-server log you saved above for reconciliation in restore steps 4 and 5. Do not edit_sqlx_migrationsor reverse SQL changes by hand. -
Start the old version from its compose folder.
up -drecreates the container using the old image selected in that folder's.env:docker compose up -d --wait --wait-timeout 120 docker compose logs bouncer # look for "bouncer-server is up" curl -s http://127.0.0.1:8080/v1/health # the old version in the answer -
Carry on with restore steps 4, 5 and 6. For SSH destinations, reconcile revokes made since the backup before resetting their version state. Restoring the database, including a rollback to 0.5.6 after migration
0019, can put the server's KRL version below what hosts already hold.
Release notes that say a version adds no migrations don't mean an older server can safely use the newer database. Roll back with the matching backup as above, or follow the release's own rollback instructions if it has them.
upgrade.sh does a rollback for you when the new release fails its health check during the upgrade: it starts the old release folder with the image it ran before, so nothing needs rebuilding as long as you give each release its own image name (ship.sh names each one after its commit). A rollback later, after people have used the new version, is a restore as above.
Reset host version state after a restore or rollback
A database restore also puts back the SSH revocation list's version number. Hosts may already hold a higher version, and they refuse lists with a lower version, so later revokes may not reach them. Going back to 0.5.6 with the pre-upgrade backup has the same risk. Keeping the version number across a restore is not implemented and is tracked in issue #283.
Resetting a host's version state removes that protection, so do it only when all of these are true:
- you have confirmed that the restored server is the one you meant to restore;
- you have put back the revokes made since the backup, as in the restore procedure;
- the longest
credential_ttlof your SSH host resources, plus five minutes, has passed since you stopped the old server. The restored database doesn't know about grants made after the backup, so it can't revoke their certificates. Waiting lets them expire, so a restored list can't let one of them log in again.
If you can't reconstruct a revoke, wait until every certificate it affected has expired, or keep that account's Bouncer principals file removed until then. A successful fetch doesn't make up for missing revoke history. Don't reset because of an older-version error you can't explain.
Before you start, open a separate SSH session to each host without using a Bouncer certificate, and keep it open, so you can still get in if something goes wrong.
On each host:
-
Stop scheduled fetches and any fetch in progress:
sudo systemctl stop bouncer-krl.timer sudo systemctl stop bouncer-krl.service -
Remove only the version file:
sudo rm -f /var/lib/bouncer-krl/versionThat's the kit's default path. If
/etc/bouncer/krl.envsetsBOUNCER_KRL_STATE_DIR, remove theversionfile in that folder instead, and use the same path in step 4. Don't remove the installed list (/etc/ssh/bouncer/revoked.krl), the host's trusted SSH CA public-key file (/etc/ssh/bouncer/trusted-user-ca.pub) orlast_ok. -
Fetch the list from the restored server. Use the service, which reads
/etc/bouncer/krl.env; running the pull script directly doesn't read it:sudo systemctl start bouncer-krl.service -
Check that the fetch succeeded and installed a list from the restored server:
journalctl -u bouncer-krl.service -n 20 --no-pager sudo cat /var/lib/bouncer-krl/versionIf the fetch failed, stop here. The host keeps its installed list and its record of the last successful fetch. While the timer is stopped, no scheduled fetch runs to report staleness, so keep checking it yourself with
sudo /usr/local/sbin/bouncer-krl-pull --check. It reportsSTALEonce the freshness limit passes. If/etc/bouncer/krl.envsetsBOUNCER_KRL_STATE_DIRorBOUNCER_KRL_MAX_AGE, give--checkthe same settings. This only checks freshness; fix the cause, then repeat step 3. -
Once the fetch has succeeded, resume scheduled fetches:
sudo systemctl start bouncer-krl.timer systemctl list-timers bouncer-krl.timer
From then on, the host again refuses any list with a lower version than the one it just installed.
The version reset, and what happens when a fetch fails and recovers, were checked with real KRL files and the unmodified pull script against a local fake server. This wasn't a production restore or a test on a physical host.
The OpenBao role kit
Run the role kit from the same release as the server (deploy/openbao-role-kit), with your admin token. For 0.5.7, do this before switching the server, as described above; for earlier releases, do it after each upgrade.
Copy resources and kit.env from the old release's deploy/openbao-role-kit into the new one first, and ssh/ssh-resources if you use SSH hosts. Run the kit and emergency stop from that folder afterwards. Without kit.env, defaults apply: using --accept-unrevocable-tokens could replace settings such as address binding with those defaults.
./setup.sh --verify # what differs from what this version of the kit writes
./setup.sh # apply it
./setup.sh --verify # must now exit 0
From 0.5.3, the kit's resource policies also stop issued tokens reading older versions of a secret (?version=N). On an install set up by a kit up to 0.5.2, the first --verify lists each resource policy as OLDER, not DRIFT, and setup.sh upgrades them without --accept-unrevocable-tokens. On an install set up by the 0.5.3 or 0.5.4 kit, nothing should be OLDER. When moving from the 0.5.6 kit to the next release's kit, the first --verify also lists policy bouncer-server as DRIFT: the earlier policy lacks the read-only provisioning lines, and setup.sh restores it without a flag. That one is expected. Stop and investigate any other DRIFT (deploy/openbao-role-kit/README.md, "Upgrading the kit"). The emergency stop works on an install that isn't upgraded yet.
After setup.sh, check that bouncer-server (or <prefix>-server) has the line # kit-policy-format: 2: bao policy read bouncer-server | grep -x '# kit-policy-format: 2'. Kits after 0.5.5 also show it in ./setup.sh --verify, as ok policy bouncer-server has the format line "# kit-policy-format: 2". The 0.5.3 and 0.5.4 kits didn't write it, and until it's there, the kit relies on weaker checks to tell its own older policies from a hand edit (see "Known limits" under "Upgrading the kit" in deploy/openbao-role-kit/README.md).
Phone and PC apps
Upgrade the server before the apps when a release says so. A newer app checks what the server supports (for example credential_types in the health answer) and doesn't send what an older server would refuse.
How this was checked
The original kit test restarted the stack with the database kept and checked that existing records survived. It did not run the whole rollback procedure.
A later test with fake data followed this page's release-download route from 0.5.5 to the unpublished 0.5.6 build and back, using the matching database backup and the health waits shown above. It checked that the requester, grant and paired device survived. Both versions had the same migrations, so it didn't test going back across a database change. A local copy stood in for the copy to the example backup host, so copying to another machine wasn't tested.
That run used a software stand-in for an approving device and the new kit's upgrade.sh for the upgrade. It did not run a full source-build rollback, ship.sh, or a server without lifecycle support against reconciled data. The source-build and ship.sh descriptions are checked against source. For a source build, rebuilding the old image
before starting anything follows from the image name both versions share.
Backup and restore
Everything Bouncer knows is in its PostgreSQL database: devices, requesters (with the hashes of their keys), requests, grants and the approval log. No secret value is ever in it. Still treat backups as sensitive: they show what was approved, for whom and when.
The secrets themselves are in OpenBao, which has its own backups (OpenBao snapshots).
What to back up
| What | How | Notes |
|---|---|---|
| Bouncer's database | backup.sh, daily and before every upgrade | This page |
Your config file and the role kit's resources and kit.env | Keep them in your own Git repository | Without them you can't rebuild the server |
| OpenBao's data | deploy/openbao/snapshot.sh | Plus the unseal material, kept separately |
The secret files in /etc/bouncer/secrets | Don't back them up. Make new ones instead | See Install, steps 2d and 3 |
Take a backup
The server can keep running.
cd ~/bouncer/deploy/compose
BOUNCER_BACKUP_DIR=~/bouncer-backups ./backup.sh manual
Expected result: it prints the new file's path on its last line, for example /home/admin/bouncer-backups/bouncer-20261115T062835Z-manual.dump. In our test run the dump was 52 KB.
backup.sh runs pg_dump inside the PostgreSQL container, checks that the result really is a PostgreSQL dump, and keeps the newest 30. The folder is created with mode 0700 and each file 0600. Its settings:
| Variable | Default | Meaning |
|---|---|---|
BOUNCER_PROJECT | bouncer | The Compose project name |
BOUNCER_BACKUP_DIR | /var/backups/bouncer | Where dumps go |
BOUNCER_BACKUP_KEEP | 30 | How many dumps to keep |
backup.sh uses the docker command. With Podman, take the dump directly instead:
mkdir -p -m 0700 ~/bouncer-backups
podman-compose exec -T -u postgres postgres pg_dump --format=custom --dbname=bouncer \
> ~/bouncer-backups/bouncer-$(date -u +%Y%m%dT%H%M%SZ).dump
Copy backups off the server. A backup that only exists on the machine it protects doesn't help when that machine is lost.
Schedule backups
The kit has a systemd service and timer that run backup.sh daily into /var/backups/bouncer. On a server you installed by hand (Install the server), install them like this:
cd ~/bouncer/deploy/compose
sudo install -D -m 0755 backup.sh /usr/local/libexec/bouncer-backup
sudo install -m 0644 systemd/bouncer-logical-backup.service systemd/bouncer-logical-backup.timer /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now bouncer-logical-backup.timer
systemctl list-timers bouncer-logical-backup.timer
Expected result: list-timers shows the timer with its next run, some time in the next day. To try it at once: sudo systemctl start bouncer-logical-backup.service, then look in /var/backups/bouncer.
The service uses the docker command and the Compose project name bouncer, which is the name compose.yaml gives. With Podman, schedule the podman-compose command above with your own timer instead.
upgrade.sh and ship.sh can install the same timer with --install-backup-timer, but only as part of an upgrade with upgrade.sh, which also needs --release, --image, --version and --revision (Upgrade and roll back). Don't run them just to install the timer.
How often to back up, how long to keep backups and where to copy them are your decisions. Daily, kept for 30 days and copied to another machine, is a reasonable start.
Restore
Read this section to the end before you start. A restore replaces the database with the backup, and brings back everything as it was then, including things you have since revoked. The steps below put those revocations back before anyone can reach the server again.
The commands use docker compose. With Podman, use podman-compose in their place; it takes the same exec -T -u options. For the start step, use podman-compose up -d bouncer, then the curl --retry health check in Install, step 5, instead of Docker Compose's wait flags. We ran the restore with Docker only.
If you are rolling back an upgrade, follow the order in Roll back instead: it loads or rebuilds the old image in the middle of these steps, and leaves out the up and logs at the end of step 3.
What a restore brings back
These are all as they were when the backup was taken:
- Devices revoked since the backup work again.
- Requesters disabled since the backup work again.
- A requester key replaced since the backup: the old key works again, and the new one is refused. Our test run showed this: after the restore, the replaced key was accepted and the new key was refused until we replaced it again.
- Grants revoked since the backup are active again, until their end time.
- Personal credentials: their sharing, their mode, and whether they were frozen, disabled or deleted.
- Credential lifecycle expiries. A version expired after the backup is current and usable again because the record of its expiry is gone.
- The SSH revocation list's version number, if you use SSH host resources. Hosts refuse a list older than the one they have, so revocations stop reaching them until the number catches up.
And two things a restore can't reach:
- Tokens issued after the backup aren't in the restored database, so the kill switch can't see them. They end on their own when their lifetime runs out (5 minutes by default). The role kit's emergency stop can revoke them at once if needed.
- Grants approved after the backup are gone. Their requesters ask again.
1. Record how things stand now
If the server still runs:
docker compose exec -T bouncer bouncer-admin device list > ~/before-restore-devices.txt
docker compose exec -T bouncer bouncer-admin requester list > ~/before-restore-requesters.txt
If it doesn't, write down every device you revoked, every requester you disabled and every key you replaced since the backup. Memory isn't a record. If you also have a recent approval log export (Audit), use it. Without either, plan to check every device and requester with the person it belongs to before step 6, and to replace every requester's key.
2. Cut off access to the server
Stop your HTTPS front end or block client access to it, so only this machine can reach Bouncer. Use the stop procedure for your proxy; the following command applies only to tailscale serve:
sudo tailscale serve --https=443 off
If this machine fetches the SSH revocation list itself, stop that too: sudo systemctl stop bouncer-krl.timer.
3. Replace the database
Run these commands from the Compose folder for the version being restored, with its .env selecting the matching image and the same Compose project name, database volume and config paths.
docker compose stop bouncer
docker compose exec -T -u postgres postgres dropdb --force bouncer
docker compose exec -T -u postgres postgres createdb --owner=bouncer bouncer
docker compose exec -T -u postgres postgres psql -c 'REVOKE ALL ON DATABASE bouncer FROM PUBLIC'
docker compose exec -T -u postgres postgres pg_restore --dbname=bouncer --no-owner --role=bouncer \
--exit-on-error < ~/bouncer-backups/<file>.dump
docker compose up -d --wait --wait-timeout 120 bouncer
docker compose logs bouncer # look for "bouncer-server is up"
up -d --wait returns once the server is healthy. If it fails or times out, keep client access closed and check the container logs and health checks.
If you are rolling back an upgrade, leave out the last two lines (up and logs): wait until Roll back has selected the old image and its matching database before starting Bouncer.
The server now runs on 127.0.0.1 only, because the front end is still off.
4. Put back what was revoked after the backup
Compare the lists from step 1 with the restored ones:
diff <(docker compose exec -T bouncer bouncer-admin device list) ~/before-restore-devices.txt
diff <(docker compose exec -T bouncer bouncer-admin requester list) ~/before-restore-requesters.txt
This is what the device diff looked like in our test, for a device revoked after the backup:
< dev_01jbx2a7c9e1g3h5j7k9m1n3p5 Alice's phone alice Android active yes ...
---
> dev_01jbx2a7c9e1g3h5j7k9m1n3p5 Alice's phone alice Android revoked yes ...
Then:
-
revoke each device that is
activenow but wasrevokedbefore:docker compose exec bouncer bouncer-admin device revoke <device-id>; -
disable each requester that is
activenow but wasdisabledbefore:docker compose exec bouncer bouncer-admin requester disable <name>; -
replace requester keys that changed after the backup. From 0.5.7, the requester list has a
KEY IDcolumn: a short label for each requester's current key, 12 lower-case hexadecimal characters, that isn't secret. For each requester, compare itsKEY IDin the list you saved in step 1 with the one in the restored list. If they differ, the key was replaced after the backup, even when theKEY ISSUEDtimes match. IgnoreLAST USEDhere.If either list has no
KEY IDcolumn, or you couldn't save a list in step 1, you can't compare keys this way. If you have an approval log export, kept off this server, that covers everyrequester_key_issuedentry since the backup, replace the keys it shows were issued after the backup. Otherwise replace every active requester key. MatchingKEY ISSUEDtimes don't prove a key is unchanged.Replace each of those keys, write the new key to a private file, and give it to whoever runs that requester:
(umask 077; docker compose exec -T bouncer bouncer-admin requester rotate-key <name> > <name>.key) -
if you revoked any grant or pulled the kill switch after the backup, or you aren't sure, pull it now:
docker compose exec bouncer bouncer-admin revoke --all
If any resource or personal storage area has lifecycle on, keep outside access closed until you have dealt with expiries. Use the approval log export kept off this server to find every credential_expired entry since the backup. For each affected credential, save a replacement value in OpenBao (for example with bao kv put -mount=<mount> <path> <field>=-, as an OpenBao administrator), rotating it at its issuer first if needed. The - reads the value from standard input. Include every field the secret needs, because kv put replaces its contents. OpenBao's newest version becomes current. If the export does not cover the whole period, replace the current value of every lifecycle credential. Do this before reopening access; expiring a value again through the app needs access open. See Restore or roll back.
If you use personal credentials, freeze every storage area until the owners have checked their credentials, because sharing, modes and deletions are also back as they were:
docker compose exec bouncer bouncer-admin personal freeze --namespace <namespace-id>
The freeze prints the IDs it froze. Then, with each owner:
- Credentials they deleted after the backup: leave them frozen. Their values are still in OpenBao, because deleting a personal credential only marks its record deleted.
- Credentials that were disabled at the backup come back disabled, and
personal freezeleaves them alone. Nobody can use a disabled credential, but its owner can turn it on again, so if they had deleted it since, ask them to delete it again. - For each frozen credential they still want, turn it back on with
bouncer-admin personal reassign <credential-id> --owner <person>, one at a time. It comes back with the sharing it had at the backup, so the owner then removes any sharing they had withdrawn since.
There's no command that lists personal credentials. To see whose each one is, read the restored database:
docker compose exec -T -u postgres postgres psql --dbname=bouncer \
-c 'SELECT id, namespace, owner, name, status FROM personal_credentials ORDER BY namespace, owner, name'
The repository's deploy/compose/README.md ("Backups") has the full procedure.
5. If you use SSH host resources
Wait until the longest credential_ttl of your SSH host resources, plus five minutes, has passed since you stopped the server in step 3. Then, on each host that fetches the revocation list, do steps 1 and 2 of Reset host version state: stop its timer and any fetch in progress, and remove only its version file. Leave the timer stopped. Steps 3 to 5 come in step 6, once access to the server is open again.
The repository's deploy/compose/README.md explains why the order matters.
6. Open access again
Restore the same HTTPS front end or access rule you stopped in step 2. For tailscale serve:
sudo tailscale serve --bg --https=443 http://127.0.0.1:8080
With SSH host resources, each host's timer is still stopped from step 5. On each host, start a fetch yourself (step 3 of Reset host version state), then check that the host took the restored revocation list and that sshd uses it through RevokedKeys. If a fetch fails, follow step 4 of that section.
sudo systemctl start bouncer-krl.service
journalctl -u bouncer-krl.service -g 'bouncer-krl:' -n 1
Expected result: a line saying installed version N (written by the server at ...), or unchanged version N if the host already had the restored list. Check that every host shows the same version. The server can't confirm delivery itself: it reports SSH revocation as unknown with pending: krl_delivery. An open SSH session is unaffected.
Once every host has confirmed the restored list, resume its timer: sudo systemctl start bouncer-krl.timer.
OpenBao snapshots
deploy/openbao/snapshot.sh DIRECTORY saves a Raft snapshot of OpenBao, checks it can be read, and records a checksum. Run it with a dedicated snapshot identity (with read on sys/storage/raft/snapshot), never Bouncer's AppRole or the root token:
BAO_ADDR=https://openbao.example.com:8443 BAO_TOKEN_FILE=~/.openbao-snapshot-token \
deploy/openbao/snapshot.sh ~/openbao-snapshots
A snapshot needs the matching unseal material to be useful, so keep both, separately and encrypted. To restore, use deploy/openbao/restore.sh on an isolated recovery instance, after you have stopped Bouncer and cut off client access. Restoring OpenBao can bring back a secret value you have since rotated, so reconcile revocations afterwards, as for Bouncer's database. The repository's deploy/openbao/README.md has the commands.
Not verified for this page. OpenBao snapshot and restore weren't part of our test run. The project's deploy/openbao/test-in-docker.sh tests them against throwaway servers.
How this was checked
In our test run we took a backup with backup.sh, then replaced a requester's
key and revoked a device, then followed the versions of steps 1, 3 and 4 that
were written at the time, with Docker. The restored server accepted the old
key and showed the device as active; the diff showed both changes; after
step 4 the device was revoked again and only the newest key worked.
That run took place before KEY ID existed, so it did not use the KEY ID
comparison in step 4. That comparison is checked against the source and the
project's automated tests, which replace a key twice in the same second and
confirm each new key gets a different KEY ID. It has not been tried in a
restore run.
The kit's own test (41 checks, all passed) also covers backup and restore.
Steps 2, 5 and 6 (Tailscale and SSH hosts), the personal-credential steps,
the backup timer and Podman were not part of that run; those parts come from
the repository's deploy/compose/README.md and the scripts.
Recovery and emergency stops
This page covers what to do when something is lost or may be compromised. Each section starts with the steps, then explains what they do and don't cover.
A lost or stolen device
A paired device can approve, and may also have displayed or copied values where policy allows it. Treat a lost device as able to approve until you revoke it, and rotate values that may have been exposed.
-
If you need to cut client access at once, stop your HTTPS front end or block client access to it. For a deployment using
tailscale serve, the command issudo tailscale serve --https=443 off. Use your proxy's own stop procedure otherwise. This needs neither Bouncer nor OpenBao, andbouncer-adminstill works. It does not revoke existing OpenBao tokens or copied values. -
Find and revoke the device:
docker compose exec bouncer bouncer-admin device list docker compose exec bouncer bouncer-admin device revoke <device-id>From then on the device can't sign in, approve, deny or see anything. Every standing grant it approved is ended, with its tokens. Time-limited grants it approved stay active until they end; the command lists them with their end times.
-
Decide about those time-limited grants. If you can't tell which approvals were genuine, run the kill switch, which ends every existing grant for everyone. Also suspend personal Always approved uses as described below:
docker compose exec bouncer bouncer-admin revoke --allRevoke the device before the kill switch. The kill switch alone leaves the device paired, so it could approve the next request.
-
Restore your HTTPS front end or access rule, if you stopped it in step 1. For
tailscale serve:sudo tailscale serve --bg --https=443 http://127.0.0.1:8080Then pair the replacement. The person's other devices get a "New device paired" alert.
-
Check the record from the time the device was lost:
docker compose exec -T bouncer bouncer-admin log export --since 2026-11-14T18:00:00Z > lost-device.jsonl
None of these steps can take back a secret a requester already read. If an approval on the lost device may not have been genuine, rotate the secrets it released (Copied secrets).
Lost admin access
In Bouncer, "admin" means whoever can run bouncer-admin on the server's machine. There's no separate admin account or password to lose.
| What's lost | What to do |
|---|---|
| The person who ran the server has left | Anyone with root on the server, or in its docker group, is the admin. Remove the person's shell and group access, then follow When someone leaves for their devices and requesters |
| Your shell access to the server | Regain it the way you would for any machine you own (console, hypervisor, cloud provider). Bouncer has no back door |
| The server itself | Build a new one from the install steps with a new secret_id, restore the latest database backup, and follow the restore procedure in full |
| The config file | Restore it from your Git repository. Without it you can rebuild it from memory, but instance.id must be exactly the old value, or every paired device stops working |
| The OpenBao admin token | Use the admin login you set up on OpenBao, or make a new root token from the unseal shares. With OpenBao 2.5.3 or later that needs a config change and restarts first: see Make a new root token. Bouncer itself never needs an admin token; only the role kit does |
Cut Bouncer off from OpenBao
Use both Bouncer's kill switch and the role kit's emergency stop if something is wrong with Bouncer itself. If you use SSH host resources, stop the separate SSH signer too, as below.
1. Bouncer's kill switch, on the server:
docker compose exec bouncer bouncer-admin revoke --all
It asks you to type yes (or pass --yes from a script), then ends every grant, cancels every pending request and asks OpenBao to revoke every token Bouncer issued. Check its report for any revoke it couldn't confirm. Expected result (from our test run):
Kill switch done. The cutoff committed at 2026-11-15T06:29:05Z: no token can be issued from before it.
Grants revoked: 0
Pending requests cancelled: 0
Tokens confirmed revoked: 0
Tokens OpenBao refused: 0
Tokens with no clear answer: 0
A secret value that was already read can't be recalled. Rotate any that may have been.
It exits 0 when OpenBao confirmed every revoke, and 10 when it didn't. Running it again is safe.
The kill switch ends grants that exist when you run it. It does not switch off Always approved on personal credentials: where allowed, a person's command-line key can get a new grant straight afterwards without a device. Suspend it for every storage area that allows it:
docker compose exec bouncer bouncer-admin personal suspend --namespace <namespace-id>
Then docker compose stop bouncer if you want the server off. To cut access off independently of Bouncer, use both applicable role-kit stops below.
2. The role kit's emergency stop, from the machine with your OpenBao admin token. The role kit (deploy/openbao-role-kit) is the set of scripts that created Bouncer's role on OpenBao. Its emergency stop doesn't need Bouncer at all, so it works even if the server is compromised or gone:
cd ~/bouncer/deploy/openbao-role-kit
export BAO_ADDR=https://openbao.example.com:8443
bao login # your OpenBao admin token
./emergency-stop.sh # asks for confirmation; --dry-run only prints
It destroys Bouncer's secret_ids, revokes Bouncer's logins and every token it issued, and empties the kit's policies. It needs the kit's resources file next to the scripts. Its exit code says what it found:
| Exit | Meaning |
|---|---|
| 0 | Bouncer is cut off. Nothing had been changed by hand, and everything was revoked |
| 1 | Not confirmed: Bouncer may still have access. Something had been changed by hand or couldn't be read, or a step failed. It has still done every step it could, and lists what it found and what to do |
| 2 | Bouncer is cut off, but some token roles named like the kit's (bouncer-issue-*) weren't the kit's, so it left their tokens alone. It lists them and how to revoke their tokens |
3. The SSH signer's emergency stop. If you use SSH host resources, stop the SSH signer too. Its separate OpenBao login is not touched by emergency-stop.sh. In the same kit folder, with BAO_ADDR set and an OpenBao admin login that has the SSH kit's permissions, run:
./ssh/setup-ssh.sh --emergency-stop
It destroys the signer's secret_ids, revokes its logins and empties its policy. Check its report: anything but exit 0 means the stop isn't confirmed. Exit 1 means it couldn't confirm, including when it found no signer under the current kit settings; exit 3 means it couldn't run with this token or OpenBao. Already signed certificates remain usable until expiry (300 seconds by default), or until a host installs the updated revocation list. To stop them on a host at once, remove the account's principals or the host's CA trust as in Retire a host. The SSH stop and re-enable sequence here is checked against deploy/openbao-role-kit/ssh/setup-ssh.sh; it has not been run for this manual.
Bouncer stays cut off until you set the role kit up again. In this order:
- Deal with what each stop reported: fix any problem that prevented it from running, revoke what it lists, and rotate the secrets those credentials could reach. Rerun any stop that wasn't confirmed.
./setup.sh --accept-unrevocable-tokens, which restores the kit's policies../setup.sh --forget-hand-edits, which clears the kit's record of what it found. After a stop that exited 0, run it straight away. After one that found something, run it only once you've dealt with every item in step 1: after this, nothing in OpenBao shows those findings any more, apart from its audit log.- Give Bouncer a new secret_id (Maintenance).
- If you stopped the SSH signer, run
./ssh/setup-ssh.shagain with the samekit.envandssh/ssh-resources. It restores the policy. Make a new signer secret_id as in step 3 of the kit'sssh/README.md, install it as/etc/bouncer/secrets/bouncer-ssh-secret-id, then recreate the container as in Maintenance, using the SSH signer's file instead. Replacing only Bouncer's token-login secret_id does not re-enable SSH.
The kit's README (deploy/openbao-role-kit/README.md, "Emergency stop") explains each step.
OpenBao recovery basics
| Situation | What to do |
|---|---|
| OpenBao restarted and is sealed | Unseal it with two of its three shares (OpenBao for Bouncer). Restarting it again won't help |
| OpenBao's data is lost | Restore the latest Raft snapshot on a fresh instance and unseal it with the source instance's shares (Backup and restore) |
| Unseal shares are lost (Shamir) | With fewer than the threshold of shares, the data can't be unsealed. Keep encrypted copies in more than one place, and test that you can reach them |
| TPM auto-unseal fails | Use your independently tested recovery plan and escrowed seal key. A complete auto-unseal recovery procedure is not published in this manual |
How this was checked
In our test run, device revoke, requester rotate-key, requester disable and the kill switch were run against the test server, and the outputs above are from that run. Later fake-data tests ran the role kit's emergency stop, its re-arm steps with a new secret_id, and sealing and unsealing a real OpenBao 2.7.2 dev sandbox. The SSH signer's stop, Raft recovery, lost unseal shares and TPM auto-unseal were not run.
Audit: what is logged and where
There are three records, each answering a different question.
| Record | Where it is | What it answers |
|---|---|---|
| Bouncer's approval log | Bouncer's PostgreSQL database | Who asked for what, who decided, which grants ended, and what changed in the config |
| The server's log | The container's output (docker compose logs bouncer) | What the server did and why it failed, for troubleshooting |
| OpenBao's audit log | OpenBao's audit device, if you turned one on | Every request made to OpenBao, by Bouncer and by requesters reading secrets |
An accessor identifies an OpenBao token without letting you read secrets with it. An authorised OpenBao operator can use it to look up or revoke that token. Keep full exports private. Bouncer's normal server log shows only the first six characters, which are not a unique token ID.
On 0.5.6 and earlier, bouncer-admin log export includes request and
grant IDs, but no token-issuance entries or accessors. To match an approved
grant to successful secret reads, match its exported grant_id with
auth.metadata.bouncer_grant in OpenBao's audit log. Those read records also
carry auth.metadata.bouncer_issuance, which matches the issuance ID in the
server's log.
For those versions, match a revoke by taking that successful read record's
auth.accessor HMAC and finding the same value in the revoke record's
request.data.accessor. Both records must come from the same OpenBao audit
device. If the token was revoked without ever being read, or its read record
is missing, this link is unavailable.
Match token records to OpenBao
From 0.5.7, the admin export
(bouncer-admin log export) also includes
token_issued and backend_revoke. They are never sent to the device log,
event stream or push notifications. The export carries no OpenBao token,
wrapping token or secret value.
This order is checked against Bouncer's source and an earlier OpenBao test, not yet run end to end with the new export (How this was checked).
| Field | What it identifies |
|---|---|
grant_id, request_id, requester, resource | The grant and its recorded context |
at | On token_issued, when Bouncer sent the issue request; on backend_revoke, when the attempt started. Whole seconds; OpenBao's event is at the same time or shortly after |
token_audit.issuance_id | The particular token or wrapped read |
token_audit.role | The token role at issuance, even if the configuration later changes. It is null for a wrapped personal-credential read, which uses no token role, and for older issuances without a recorded role |
token_audit.accessor | The full accessor, for an exact audit-log match. Omitted when no usable accessor is available: token_audit.accessor_status is withheld if a 2xx reply omitted it or gave an unusable value, or absent if no usable issue reply arrived |
token_audit.revoke_outcome | null on token_issued; on backend_revoke, OpenBao's result: revoke_confirmed, already_expired (OpenBao found no such token), revoke_failed or unknown |
If an audit device logs accessors in plain text (hmac_accessor set to false,
or log_raw on), compare the exported accessor directly. For OpenBao's
normal HMAC-protected audit output, use the following order:
-
Export the approval log with a
bouncer-adminfrom the same version as the server (See it and export it). Find the grant and itstoken_issuedentry. Match laterbackend_revokeentries bygrant_idandtoken_audit.issuance_id. -
Choose the OpenBao audit device whose log you are investigating. An authorised OpenBao operator hashes the full accessor with that device's salt:
ACCESSOR='<token_audit.accessor from the export>' bao write -format=json sys/audit-hash/file input="$ACCESSOR" | jq -r .data.hashReplace
filewith the device's path. Each audit device has its own salt, so repeat this for each device's log. The server log's six-character prefix cannot produce the same hash. -
Look for that hash in the creation-response field from the table below, in
auth.accessoron later uses of the token, and inrequest.data.accessoronauth/token/revoke-accessor. On the creation record itself, the top-levelauth.accessorbelongs to Bouncer's own server token, not the issued one. Bouncer's grant and issuance metadata give another check on successful secret reads.
The accessor depends on what Bouncer released:
| What Bouncer handed out | Exported accessor | OpenBao creation-response field to compare |
|---|---|---|
| Direct token | The issued token's accessor | response.auth.accessor |
| Wrapped token | The inner token's accessor | response.wrap_info.wrapped_accessor |
| Wrapped personal-credential read | The wrapping token's accessor; Bouncer can revoke it while unused | response.wrap_info.accessor |
A wrapped personal-credential read releases the saved value on unwrap. It does not create a new token governing that value's later use. Revoking its unused wrapping token cannot recall a value already unwrapped.
What a missing or repeated record means
token_issued records an observed or possible issuance. Its optional
token_audit.issuance_status marks a refused credential or an uncertain
issuance; a normal release omits that field. None of these records proves
that the caller received or used the credential. backend_revoke records a
backend attempt, not the grant cutoff or the end of a downstream session.
During an OpenBao outage, retries can create repeated revoke_failed
entries. A call that never reached OpenBao has no matching OpenBao audit
event. Local expiry without a
backend call creates no backend_revoke entry. Records are not added for
tokens issued before the upgrade, so revoking one of those afterwards gives
a backend_revoke with no token_issued and a null role. SSH certificates
have neither record: they are not OpenBao tokens, and their revoke is the
KRL entry.
Normal issuance records and backend revoke records commit with their Bouncer state changes. After an issuance failure, Bouncer saves the failure state and conservative lifetime bound first, then tries to write its audit records. A failed audit write logs a warning and keeps that state and the original error. The OpenBao call happens outside those database transactions. If the process stops or the database fails after OpenBao acts and before Bouncer commits, the export may have no record of that call. A failed backend revoke transaction also loses the saved revoke outcome; the sweeper retries and recovers it. A later retry records a later attempt, not the missing one.
If the requester disconnects during issuance, the connector cleans up the token, but its evidence does not reach the server for an export record. A failed cleanup can leave a token until it expires, as reported in the server log.
Refused wrapped personal-credential reads still have no issuance or export record. This path does not revoke their wrapping token; it is never released and expires at its OpenBao wrapping TTL.
A token the server refuses after recording it also has a token_issued record followed by a backend_revoke: for example, when its kind is wrong, it would outlive the request, or the grant ended while OpenBao was issuing it. The credential is not released, and the revoke outcome still needs checking.
A token issue refused by the connector has a token_issued record marked
token_audit.issuance_status: refused. Its attempted revoke has a matching
backend_revoke, including the outcome and the same checked accessor. The
credential was not released; a failed revoke does not prove that it ended.
When a 2xx issue reply omits the accessor or gives an unusable value, the
token record omits it and uses token_audit.accessor_status: withheld.
A lost or unusable answer uses
absent. Both have token_audit.issuance_status: may_have_been_issued, so
they do not establish that a token exists. Bouncer adds no revoke record
without an actual attempt. For a lost answer, the entry's time is the
original issue attempt, not when the failure was recorded.
Without an accessor, use the issuance ID to investigate OpenBao's creation
request. OpenBao's audit log HMACs Bouncer's metadata there, so submit that
ID to sys/audit-hash on the same audit device and look for the result in
request.data.meta.bouncer_issuance on auth/token/create requests. The
transaction and crash limits above still apply: missing Bouncer evidence
does not prove that OpenBao issued nothing.
These logs do not record a child command's later actions, every use of a copied secret, or whether a downstream session ended.
The approval log
Every entry has a time, a kind, and whichever of these apply: the request, the grant, the requester, the resource, the person, the device, the channel (app or notification), the durations, and a short detail. The kinds, as of 0.5.2, with later additions marked:
| Area | Kinds |
|---|---|
| Requests | request_filed, approved, denied, decision_rejected, request_expired, request_cancelled |
Credential lifecycle (from 0.5.3, where lifecycle is on) | credential_expired, credential_expiry_scheduled, credential_replaced, credential_version_viewed, credential_lifecycle_refused |
| Grants | grant_expired, grant_revoked, grant_suspended, review_due, review_confirmed |
| Devices | device_paired, device_revoked |
| Requesters | requester_created, requester_key_issued, requester_disabled |
| Admin and config | kill_switch, config_loaded, policy_loosened |
| Values | secret_written, secret_write_failed, secret_viewed, secret_view_refused |
| Downstream credentials | downstream_rotation_due, downstream_rotated |
| Personal credentials | sharing_changed, sharing_refused |
| Tokens (admin export only, from 0.5.7) | token_issued, backend_revoke |
| Resource provisioning (from 0.5.7) | resource_provisioning_changed |
| Device reports (from 0.5.2) | reported_screenshot, reported_capture_started, reported_capture_stopped, reported_copy, reported_protection_failed |
decision_rejected records an approval that failed a check (a bad signature, a used challenge, a duration outside policy). It is never counted as a decision.
Device reports
From 0.5.2, the apps tell the server when a screenshot, a screen recording or a copy happens on a screen that shows a secret, or on a form where one is being typed. Each becomes one entry whose kind starts with reported_:
| Kind | What the device said |
|---|---|
reported_screenshot | A screenshot was taken |
reported_capture_started, reported_capture_stopped | The screen started or stopped being recorded or mirrored. If a recording is still running when the screen closes, the app sends the stop then, so the app sends a stop for every start. A stop can still be missing from the log, because a report isn't guaranteed to arrive (see below) |
reported_copy | The person copied a value they had viewed. The server only accepts this within an hour of a view of that value on the same device |
reported_protection_failed | Windows couldn't keep Bouncer's window out of screen capture |
These entries are the device's word. The server can't check them, and every one says so in its detail: "reported by the device; not verified by the server". The person, the device and the entry's time come from the server, never from the device.
A missing entry proves nothing. No platform reports every capture:
| Platform | Screenshot | Recording or mirroring | Copy |
|---|---|---|---|
| Android 14 and later | Reported | Reported on Android 15 and later | Reported |
| Android 9 to 13 | Not detected | Not detected | Reported |
| iPhone | Reported | Reported | Reported |
| Windows | Not detected | Not detected | Reported |
Windows keeps Bouncer's window out of captures but can't tell when someone tries. A camera pointed at the screen is never detected, on any platform. Reports wait in the app's memory until they're sent, so one that hasn't been sent when the app closes is lost.
A report entry has one extra object, report, and no other entry has it:
| Field | Meaning |
|---|---|
event_id | An ID the app made for the event. The same event sent twice is recorded once |
observed_at | When the device saw it. The entry's own at is when the server received it |
screen | stored_value (a saved secret was showing; the entry names the resource) or draft (a form; no resource) |
protection | blocked: the app had asked the system to keep the screen out of captures. not_blocked: the platform can't (iPhone), or Windows refused (a reported_protection_failed entry). allowed_by_setting: the person had turned on Allow screenshots. test_build: an internal test build, which never blocks |
view_id | The secret_viewed entry this report followed, if that device viewed the value in the hour before |
An example, with made-up IDs:
{"id": "log_01…", "at": "2026-11-15T19:53:28Z", "kind": "reported_copy", "resource": {"id": "demo-api-key", "name": "Demo API key", "kind": "stored_api_key", "credential_class": "openbao-token", "static_exposure": true}, "person": {"issuer": "bouncer:local", "subject": "alex", "name": "Alex"}, "device": {"id": "dev_01…", "name": "Alex's phone", "platform": "android"}, "detail": "reported by the device; not verified by the server", "report": {"event_id": "00c3bf7a6af3f058e68c5ba48b119720", "observed_at": "2026-11-15T19:53:28Z", "screen": "stored_value", "protection": "blocked", "view_id": "log_01…"}}
The fields that are null in a real entry are left out here. A report never holds an image, a value, anything typed or what was copied: the server refuses a report with any field it doesn't define.
Each device may send up to 30 reports in 10 minutes. After 100 of a device's report requests are refused in 10 minutes, the server stops accepting more from it for a while. Either way the server answers rate_limited and writes nothing.
There's no setting to turn device reports off. What decides whether they're recorded is the server, not a version number: a server that takes them says so in its health answer, and the apps send them only to a server that does. To check yours:
curl -s http://127.0.0.1:8080/v1/health | jq .instance.device_reports
Expected result: true. If it prints null, this server doesn't take device reports, and the apps send it none.
See it and export it
People see the ordinary approval log in the apps. The token records above are available only through the admin export.
Upgrade a stand-alone export command with the server. The bouncer-admin
inside the server container always matches the server. A separate copy, for
example one run by cron on the host, does not. A 0.5.6 or earlier
bouncer-admin cannot write token_issued, backend_revoke, resource_provisioning_changed or ssh_ca_changed records. It stops at the first one with Can't write an entry as JSON. Everything before that entry has already been written, including earlier entries from the same page. With --cursor-file it does not save the new cursor, so later runs repeat that output and stop at the same entry.
Admins export it:
docker compose exec -T bouncer bouncer-admin log export --since 7d > bouncer-log.jsonl
Expected result: one JSON object per line, oldest first, and a note on the screen such as bouncer-admin: Wrote 37 entries to stdout. To carry on from here: bouncer-admin log export --after 37.
| Option | Meaning |
|---|---|
--since, --until | A time such as 2026-11-01T00:00:00Z, or how long ago, such as 24h or 7d. --until is exclusive |
--after <cursor> | Carry on after an earlier export |
--cursor-file <file> | Read the cursor from the file and save the new one there when done. For a job that ships only what's new each time |
--out <file> | Write to a new file with mode 0600 instead of standard output |
To list only the device reports in an export, filter on the kind with jq:
jq -c 'select(.kind | startswith("reported_"))' bouncer-log.jsonl
Expected result: one JSON object per line, each a device report like the example above, and nothing at all if there were none.
For a short table instead (time, kind, person, device, resource, and whether capture was blocked):
jq -r 'select(.kind | startswith("reported_")) | [.at, .kind, .person.name, .device.name, (.resource.name // "(a form)"), .report.protection] | @tsv' bouncer-log.jsonl
Expected result: one line for each report, with tabs between the columns, such as:
2026-11-15T19:53:28Z reported_copy Alex Alex's phone Demo API key blocked
2026-11-15T19:53:29Z reported_screenshot Alex Alex's phone (a form) blocked
With the compose kit, the container's filesystem is read-only, so --out and --cursor-file only work for a path on a writable volume. The simplest approach is to redirect standard output on the host, as above. The read-only setting in compose.yaml, with no writable /tmp, means --out /tmp/x.jsonl inside the container fails with "Read-only file system". This is checked against source.
Ship it somewhere else
The approval log lives on the server it describes. If the server is lost, so is the log, and after a restore you have nothing to compare against. Ship it off the machine regularly, for example from cron on the host:
cd ~/bouncer/deploy/compose && \
docker compose exec -T bouncer bouncer-admin log export --since 25h | logger -t bouncer-audit
Delivery is at least once: each entry's id is unique, so your log store can drop repeats. Nothing in the kit sets this up for you.
From 0.5.7 the export includes full token accessors.
Send it only to a log store that people without OpenBao rights can't read,
and filter out the token_issued and backend_revoke entries first if that
store is shared.
The server's log
RUST_LOG in .env sets the level (info by default). Useful lines: bouncer-server is up, config reloaded, push sent, and start-up errors. The server never logs a requester key, device token, pairing code, OpenBao token or secret value. Container logs rotate at 10 MB, 5 files.
OpenBao's audit log
With the dedicated OpenBao from deploy/openbao, an audit device is already on; with your own OpenBao, turn one on in its configuration (OpenBao for Bouncer). Everything Bouncer does appears under its AppRole's display name, and each requester's secret read appears under the token Bouncer issued for it. Don't configure OpenBao to keep fields such as secret_id in plain text; the role kit's --verify reports that as drift on its own mount.
How this was checked
The export above and the kinds seen in it came from the fake-data test. The read-only filesystem behaviour is checked against compose.yaml. The full list of kinds comes from the contract schema (contracts/schemas/bouncer.v1.json).
The device report entries were sent to our staging server and read back both ways, in the app's log and in the export. That run used a script standing in for a phone, so it shows how the server records a report. Both jq filters above were run on that export, where they picked out the 7 device reports among its 13 entries, and the health check printed true for that server. Detection itself was checked on an Android 16 emulator. It hasn't been checked on a physical phone, and the iPhone code hasn't run on a device yet.
The token-record fields and the order above, from 0.5.7, were checked against the source and its automated export tests.
Those tests cover matching issuance and revoke IDs, pagination, retries and
exclusion from the device log. The OpenBao steps were run earlier on
OpenBao 2.7.2 for a wrapped token. There, the sys/audit-hash result for its
full accessor matched response.wrap_info.wrapped_accessor, the read's
auth.accessor and the revoke's request.data.accessor. That run took the
accessor from a test setup, not from the export, and did not cover direct
tokens or wrapped personal-credential reads. The whole join, from the new
export to OpenBao's audit log, has not been run end to end.
Uninstall
Removing Bouncer means removing its containers and data, its role on OpenBao, and the files on the server. It doesn't touch your secrets in OpenBao.
If you might want the records later, you'll take a final backup and approval log export at the end of step 2, so that they include the kill switch and the sign-outs.
1. End all access
On the server:
cd ~/bouncer/deploy/compose
docker compose exec bouncer bouncer-admin revoke --all
This is the kill switch: it ends every grant and asks OpenBao to revoke every token Bouncer issued. Check its report for any revoke it couldn't confirm.
2. Sign out the apps, and clean up requester machines
Do this while the server still runs, so each sign-out reaches it:
- In each app, sign out. That revokes the device on the server. If someone can't do it now, they can just uninstall the app later.
- On each requester machine, delete the key file (
shred -u ~/.config/bouncer/key) and uninstall the CLI (Install the CLI).
Then, if you want the records, take the final backup and approval log export on the server, and copy them somewhere safe:
cd ~/bouncer/deploy/compose
BOUNCER_BACKUP_DIR=~/bouncer-backups ./backup.sh final
docker compose exec -T bouncer bouncer-admin log export > ~/bouncer-log-final.jsonl
3. Remove Bouncer's role from OpenBao
You need an OpenBao admin token. If you revoked the root token, get one the way you planned in OpenBao for Bouncer, step 5: your own admin login, or a new root token made from the unseal shares.
Run this from the machine with the role kit (on the Bouncer server itself, that's ~/bouncer/deploy/openbao-role-kit, which step 5 deletes, so do this first):
export BAO_ADDR=https://openbao.example.com:8443
bao login # your admin token, unless BAO_TOKEN is already set
cd ~/bouncer/deploy/openbao-role-kit
./teardown.sh --resources resources
It first runs the emergency stop, then deletes the kit's token roles, Bouncer's AppRole and its mount, and the kit's policies, and checks nothing is left. It never touches your KV mounts or secrets. If you used the kit's scoped admin policy, it prints one last command to run with a full admin token (deleting Bouncer's identity entity), and exits 2.
If you used SSH host resources, remove the separate SSH signer too, in this order:
-
On every host, remove Bouncer's CA trust (Retire a host).
-
From the same role-kit folder, run:
./ssh/setup-ssh.sh --teardownIt needs the matching
kit.env,ssh/ssh-resources, thebaoCLI and an OpenBao admin login with the SSH kit's permissions. It removes the signer's AppRole mount, policy and CA signing roles. The CA mount stays. -
Once no host trusts the CA, remove its mount too:
./ssh/setup-ssh.sh --teardown --remove-ca
These SSH teardown commands are checked against deploy/openbao-role-kit/ssh/setup-ssh.sh; this sequence has not been run for the manual. Neither command removes trust from destination hosts for you.
4. Stop and remove the containers and data
On the server:
cd ~/bouncer/deploy/compose
docker compose down -v
-v deletes the database volume. Without it, the database stays on the machine.
Then remove the image and, if you set them up, the backup timer and HTTPS front end:
docker image rm localhost/bouncer-server:local # release download: localhost/bouncer-server:<short commit>
sudo systemctl disable --now bouncer-logical-backup.timer
sudo rm -f /etc/systemd/system/bouncer-logical-backup.service /etc/systemd/system/bouncer-logical-backup.timer \
/usr/local/libexec/bouncer-backup
sudo systemctl daemon-reload
sudo tailscale serve --https=443 off
5. Remove the files on the server
sudo sh -c 'shred -u /etc/bouncer/secrets/*'
sudo rm -r /etc/bouncer/secrets /etc/bouncer/config
rm -r ~/bouncer
The sh -c matters: your own user can't read the secrets folder (it belongs to the server's user, 10001, with mode 0700), so the * must be expanded by a shell running as root. Written as sudo shred -u /etc/bouncer/secrets/*, your own shell can't expand it, shred fails, and the next line would delete the files without overwriting them first.
For a download installation, remove the release folders under ~/bouncer-releases once you no longer need their kit settings or rollback files.
Keep or delete ~/bouncer-backups and /var/backups/bouncer as you decide.
What stays behind
Personal credentials made in the app stay in OpenBao under their storage area's prefix. Removing the database deletes their ownership records. Delete those values in OpenBao if you no longer need them.
Values that requesters read while Bouncer was running stay valid wherever they were copied. If you are retiring Bouncer because of a suspected compromise, rotate those secrets at their source.
How this was checked
The role kit's teardown.sh was run against our sandbox OpenBao, and docker compose down -v removed our test stack. The shred line was checked in a throwaway container, with a root-only secrets folder and an admin user with sudo: the old form failed with failed to open for writing: No such file or directory and left the files, and the sh -c form removed them. The whole page wasn't run in this order against one server.
Troubleshooting the server
Check the logs first: docker compose logs bouncer, and docker compose logs postgres if PostgreSQL is involved. The server's messages say what to fix, and never contain keys, tokens or secret values.
The server doesn't start
The server stops at start-up if its settings are wrong, and Docker restarts it after a pause, so the same message repeats in the log. From 0.5.6, a sealed or unreachable OpenBao, or a refused AppRole login, leaves it running with 503 and the credential backend isn't ready. Earlier servers, such as 0.3.8, can exit and restart instead (When Bouncer is unavailable).
| The log says | What to do |
|---|---|
can't read the AppRole role_id file /run/secrets/bouncer-role-id: ... (before 0.5.6: start-up stops; from 0.5.6: keeps running with 503 backend_auth_failed) | The file is missing, or not readable by user 10001. Redo install step 3 |
bouncer-entrypoint: can't read the database password file ... | The same, for bouncer-db-password |
the config file /etc/bouncer/bouncer.yaml was refused: ... | The reason follows. That's the path inside the container; on the server, edit /etc/bouncer/config/bouncer.yaml. Then docker compose up -d --force-recreate --wait --wait-timeout 120 bouncer |
can't connect to the database: ... password authentication failed | The password file changed after the database was made. Put the old one back, or change the password properly |
can't update auth/token/create/...; run the role kit's setup.sh (0.5.6 and earlier) | The resource is missing from the role kit's resources file, or setup.sh has not run since it was added. These versions stop the whole server. From 0.5.7, only that resource answers 503 resource_not_provisioned (When Bouncer is unavailable) |
the credential backend isn't ready with an error logging in to OpenBao with AppRole (server 0.5.6 keeps running, answering 503 backend_auth_failed) | The secret_id may have expired or been destroyed, or SECRET_ID_BOUND_CIDRS doesn't include the server. Follow Replace the OpenBao secret_id, including recreating the Compose container so the new file is mounted and a fresh login is checked |
the credential backend isn't ready with OpenBao is sealed (answering 503 backend_sealed) | OpenBao is sealed. Unseal it; the server recovers by itself |
BOUNCER_WAIT_FOR_OPENBAO is ignored | Remove the setting from deploy/compose/.env. From 0.5.6 the server doesn't need to wait for OpenBao |
postgres exits with code 2: ls: cannot open directory '/docker-entrypoint-initdb.d/': Permission denied | The checkout isn't readable by PostgreSQL's user, usually because of a strict umask. chmod -R a+rX ~/bouncer/deploy/compose, then docker compose up -d. We hit this in testing |
role "bouncer" does not exist, or the password is refused on a brand-new install | PostgreSQL's first start stopped part way. On a new install only, start over with docker compose down -v and docker compose up -d. Never do this once Bouncer is in use: -v deletes the database |
| A migration error, or the server refuses the database's migrations | You started an older version on a database a newer version migrated. See Roll back |
Config reload is refused
bouncer-admin config reload exits with code 6 and the reason. The old config stays loaded.
| The message mentions | What to do |
|---|---|
isn't valid and a setting | Fix that setting. The message names it, for example defaults.durations: min (2h) is more than max (1h) |
duplicate mapping key | A key appears twice in the same block |
The resource ... is new or The openbao settings changed | These need a recreate and health check: docker compose up -d --force-recreate --wait --wait-timeout 120 bouncer |
Requesters get errors
| The requester sees | Likely cause |
|---|---|
| Exit code 6, the key isn't accepted | The requester was disabled, or its key was replaced. Check bouncer-admin requester list |
Exit code 6, not_requestable | The requester isn't in the resource's requesters list, or the resource doesn't exist |
Exit code 6, duration_not_permitted | The duration is outside the resource's range, or a disabled preset |
| Exit code 12, 13 or 14, "The Bouncer server is running, but its vault …" | OpenBao is sealed (12), unreachable (13), or refusing the server's login (14). An outage, not a refusal: see When Bouncer is unavailable |
| Exit code 15, "the proxy in front of it got no answer" | Your HTTPS front end (for example tailscale serve) is up, but bouncer-server isn't answering. Check docker compose ps and the server's log |
issuance_failed | Bouncer could not get a credential from OpenBao for a reason other than an outage or a missing kit role. Check the server log for OpenBao's reason. |
| Exit code 6 reading from OpenBao, "permission denied" | The role kit's paths don't match the resource's kv entries |
| Requests time out with exit code 4 | Nobody approved in time. Check approvers have paired devices, and that push works, or that they open the app |
Exit codes and errors lists every code.
Approvers don't see requests
- No notification, but the request is in the app: push is off or failing. Check
push sentlines in the log (Push notifications). Windows never gets pushes; the app must be running. - Not in the app at all: the person isn't in the resource's
approvers, or their device was revoked.bouncer-admin device listshows the device's status. - The phone can't approve, only deny: the resource has
require_hardware_uv: trueand the phone's key doesn't verify the user on every signature, or the pairing settings no longer accept the key type (Device keys).
Revokes say "not confirmed"
bouncer revoke or the kill switch exits 10 when OpenBao didn't confirm every token's revoke. The cutoff has still happened: no new token can be issued. The server retries the revokes every few seconds, then every minute, until they succeed or the tokens expire. Check that OpenBao is unsealed and reachable from the server.
Collecting information for a bug report
curl -s http://127.0.0.1:8080/v1/health(the version);docker compose psand the last 100 lines ofdocker compose logs bouncer;- the exact command and its output.
Remove your hostnames and any IDs you don't want to share before you send them. None of these contain secrets.
How Bouncer protects access
This section explains what Bouncer does to protect secrets, what it relies on, and where its protection stops. Known limits lists the limits in one place.
How it works
OpenBao stores the secret values. Bouncer's own database stores information about secrets, requesters and devices, and the record of every request and decision, but not the values. The Bouncer server does handle secret values in plain text when a device views or saves a secret, and when someone creates a personal credential. So the server's own OpenBao login can read, at any time, every secret that's enabled for viewing in the app and every personal credential, and can write where it's configured to. For a request that needs approval, a person signs the decision on a paired device, and the requester can then fetch short-lived OpenBao tokens until the grant ends. Two experimental features can give access without a new approval: existing standing grants, and personal credentials set to Always approved (Approvals and access duration).
What protects what
| Protection | What it does | Where it's enforced |
|---|---|---|
| Signed approvals | Only a signature from a paired device's approval key approves. A requester key or device token can never approve | The server checks every signature, challenge and policy rule in one transaction |
| Exact scope | The signature covers a hash of exactly what was asked: the resource, the requester, the duration and the reason. An approval can't be moved to another request | The device recomputes the hash and refuses to sign if it differs; the server checks it again |
| Short tokens | Each OpenBao token lasts minutes (5 by default), can read only that resource's paths, and never outlives its grant | OpenBao, through the role kit's policies and token roles |
| Scoped OpenBao authority | The role can issue and revoke tokens, read paths enabled for viewing, and read and write personal credential namespaces. It can write configured save paths. OpenBao does not check Bouncer's approvals | OpenBao policies; the role kit's check.sh checks their scope |
| Revocation | A revoke stops new tokens at once and asks OpenBao to revoke those already issued. SSH certificates use a revocation list each host must fetch. From 0.5.7, hosts can fetch it while OpenBao is down, once Bouncer has read the CA public key; in 0.5.6 and earlier they can't (issue #281; SSH revocation) | The server, then OpenBao |
| Values and metadata | PostgreSQL stores hashes of requester keys, device tokens and pairing codes, plus access metadata. Secret values are stored in OpenBao, and handled in server memory when a device views or saves a secret, and when someone creates a personal credential | The server's storage and API paths; this is not end-to-end encryption against the server operator |
| Admin off the network | Admin commands go over a local Unix socket, never the network | File permissions on the server's machine |
Pages in this section
- Approvals and access duration: the two clocks, and what an approval allows.
- Device keys and user verification: how each platform keeps the approval key, and what is really checked.
- Copied secrets and revocation limits: what "revoked" can and can't mean.
- Self-approval and separation of duties.
- What's covered and what isn't.
- Known limits.
Approvals and access duration
An approval and the access it grants are different things, and each has its own limits. The app-side explanation is in Approvals and access duration; this page adds what the server enforces.
Three times
| Time | What it limits | Default | Set by |
|---|---|---|---|
Time to answer (request_wait) | How long a request waits for a decision. After it, the request expires and nothing is granted | 15 minutes (1 minute to 24 hours) | The config file |
| Access duration | How long the grant lasts, from the moment of approval | What the requester asked, unless the approver changes it (1 minute to 365 days) | The requester asks; the approver decides, within the resource's policy |
Token lifetime (credential_ttl) | How long each OpenBao token lasts | 5 minutes (30 seconds to 1 hour), and never past the grant's end | The config file, capped by the role kit |
The server's clock is the only one that counts. Expiry needs no background job: every check compares the current time with the grant's end, so a grant can't outlive its time because a job didn't run or the server restarted.
What an approval allows
During a grant, the requester can fetch as many fresh tokens as it likes, each lasting the token lifetime, and read the resource's secret with them. So a grant is permission to read the secret repeatedly until it ends, not a single read.
What the approver agreed to is fixed by the signature: this resource, this requester, this duration, this reason. If the resource's policy changes afterwards, a pending decision against the old policy is refused, and standing grants on it are suspended.
Ending access early
Access ends early when:
- an approver revokes the grant in the app;
- the requester revokes it itself (
bouncer revoke, or the MCPrevoke_granttool); - the admin disables the requester, or pulls the kill switch;
- the admin revokes the device that approved it, for standing grants only. Time-limited grants approved by a revoked device stay until they end, and the admin is shown a list so they can end them by other means.
A revoke stops new tokens at the moment it's committed, then revokes the tokens already issued. If OpenBao doesn't confirm a token's revoke, the server keeps retrying until it does or the token expires.
None of these can take back a value that was already read: see Copied secrets and revocation limits.
Standing grants ("Always")
The source supports standing grants, which have no end time. The Bouncer project hasn't decided the policy for standing grants yet. Keep them off. They are not an approved feature. If you run a server, turn them off with durations.always: false, and leave always out of the presets.
A related mode is also undecided: "Always approved" for personal credentials, where an owner lets their own credential be used without approving each time. It has two open problems: under Always approved, a person's command-line key gets the value with no device involved, and the kill switch doesn't stop Always approved uses. Keep it off: leave ceilings.always_approved: false (the default) on every personal-credential storage area.
When a server does allow standing grants, the source limits them in these ways:
- each is suspended when its review is due (every 90 days by default), unless the admin re-confirms it;
- each is suspended when its resource's policy changes, when its resource is removed, or when its requester gets a new key;
- a suspended grant never becomes active again; the requester must ask again.
Device keys and user verification
Every paired device holds two secrets of its own:
- a device token, which lets it read the inbox, requests, grants and log, make requests on behalf of its person, and revoke grants. It can't approve;
- an approval key, a private key that signs approvals and denials. It is made on the device and never leaves it.
What "user verification" means (whether someone had to prove they're the device's owner before each signature) depends on the platform and the key. This page says what the current source does, where that differs from release 0.5.6, and what the server can and can't check.
Each platform
| Platform | Where the approval key lives | What it needs before signing | Label |
|---|---|---|---|
| Android, standard key | The Android Keystore: in StrongBox (a separate security chip) when the phone has one, otherwise the main processor's trusted environment (TEE) | The phone must be unlocked. No check on each signature | platform-hw-unlocked |
| Android, biometric key | The same, with the key bound to biometrics | A strong biometric check for every signature. Adding a new fingerprint or face makes the key unusable, so it has to be replaced | platform-hw-uv |
| iOS | The Secure Enclave | Face ID or Touch ID for every signature, with no passcode fallback. Changing enrolled biometrics makes the key unusable | platform-hw-uv |
| Windows | A Windows Hello passkey, through Windows' WebAuthn API | Windows Hello (PIN or biometric) for every signature | platform-sw-uv |
Some details that matter:
- Android: biometric keys are opt-in. A person chooses them when pairing (Confirm every signature with biometrics), and the server must have
pairing.allow_user_verified_keys: true. Without that, an Android key only needs the phone to be unlocked: anyone holding an unlocked, paired phone can approve. - iOS needs
allow_user_verified_keys: trueto pair at all, because every iOS key is a biometric key. The iPhone app is in internal testing (Platforms and status). - Windows Hello keys are labelled
platform-sw-uvin every version. In 0.5.6 and earlier, Bouncer doesn't check TPM attestation. From 0.5.7, the server checks a TPM attestation at enrolment when Windows supplies one and records the result separately; a verified key can then meetrequire_hardware_key, but no real PC has passed that check yet, and keys enrolled before it stay unattested. These keys needpairing.allow_webauthn_keys: true. A Windows PC without a Hello key can see requests but not approve or deny. - Weak biometrics aren't accepted as a stronger path. Android biometric keys require the strong biometric class. There is no option to allow a weaker face unlock.
What the server can prove
The server checks every signature against the key enrolled at pairing, and checks the label recorded then. But the label itself is mostly the device's own claim:
| Claim | Can the server prove it? |
|---|---|
| The signature was made by the enrolled key | Yes, always |
| An Android key is in secure hardware | Only with key attestation (below) |
| An Android or iOS key requires biometrics | Android: only with key attestation. iOS: no; it's the app's word |
| A Windows Hello key is in a TPM | 0.5.6 and earlier don't check it. From 0.5.7 the server checks a TPM attestation at enrolment when Windows supplies one, but no real PC has passed that check yet, and keys enrolled before it stay unchecked |
A modified app with a valid pairing code could claim a stronger key than it has, except where attestation proves it. The platform is part of that claim: a device that says it is an iPhone or a Mac is not asked for attestation, even under android_attestation: required. Keep pairing codes to the right person. In the current source (not yet released), #282 separates that claim from verified key evidence. The default UV-only rule still accepts the claim; operators must explicitly select a verified-evidence requirement to refuse it.
Android key attestation
Android phones can prove their key with key attestation: the Keystore signs a certificate for the new key that chains up to Google. The server checks the chain, that the key is the pairing key, that it was generated in hardware, that it needs the phone unlocked, that a biometric key needs a biometric (from 0.5.7, a biometric only; 0.5.6 also accepts a key that the phone's PIN can unlock instead), and that it belongs to the official Bouncer app.
pairing.android_attestation | Effect |
|---|---|
prefer (default) | A chain that verifies marks the key as attested. A phone without one still pairs, unattested |
required | A device that declares Android and claims a hardware key pairs only with a chain that verifies. It does not stop a modified app that declares iPhone or Mac, whose keys are not attested (issue #282). This remains an Android-specific requirement |
off | The phone's claim is taken as it stands |
Attestation proves facts about one key, not about the rest of the phone: no verified boot, patch level or integrity checks. Checking Google's list of revoked attestation keys isn't implemented.
Requiring biometric approval for a resource
resources:
- id: prod-db-password
# ...
require_hardware_uv: true
With this, only an enrolled platform-hw-uv key with a signed biometric verification value can approve. Standard Android keys and Windows Hello keys can still deny. It can also be set in defaults. This UV-only rule still accepts declared claims, including a modified client declaring iPhone or Mac, unless an operator opts in to verified evidence. Upgrading does not tighten it automatically.
In the current source (not yet released), require_hardware_key: true requires verified Android-key or Windows TPM evidence for the current key, plus a matching per-use verification: Android biometric or WebAuthn UV. A hardware-unlocked Android key still fails. A declared platform-hw-uv label alone fails, under every Android attestation mode. Setting both resource flags requires both verified evidence and the biometric rule; TPM + PIN does not satisfy both. Denials remain independent of these resource flags.
Key proof and the explicit server opt-in
The current source (not yet released) adds Device.key_proof beside the unchanged platform, assurance and attestation fields. bouncer-admin device list shows its status and evidence kind; JSON also shows checked_at.
| Status | What it means for the current key |
|---|---|
verified | The server verified Android-key or TPM evidence for this enrolled key and enrollment challenge |
unverified | Evidence is absent or deliberately unchecked; this includes ordinary iOS and macOS claims |
unsupported | The evidence has no verifier, or there is no approval-key proof path |
failed | Supported evidence was checked and failed |
Proof does not verify the reported platform, OS or app version, whole-device posture, or an individual biometric operation. Recognized historical Android evidence keeps an unknown check time (null); migration does not invent a date. Unknown legacy records never become verified, and stale proof cannot qualify another key or epoch.
Historical Android tee and strongbox records remain verified hardware evidence. For biometric keys recorded before 0.5.7, the verifier only checked that the allowed authentication types included biometrics, so some keys may also accept a device PIN. Re-pair those phones on 0.5.7 or later if biometric-only authentication is required.
The new pairing.require_verified_approval_keys defaults to false. When explicitly set to true, it requires verified evidence when an approval key is installed and whenever it signs, including existing keys after reload. It closes the declared-platform exemption for this key requirement. It cannot be combined with android_attestation: off. Keyless Windows pairing remains request-only; enrollment must then supply verified TPM evidence. Session/status reads, admin pairing and revocation, and self-revocation remain available for recovery.
Once this opt-in is enabled, a key without verified evidence cannot sign anything, including denials and device-settings changes.
A refusal uses 422 assurance_not_accepted with the requirement and proof status. Re-enrol with supported evidence, or ask the operator to review enrollment. Changing a platform or assurance label cannot establish proof. Existing allow_user_verified_keys, allow_webauthn_keys and software-key opt-ins still apply. Apps from this release use the same proof for approval eligibility and signing. No policy is activated on upgrade, and there is no automatic re-enrollment. In particular, an existing deployment using only allow_user_verified_keys: true and require_hardware_uv retains the declared-claim exposure until the operator opts in.
Windows keys enrolled before 0.5.7, or later without TPM evidence, stay unverified; no real PC has yet passed the TPM verifier. RS1 (RSA with SHA-1) attestations are refused. Wider platform, OS and app-version admission belongs to #293. Resources and policy explains the resource settings.
Approving from a notification
When a resource allows it (notification_approval: true, the default) and the person turns it on for their device, an Android phone can approve straight from a notification, for exactly the requested duration. It signs with the same key and the same checks. iOS and Windows don't offer it.
Viewing values on a device
Where a resource allows in-app viewing (view), each view is signed like an approval. It needs a hardware-backed Android or iPhone key, or a Windows Hello key, which Bouncer labels platform-sw-uv. The label does not prove where Windows keeps it. Viewing uses the key's normal check: a standard Android key only needs the phone unlocked; a biometric key asks for biometrics every time. The resource's own key requirements also apply. Each view is logged as secret_viewed.
How this was checked
From the source: the Android Keystore channel (KeystoreChannel.kt, BiometricSigning.kt), the iOS Secure Enclave provider (NativeAppleKeys.swift), the Windows Hello code, the config loader's pairing defaults, and the server's attestation module. These pages don't claim device testing. Testing on physical phones and PCs is separate from this guide, and parts of it haven't been done yet: no real PC has passed the Windows Hello TPM check, for example.
Copied secrets and revocation limits
Most secrets Bouncer guards are static: a password, an API key or a token that stays the same until someone changes it. Bouncer controls who can read a static secret and for how long. It can't control what happens to the value after it has been read.
What a revoke stops, and what it doesn't
When a grant ends, by time or by revoke, Bouncer:
- stops issuing new OpenBao tokens for it, at once;
- asks OpenBao to revoke the tokens it already issued. If OpenBao is unavailable, Bouncer reports the unconfirmed revokes and retries until they succeed or the tokens expire. Check the revoke result rather than assuming every token was revoked.
For SSH access, Bouncer adds revoked certificates to its revocation list. Each host must fetch that list before it refuses them. Until a host fetches the new list or the certificate expires, the certificate can still start new logins. In 0.5.6 and earlier, hosts can't fetch a new list while OpenBao is sealed or unreachable. From 0.5.7, Bouncer serves the list from its database during an OpenBao outage, once it has read the CA public key (issue #281; SSH revocation).
It can't:
- take back a value that was already read. If the requester copied the password into a config file, a log, its memory or (for an AI agent) a conversation, the copy still works;
- close sessions already open. A database connection or SSH session opened while the grant was active may stay open until that system closes it;
- revoke a credential at the system that issued it. A cloud API key or a Proxmox token is valid at its own system until someone removes or regenerates it there.
bouncer revoke says this in its output: A secret value that was already read can't be recalled. If it was read, rotate it.
Rotate what may have leaked
Rotating means changing the secret at its source (a new database password, a regenerated API key) and saving the new value in OpenBao. After that, old copies stop working. Rotate when:
- a grant was approved by mistake, or from a device that was lost;
- a requester's machine or key may be compromised;
- an AI agent was given the value and the conversation may be stored somewhere you don't control;
- someone who could read the secret leaves.
Tracking credentials from other systems
For a resource whose value was issued by another system, add a downstream block to its config (Resources and policy). Bouncer then tracks when a value was released under a grant that has since ended, and marks it due for rotation:
docker compose exec bouncer bouncer-admin downstream list
Rotate each one marked ROTATE yes at its system, update the secret in OpenBao, and record it:
docker compose exec bouncer bouncer-admin downstream rotated example-api-key
Limits of this tracking:
- Bouncer counts any issued token as a possible read. It can't tell whether the value was actually read.
- It only knows about grants. A value copied outside Bouncer (an old
.env, a backup) isn't tracked. - Bouncer never contacts the other system, so it takes your word that you rotated.
- The kill switch ends every grant, so afterwards every released downstream credential is due.
Ways to limit exposure
- Prefer short grants. A 15-minute grant gives a smaller window than a week.
- Use
bouncer execwith a command you trust to avoid returning the value directly to a terminal or model. Check the command's output with fake data first (Patterns for workloads). - Use SSH host resources for SSH instead of a stored private key. Each use gets a certificate that expires within minutes, so there's nothing long-lived to copy.
- Keep secrets you'd hate to rotate away from agents.
How this was checked
The revoke output above is from our test run. The downstream tracking is from the server source and the project's docs/security/downstream-credentials.md, which records a real case: a copied static token kept working at its own system after a Bouncer revoke, as this page describes.
Self-approval and separation of duties
Who can do what
| Role | Can | Can't |
|---|---|---|
| Requester (a key) | Ask, follow its own requests, use its own grants, end its own grants | Approve anything, including its own requests |
| Approver (a person with a paired device) | Approve or deny requests for the resources that list them, revoke grants, see the log | Approve resources that don't list them |
| Admin (the administrator, with a shell on the server) | Pair devices, create and disable requesters, revoke devices, reload the config, pull the kill switch, re-confirm standing grants | Approve or deny directly: no admin command approves a request. But an admin can pair devices and change who approves, so treat admin access as able to approve (see below) |
| Config owner (whoever can change the config file) | Decide who approves what, for how long, and whether self-approval is allowed | Approve on someone's behalf |
In small installations the same person often holds every role. A new approval always needs a signature from a paired device. But an existing standing grant can be used again, and a personal credential set to Always approved lets the people it's shared with get access without a new signature, including through their command-line key. Limit these with the settings in Approvals and access duration.
Self-approval
A person can ask for access themselves (through their own human requester), or own an agent or host that asks. When the same person then approves, the app labels the request Self-approval or Your own agent, and the grant records it.
Whether that's allowed is a per-resource setting, self_approval, which is on by default:
defaults:
self_approval: false # for every resource
resources:
- id: prod-db-password
self_approval: false # or for one resource
approvers: [alice, bob]
With it off, requests from a person's own requesters need another approver. Make sure each such resource lists at least two approvers, or nobody can approve those requests. Denying is always allowed.
Self-approval still has value: the request, its reason and the decision are all in the log, the grant is time-limited, and the approval needs the person's device in hand. But it isn't a second person's check.
Bouncer does not yet ask for an extra check when you approve your own request or your own agent's. The same key and checks apply as for anyone else: with a standard Android key, an unlocked phone is enough. If self-approval needs a stronger check, set require_hardware_uv: true on those resources or turn self_approval off.
A second approver
Every resource needs exactly one approval in this version. Requiring two different people to approve the same request isn't implemented.
The admin and the config owner
Anyone who can change the config file or run bouncer-admin can change who approves, add requesters, and loosen policy. Bouncer limits the damage and makes it visible:
- loosening changes are written to the log as
policy_loosenedand announced to the affected approvers' devices; - there is no admin command to approve a pending request, but an admin can change policy and enrol devices. Treat that authority, and write access to the database, as trusted;
- every admin action that changes access (pairing, revoking, disabling, the kill switch, re-confirming a review) is in the approval log.
To separate these duties, keep the config file in a repository where changes need review by someone else, and keep shell access to the server to a small group.
How this was checked
From the server source (self_approval in the decision checks, the admin API, the config loader) and a test reload in our run, which produced the policy_loosened entry shown in Configure the server.
What's covered and what isn't
This page lists the threats Bouncer's design addresses, with the limits of each. It's based on the project's threat model for requests, approvals and grants, and on the server source. That threat model hasn't been reviewed by anyone outside the project yet.
Covered
| Threat | How Bouncer handles it |
|---|---|
| A requester approves its own request | A requester key can't approve. Only a device's signature does |
| A replayed approval | Each approval signs a single-use challenge, valid for one request and revision. A second use is refused |
| An approval moved to another request | The signature covers a hash of the resource, requester, duration, reason and policy revision. Anything different is refused |
| An approval made on one Bouncer used on another | The instance ID is inside every signature |
| Approval by someone who isn't an approver | The server checks the approver list from the config on every decision |
| Access outliving its approval | Every check compares the server's clock with the grant's end. Tokens never outlive the grant |
| A restart bringing access back | Expiry and revocation are stored and computed, so they survive restarts. Used challenges and pairing codes stay used |
| A slow or failing revoke | Bouncer records the grant's end first, so no new tokens are issued. Revokes run even if the caller disconnects, and failed ones are retried |
| Policy loosened quietly | A reload that loosens policy is logged and announced. Standing grants are suspended when their policy changes |
| Secrets in push notifications | Pushes carry only an event ID. Details are fetched from your server |
| Secret values in Bouncer's database | PostgreSQL holds access records and hashes of requester keys, device tokens and pairing codes, not stored secret values. The server handles plaintext when a device views or saves a secret, and when someone creates a personal credential; OpenBao holds the values |
| Guessing pairing codes | Codes are 60 random bits, single-use, short-lived, and limited to 10 wrong tries per address per 10 minutes |
| A stolen requester key used from elsewhere | The key can ask and use its active grants. A human requester's key can also receive access covered by a personal credential's Always approved mode. Replace the key and review its grants (Approvals and access duration) |
| A lost phone | Revoke the device; it can't approve or see anything afterwards (Recovery) |
| Bouncer itself compromised | The role kit limits which paths the server can reach, but the server can still issue resource tokens, read viewing paths, and read and write personal credential namespaces. The role kit's emergency stop works independently of Bouncer. See "Bouncer chooses the resource" below |
Not covered, or only partly
| Threat | Why |
|---|---|
| A value already read | Can't be recalled. Rotate it (Copied secrets) |
| An unlocked, paired phone in the wrong hands | With a standard Android key, the phone being unlocked is the only check. Biometric keys and require_hardware_uv narrow this |
| A modified app claiming a stronger key | Android attestation can prove the key's hardware and biometric requirements only when the device declares Android. A modified app can declare iPhone or Mac and avoid attestation even under android_attestation: required (issue #282). From 0.5.7, the server checks a TPM attestation at enrolment when Windows supplies one, but no real PC has passed that check yet, and keys enrolled before it stay unchecked (Device keys) |
| Bouncer chooses the resource | OpenBao lets Bouncer issue a token for any configured resource; it doesn't know whether a person approved. A bug or compromise in Bouncer could issue tokens for every listed resource, a few minutes at a time, while it holds a login |
| Issued tokens are bearer tokens | Anyone holding a token can use it until it expires (minutes) |
| Which machine is asking | The host name and client name a requester sends are labelled "reported" because they aren't verified. Any holder of the key can ask |
| The server's own machine | Whoever has a shell there is the admin, and can loosen policy (which is logged). Whoever can write to PostgreSQL can forge grants |
| A restore bringing back revoked access | A database restore revives revoked devices, disabled requesters and replaced keys. The restore procedure puts them back, but needs a record of what changed |
| Source-host binding | A grant can't yet be tied to one requesting machine |
| Revocation timing under load | Revokes are designed to complete within seconds, but there's no timing test against a real OpenBao under load |
Out of scope
- The security of OpenBao itself, the host operating systems, and the phones and PCs.
- What a requester does with a secret once it has it.
- Network-level attacks on your private network or VPN.
How this was checked
From the project's threat model for requests, approvals and grants (in the repository's docs/security folder), which maps each covered threat to an automated test, the role kit's "Remaining risk" section, and the server source.
Known limits
These are the limits of the current source that matter most when deciding what to put behind Bouncer. Where a limit differs in 0.5.6, the page says so. The platforms page has the status of each app.
Server and images
- No high availability. One server, one PostgreSQL database. An outage stops new access through Bouncer. Already issued tokens and SSH certificates keep their own expiry. In 0.5.6, an OpenBao outage prevents SSH hosts fetching a new revoke until OpenBao recovers. From 0.5.7, they can fetch during that outage once Bouncer has retained its CA public key; PostgreSQL must still be available (issue #281). A copied value or established session may outlast the grant (When Bouncer is unavailable).
- Images aren't signed, and there's no published container registry. The private 0.5.5 and 0.5.7 releases include an image download; building from a chosen source commit is another option. 0.5.6 has no GitLab release (Get Bouncer).
Identity
- People are entries in the config file. There's no single sign-on, directory or group sync. Code for an identity-provider verifier exists in the source but isn't connected to anything.
- Pairing is a one-time code, not a sign-in. Whoever uses the code pairs as that person.
- Requester keys are bearer keys in a file. There are no per-host certificates or hardware-bound requester keys yet.
Approvals
- One approval per request. There's no two-person rule.
- Standing grants ("Always") exist in the source, but the Bouncer project hasn't decided their policy yet. Turn them off with
durations.always: false. "Always approved" personal credentials have two open problems; keepceilings.always_approved: false(Approvals and access duration). - Re-confirming a standing grant is an admin action, not a fresh approval from a device.
- Standard Android keys only need the phone unlocked. Biometric keys are opt-in.
- Approving from a notification is Android only.
- Windows gets no push notifications: requests arrive only while the app or its tray icon is running. Device keys and user verification describes the release and verification limits for Windows Hello keys.
Secrets
- A value already read can't be recalled. Rotate it.
- Credential kinds: stored secrets, API keys and SSH host access. There are no database-credential or one-time-password kinds that issue fresh credentials per use.
- A copied value stays on the clipboard if the app can't clear it. Bouncer clears a copy after 30 seconds. On Android that only happens while the app is running. On Windows, from 0.5.1, it also happens when Bouncer quits or the session ends, but not after a crash or a forced close. Before 0.5.1, a Windows copy went to the ordinary clipboard, where Windows clipboard history and cloud sync can keep it; from 0.5.1 Windows keeps it out of both.
Operations
- Two lists to keep in step: the config file's resources and the role kit's
resourcesfile. - A new resource or an OpenBao change needs a restart.
- The approval log lives on the server. Nothing ships it elsewhere unless you set it up (Audit).
- A database restore brings back revoked access until you reconcile it (Backup and restore).
- The kit's example front end is
tailscale serve. Neither it nor any other reverse proxy was tested end to end for these pages (TLS and networking). - Push needs a Firebase key for the same project as the app builds. The official builds use the Bouncer project's own Firebase project, so a server of your own can push to them only with that project's key (Push notifications).
Clients
- The Windows CLI isn't code-signed. It's new in 0.5.1; check the zip against
SHA256SUMS. exec --fileandself-updateare Linux only.exec --stdinworks on Linux and Windows.- There's no public package repository for the Linux
.deband.rpmyet, and release builds can't self-update yet.
Verification scope
The verification notes beside each procedure say what was checked. The operator tests use fake data in isolated environments and a software stand-in for devices.
- The preparation checklist is checked against the source only. A test with fake data followed the download installation, but nobody has yet followed the current checklist from start to finish on a fresh deployment (Overview and prerequisites).
- Sizing needs measurement. The preparation checklist gives planning estimates, not a workload capacity guarantee. Measure database, OpenBao, audit and backup growth in your evaluation (Overview and prerequisites).
- HTTPS needs a check for your deployment. The manual describes network and certificate requirements. It does not supply a complete, tested setup for every reverse proxy or private CA. Check certificate name and trust, client reachability and forwarded addresses before pairing (TLS and networking).
- App and hardware checks are separate. The operator tests use a software stand-in for an approving device. Lifecycle tests exercise operator steps and the server API; they do not verify the app's screens or physical keys (Credential expiry, replacement and history).
- Moving from another secret store needs a plan for each system that uses a secret. These pages don't give a general procedure for importing secrets from another store, switching each system over, or switching back. List every system that uses or issues each secret, test each one with a fake credential, and have a way to switch back that doesn't depend on Bouncer before you plan the move. Storing a credential type in Bouncer doesn't make Bouncer able to issue it, and isn't a tested connector.
- Audit retention is operator-managed. The kit does not automatically ship logs off the server or set your log-store retention. Check delivery and recovery separately. The audit chapter's historical event table is not a complete catalogue of later lifecycle or assurance events (Audit).
- Rollback coverage is bounded. A test with fake data followed the download route from 0.5.5 to the unpublished 0.5.6 build and back. That test used the kit's
upgrade.shfor the upgrade. The tests did not run a full source-build rollback,ship.sh, or a server version without credential versions against data that had already been reconciled (Upgrade and roll back). - A database restore is only part of recovery. The tests don't cover recovering OpenBao's own storage (Raft), keeping backups off the machine, recovering from a separate workstation, fully reconciling what the restored database allows, or measuring recovery time and data loss. Bouncer doesn't reconcile a restore for you. Keep outside access closed until the restore checks that apply to you are complete.
The API and CLI reference pages are checked against the API definition and the tools' current --help output. Automatic checks confirm that the manual's example files are valid, but not that they suit your server's policy, OpenBao permissions or network. The environment variables page covers the main tools; variables for individual kit scripts are listed with those procedures.
Reference
Complete lists, for looking things up. The task pages in Integrate and Operate explain how to use them.
- HTTP API: every endpoint of contract
bouncer.v1, generated from the contract files. - Config file: every setting in
bouncer.yaml, with defaults and allowed values. - CLI: the
--helpoutput ofbouncer,bouncer-admin,bouncer-mcpandbouncer-server. - Environment variables.
- Ports and files.
- Exit codes and errors.
Everything here describes Bouncer 0.5.7. The page footer identifies the source commit.
HTTP API
This page lists every endpoint of the Bouncer API, contract bouncer.v1, as the
server implements it in Bouncer 0.5.7. The page footer identifies the source commit.
It is generated from the contract
files in the repository: contracts/openapi.yaml (the endpoints) and
contracts/schemas/bouncer.v1.json (every object named below). Those files have
the full field-by-field detail, and contracts/examples/ has an example of each object.
Most integrations don't need the API directly: the CLI and the MCP server speak it for you.
Conventions
- Base path
/v1. The server itself speaks plain HTTP, on 127.0.0.1:8080 by default (--listen); clients reach it over HTTPS through the reverse proxy in front of it. Bodies are JSON in UTF-8. - Credentials go in
Authorization: Bearer: a requester key (brk_...) or a device token (bdt_...). Health and pairing need none. Never put a key in a URL. - Admin endpoints (
/admin/v1) are served only on the server's local Unix socket, never over the network.bouncer-admincalls them. - Only a signed statement from a paired device approves. No credential on its own can.
- IDs have several formats. Generated request IDs have a prefix and 26 lower-case
characters, such as
req_01jbx3k9m2p4q6r8s0t1v3w5y7; resource IDs and personal credential IDs use other formats. Treat them as opaque. - Times are UTC, RFC 3339, whole seconds:
2026-11-15T14:02:00Z. - Durations are objects:
{"kind": "finite", "seconds": 900}, or{"kind": "always"}. - Unknown fields in a request body are refused. Clients should ignore unknown fields in responses, and treat unknown values as "something else".
- Idempotency. Creating a request and fetching a token take an
idempotency_key. Repeating a request with the same key and body returns the first request; a different body is409 idempotency_conflict. Repeating a token fetch with the same key issues a new token and revokes the earlier one, so a retry never leaves two live tokens. - Long polling.
GET /v1/requests/{request_id}?wait=NandGET /v1/events?wait=Nwait up toNseconds (at most 60) for a change. - Secrets in transit. Four responses on the network side carry a secret, and are sent
with
Cache-Control: no-store:POST /v1/grants/{grant_id}/credentials(a short OpenBao token),POST /v1/resources/{resource_id}/view(the secret's values),POST /v1/credentials/{resource_id}/versions/{version}/view(an old version's values) andPOST /v1/pair(the new device token). Three admin responses carry one too:POST /admin/v1/requestersandPOST /admin/v1/requesters/{requester_id}/key(the requester's new key), andPOST /admin/v1/pairing-codes(a one-time pairing code). These don't setno-store, but they only ever travel over the server's local Unix socket, never through a proxy or cache. Only four endpoints accept secret values:POST /v1/resources/{resource_id}/store,POST /v1/grants/{grant_id}/write,POST /v1/credentials/{resource_id}/lifecycle(a replacement) andPOST /v1/personal-credentials. The server never logs any of these secrets. It keeps no copy of OpenBao tokens or secret values, and keeps requester keys, device tokens and pairing codes only as hashes.
Session
GET /v1/health
Is the server up, and which Bouncer is it.
Caller: none. Returns: Health.
Needs no credential. The app reads the instance ID here before pairing, because the pairing statement is addressed to it. The instance's flags say what this server supports: credential_types: true (0.5.0) means it accepts credential_type in personal create and rename bodies; older servers leave it out. device_reports: true means it takes device reports at POST /v1/devices/self/reports; an app doesn't report to a server without it. GET /v1/session carries the same instance. It is also the readiness check: while OpenBao is sealed, can't be reached or refuses the server's own login, it answers 503 with backend_sealed, backend_unreachable or backend_auth_failed and a Retry-After, and so does every other public call except the three that only take access away: a grant's revoke, a device's own revoke and a request's cancel. Those still work, and a revoke reports the tokens OpenBao couldn't revoke yet as revoke_failed; the server revokes them once OpenBao is back. The server stays up and issues nothing until OpenBao is ready again. The problem holds no address and no token. From 0.5.7, the database is also checked with a short SELECT 1 probe on a separate connection, cached for up to five seconds. If PostgreSQL is unavailable, every public call, including revoke and cancel, answers 503 database_unavailable with Retry-After: those calls need the database to commit their changes. The process stays up and recovers without a restart. In 0.5.6, a call that needs PostgreSQL and cannot reach it fails with 500 internal.
GET /v1/session
Who the caller is, and the server's time.
Caller: requester key, device token. Returns: Session.
The apps use server_time to show countdowns against the server's clock, not their own.
Requests
GET /v1/resources
The resources the caller may request, with each one's duration menu.
Caller: requester key, device token. Returns: ResourceList.
A device lists the resources its person may request through their own human requester. Searching and filtering only narrow that list: they read metadata (ID, name, description, folder), never a value, and a folder never makes a resource visible or requestable.
GET /v1/requests
List requests.
Caller: requester key, device token. Returns: RequestPage.
role=approver (devices only) lists requests the caller's person can decide: the inbox. role=requester lists the caller's own requests. Newest first.
POST /v1/requests
Ask for access.
Caller: requester key, device token. Body: CreateRequest. Returns: Request.
Files a request as the caller's requester. A device files it as its person's own human requester. The server checks the policy, works out the duration menu and the deadline, notifies the approvers, and returns the request as pending.
GET /v1/requests/{request_id}
One request.
Caller: requester key, device token. Returns: Request.
Visible to its requester and to its approvers' devices. With wait=N, the call is held for up to N seconds (at most 60) while the request is pending, and returns as soon as it changes. bouncer wait uses this.
POST /v1/requests/{request_id}/cancel
Withdraw a pending request.
Caller: requester key, device token. Returns: Request.
Only its requester can cancel it. The approvers' notifications are withdrawn.
Decisions
POST /v1/challenges
Get a single-use challenge to sign.
Caller: device token. Body: ChallengeRequest. Returns: Challenge.
Devices with an approval key only. A challenge is bound to this device and, for a decision, to the request and its revision. It lasts 2 minutes by default and is used up by the first statement that carries it, whatever the outcome.
POST /v1/requests/{request_id}/decision
Approve or deny, with a signed decision statement.
Caller: device token. Body: DecisionRequest. Returns: DecisionResult.
The server checks everything in contracts/README.md section 4 inside one transaction, then commits the decision and, on approval, the grant. Any failed check is logged as a rejected attempt, never as a vote, and the challenge is used up either way.
Grants
GET /v1/ssh/krl
The SSH revocation list (KRL) for destination hosts.
Caller: requester key. Returns: binary data.
An OpenSSH KRL, for sshd's RevokedKeys, signed by nothing and naming the SSH CA. It revokes, by key ID, every certificate of each ssh_host grant that was cut off while a certificate of it may still be live, and by serial each certificate a retry replaced. Entries drop out 5 minutes after the certificates they name have ended. The version goes up by one whenever the list changes. Only an active requester of kind host may fetch it; destinations do so on a timer (deploy/ssh-krl/) and install it with an atomic rename.
GET /v1/grants
List grants.
Caller: requester key, device token. Returns: GrantPage.
A requester sees its own grants. A device sees grants on the resources its person approves, plus its person's own. Newest first.
GET /v1/grants/{grant_id}
One grant.
Caller: requester key, device token. Returns: Grant.
POST /v1/grants/{grant_id}/credentials
Get a short OpenBao token for an active grant.
Caller: requester key. Body: CredentialRequest. Returns: Credential.
The grant's requester only. The server re-checks the grant, asks OpenBao for a token through the resource's token role, reads back its real lifetime, records the accessor, and returns it. The token lasts at most the resource's credential_ttl (5 minutes by default) and never past the grant's end.
POST /v1/grants/{grant_id}/write
Save the values for an approved store request.
Caller: requester key. Body: WriteSecretRequest. Returns: WriteResult.
The grant's requester only, for a grant whose actions are ["write"] (an approved store request). The body has one value for each field the request named, and no others. The server writes them into the resource's one secret, then ends the grant: each store approval is used once, whatever the outcome.
POST /v1/grants/{grant_id}/revoke
End a grant now.
Caller: requester key, device token. Returns: RevokeResult.
Allowed for the grant's requester, and for any active device of a person who approves the resource or owns the requester. Not signed: revoking only takes access away.
Devices
GET /v1/devices
The caller's person's devices.
Caller: device token. Returns: DeviceList.
PUT /v1/devices/self/push-route
Register where to send this device's pushes.
Caller: device token. Body: PushRoute. Returns: nothing (204).
Routing data only; it proves nothing. Sent on every app start. Only fcm is accepted in this version; any other kind is refused with 422 invalid_body.
POST /v1/devices/self/revoke
Revoke the authenticated device.
Caller: device token. Body: an empty object, {}. Returns: Device.
Needs only this device's bearer token, without a signed statement. Accepts no query parameters or target fields. Send no body or {}. The device, its unused challenges and the standing grants it approved are cut off together. Its time-limited grants stay active until they end. Other devices and grants they approved are unaffected.
POST /v1/devices/self/reports
Record what only the device saw, in the approval log.
Caller: device token. Body: DeviceReportRequest. Returns: DeviceReportResult.
A paired device reports, with its own token, a screenshot or screen recording while Bouncer showed a protected screen, a copy of a value it had just viewed, or a failure to keep its window out of capture. Each report becomes one approval log entry of a reported_* kind, with the report in the entry's report. These are the device's word: the server can't verify them, and a missing report proves nothing.
POST /v1/devices/self/approval-key
Enrol a Windows Hello passkey as this Windows device's approval key.
Caller: device token. Body: ApprovalKeyRequest. Returns: Device.
A Windows device, paired without a key, proves it holds a new passkey by signing an approval_key statement as a WebAuthn assertion with user verification. Needs pairing.allow_webauthn_keys. The key is labelled platform-sw-uv: it can always deny, and approves any resource that doesn't set require_hardware_uv (or, from 0.5.7, require_hardware_key). From 0.5.7, the body may also carry the passkey's registration: with a tpm attestation that verifies to a pinned root, the key is recorded as attested and can meet require_hardware_key too; otherwise it enrols unattested while verified evidence is optional. In the current source (not yet released), pairing.require_verified_approval_keys (default false) instead requires verified evidence at installation and whenever a key signs. Keyless Windows bootstrap remains available. Device.key_proof adds status, evidence_kind and nullable checked_at; neither a declared platform nor assurance alone establishes proof. A configured requirement fails with 422 assurance_not_accepted and re-enrollment/operator-review guidance. A registration that isn't exactly its two strings is invalid_body; 0.5.6 and earlier refuse the field. A device that already has a key is refused with 403; to change it, sign out and pair again.
PUT /v1/devices/self/settings
Turn approval from notifications on or off, with a signed statement.
Caller: device token. Body: DeviceSettingsRequest. Returns: Device.
POST /v1/resources/{resource_id}/view
View a stored secret's value on this device, with a signed statement.
Caller: device token. Body: SecretViewRequest. Returns: SecretViewResult.
Only for a resource whose view setting isn't off: under grant_holder, for a person whose own human requester holds an active read grant for it (never an agent's); under approver (the older allow_device_view), for its approvers. Only from a device whose approval key is not software-held on a phone (platform-sw-unlocked), presence-only or a synced passkey; Windows Hello (platform-sw-uv) is accepted. The statement carries a secret_view challenge, so it's used once. The answer is sent with Cache-Control no-store, and the value is never stored, logged or pushed. Each view is logged as secret_viewed, and each refusal as secret_view_refused.
POST /v1/resources/{resource_id}/store
Save values into a stored secret from this device, with a signed statement.
Caller: device token. Body: SecretStoreRequest. Returns: SecretStoreResult.
A one-shot, self-approved store request: the person is both requester and approver. Only for a resource with allow_write and self_approval, only for its approvers, and only from a device whose approval key is not software-held on a phone (platform-sw-unlocked), presence-only or a synced passkey; Windows Hello (platform-sw-uv) is accepted, with the user verification the key enrolled with. The statement names the fields (never the values) and carries a secret_view challenge, so it's used once. The values are merged into the secret (other fields kept), never stored, logged or echoed. Each save is logged as secret_written, and each refusal as secret_write_failed with the reason.
GET /v1/credentials/{resource_id}/history
A credential's versions, states, dates and actors, without values.
Caller: device token. Returns: CredentialHistory.
For a config resource or personal credential with lifecycle on. Paired devices only (never requester keys), for a person who may see the credential: a personal credential's owner and the people it's shared with; a config resource's approvers. Built from OpenBao's version metadata (never values) and Bouncer's own records, newest first. A version OpenBao removed for good under max_versions keeps its line, as pruned. can_change and can_view_old say what this person may do.
POST /v1/credentials/{resource_id}/lifecycle
Expire, schedule or clear an expiry, or replace a credential's current version.
Caller: device token. Body: CredentialLifecycleRequest. Returns: CredentialLifecycleResult.
A signed credential_lifecycle statement over a single-use secret_view challenge, from a device whose approval key isn't kept in software on a phone, with the user verification it enrolled with. From 0.5.7, it needs a key that checks the person on each use (fingerprint, face or Windows Hello); an Android key that only needs the phone unlocked is refused, and the credential's require_hardware_uv and require_hardware_key settings apply. version must still be the current version, or it's version_conflict and nothing changes. Expiring deletes nothing: the value stays in OpenBao's version history, and every live token and unused wrapped hand-out Bouncer issued for it is revoked. A replacement is a KV version 2 patch with cas, a new version at the same path. While retention is held, one that would make OpenBao remove an old value for good is refused (prune_not_confirmed), and so is any statement with a prune_version. Personal credentials: Editors and up. Config resources: approvers; a replacement also needs allow_write and self-approval. Expiring or replacing a token issued by another system doesn't revoke it there. Every change is logged; every refusal is logged as credential_lifecycle_refused.
POST /v1/credentials/{resource_id}/versions/{version}/view
See an old version's value once, as its own authorised and logged operation.
Caller: device token. Body: CredentialLifecycleRequest. Returns: CredentialVersionView.
Never part of the history listing, and never for requester keys, agents, the CLI or MCP. A signed credential_lifecycle statement with op view_version naming the version. From 0.5.7, it needs a key that checks the person on each use (fingerprint, face or Windows Hello), and the credential's require_hardware_uv and require_hardware_key settings apply. 0.5.6 accepts any approval key that is not software-held on a phone, presence-only or synced, including an Android key that only needs the phone unlocked. Only a personal credential's owner, and a config resource's approvers where its view setting is on. Not the current version (use the resource's view). Logged as credential_version_viewed.
POST /v1/pair/preview
Check a pairing code before using it.
Caller: none. Body: PairPreviewRequest. Returns: PairPreview.
No bearer credential: the pairing code is the credential. Returns who the code pairs as and which Bouncer, so the app can show "As {person}" on the "Name this phone" screen. It doesn't use the code up. Wrong codes count towards the same rate limit as POST /v1/pair.
POST /v1/pair
Pair a device with a one-time code from bouncer-admin.
Caller: none. Body: PairRequest. Returns: PairResult.
No bearer credential: the pairing code is the credential. It works once. A device with an approval key (Android) sends a signed pairing statement as proof; a device without one (a Windows PC) sends null. Pairing adds a device_paired event for the person's other devices.
Personal credentials
GET /v1/personal-credentials
The personal credentials this person owns, or that are shared with them.
Caller: device token. Returns: PersonalCredentialList.
Metadata only, never a value. mine is what the caller owns; shared is what's shared with them now, through a person or group assignment, resolved by the config loaded now. A credential the caller has no access to isn't listed. Managers and the owner also see its assignments. From 0.5.7, responses add shared_by (the recorded human who last changed the selected assignment) and access_sources (only assignments matching this viewer now). Each actor is omitted unless they are the owner or the caller is an owner/Manager. Unchanged assignments retain their original actor and timestamp. 0.5.6 and earlier omit these fields; ownership is not a fallback actor. These metadata fields do not change permissions or approval mode. A disabled credential stays listed, with status disabled, for its owner (in mine) and its Managers (in shared), so the owner can re-enable or delete it; nobody else sees it, and nobody can use it.
POST /v1/personal-credentials
Create a personal credential from this device, with a signed statement.
Caller: device token. Body: PersonalCreateRequest. Returns: PersonalCredential.
The statement (op create) names the namespace, name, folder, field names, access mode and assignments, never the values, and carries a secret_view challenge, so it's used once. Only from a device whose approval key is not software-held on a phone (platform-sw-unlocked), presence-only or a synced passkey; Windows Hello (platform-sw-uv) is accepted, with fresh user verification, and only for a person the namespace lets create there, within its ceilings (field names and count, how many each owner may keep, whether reveal and Always approved are allowed). The values go once to OpenBao at <prefix>/<owner>/<id> and are never stored, logged or echoed. Private unless the statement shares it. Logged as sharing_changed, and each refusal as sharing_refused with the reason.
PUT /v1/personal-credentials/{credential_id}/sharing
Replace a personal credential's assignments and access mode, with a signed statement.
Caller: device token. Body: PersonalChangeRequest. Returns: PersonalCredential.
Op share. The owner may set anything within the namespace's ceilings, and signing the mode again ends a suspension of Always approved and starts its review over. A Manager may share with Viewers and Editors up to what they have themselves, and can't change the mode or Managers. Grants the new sharing no longer allows end at once, and their tokens are revoked.
POST /v1/personal-credentials/{credential_id}/disable
Disable a personal credential, with a signed statement (owner only).
Caller: device token. Body: PersonalChangeRequest. Returns: an object with id, status.
Op disable. Nobody can use it any more; its grants end and their tokens are revoked. A value already revealed can't be recalled.
POST /v1/personal-credentials/{credential_id}/enable
Re-enable a disabled personal credential, with a signed statement (owner only).
Caller: device token. Body: PersonalChangeRequest. Returns: PersonalCredential.
Op enable. Only for a disabled credential (an active one is forbidden). Its sharing and mode are as they were, so the summary the app shows before the signature must name them. The grants that disabling ended stay ended; new requests follow the mode.
POST /v1/personal-credentials/{credential_id}/rename
Rename or move a personal credential, with a signed statement (owner only).
Caller: device token. Body: PersonalChangeRequest. Returns: PersonalCredential.
Op rename, for an active credential. The statement names the new display name, kept exactly as typed, and folder (null is no folder). The ID, the OpenBao path, the sharing, mode, grants and history don't change, and no grant is suspended: a name and folder aren't policy. Refused with invalid_body when the owner already has a live credential of that name, ignoring case, in that folder. Anyone but the owner gets not_found.
DELETE /v1/personal-credentials/{credential_id}
Delete a personal credential, with a signed statement (owner only).
Caller: device token. Body: PersonalChangeRequest. Returns: an object with id, status.
Op delete, sent as the body of the DELETE, for an active or a disabled credential. As disable, and the credential is gone from every list. The value stays in OpenBao until the operator deletes it: Bouncer's policy has no delete there.
Events
GET /v1/events
Follow events for this device.
Caller: device token. Returns: EventPage.
Returns the events after the cursor, oldest first. Without after, it starts at the device's pairing. The server keeps events for at least 7 days; a cursor older than that returns every event still kept. With wait=N, the call is held for up to N seconds (at most 60) until there's at least one. The Windows app and the Android app in the foreground use this; pushes only carry an event's ID.
GET /v1/events/{event_id}
The event a push pointed to.
Caller: device token. Returns: Event.
Log
GET /v1/log
The approval log.
Caller: device token. Returns: LogPage.
Entries about the resources the caller's person approves, newest first. Entries of the reported_* kinds were reported by a device, not verified by the server (see POST /v1/devices/self/reports). A kind this server doesn't know is refused with invalid_body. Entries of kinds the client doesn't know are shown generically.
Admin
POST /admin/v1/pairing-codes
bouncer-admin device pair.
Caller: admin socket. Body: AdminPairingCodeRequest. Returns: AdminPairingCode.
GET /admin/v1/devices
bouncer-admin device list.
Caller: admin socket. Returns: DeviceList.
POST /admin/v1/devices/{device_id}/revoke
bouncer-admin device revoke.
Caller: admin socket. Returns: Device.
The device can no longer sign in, decide or see anything. Its pending challenges are void. The standing (Always) grants it approved are revoked with their tokens; the time-limited grants it approved stay active until they end. When this call revoked the device, the answer's revocation says what it ended and what it left, including any downstream credentials now due rotation. A device that was already revoked is answered as it stands, without revocation.
GET /admin/v1/requesters
bouncer-admin requester list.
Caller: admin socket. Returns: RequesterList.
POST /admin/v1/requesters
bouncer-admin requester add.
Caller: admin socket. Body: AdminRequesterCreate. Returns: RequesterWithKey.
Creates a requester and its first key. The key is shown once.
POST /admin/v1/requesters/{requester_id}/key
bouncer-admin requester rotate-key.
Caller: admin socket. Returns: RequesterWithKey.
Issues a new key and makes the old one stop working at once. The new key is shown once. A new key is a re-enrolment: the requester's standing grants are suspended (grant_suspended in the log) and need a fresh approval. Its time-limited grants stay until they end.
POST /admin/v1/requesters/{requester_id}/disable
bouncer-admin requester disable.
Caller: admin socket. Returns: Requester.
The key stops working, pending requests are cancelled, and active grants are revoked.
POST /admin/v1/revoke-all
bouncer-admin revoke --all (the kill switch).
Caller: admin socket. Returns: KillSwitchReport.
Ends every grant, cancels every pending request and revokes every issued token. The cutoff commits before anything else.
POST /admin/v1/config/reload
bouncer-admin config reload.
Caller: admin socket. Returns: ConfigReport.
Loads the config file again. An invalid file is refused and the old one stays loaded. Standing grants on a resource whose policy changed (a new resource_revision), or that left the file, are suspended. A change that loosens policy (a longer maximum, Always or self-approval newly allowed, more requesters, approvers or secrets, a weaker key requirement, or looser pairing) writes a policy_loosened log entry saying what loosened, and a policy_loosened event for the approvers' devices.
GET /admin/v1/log/export
bouncer-admin log export.
Caller: admin socket. Returns: LogExport.
The whole approval log, oldest first, in pages, for the operator to keep or ship to syslog or a SIEM. Ordinary entries keep the LogEntry shape. From 0.5.7, admin-only token_issued and backend_revoke entries add token_audit: issuance ID, issuance-time role (null for wrapped KV reads or older issuances), full non-secret accessor, and backend revoke outcome (null on issuance). The entry names the grant and time. The full accessor can be passed to sys/audit-hash on the relevant OpenBao audit device for an exact HMAC match. It cannot read credentials, but can look up or revoke a token. These records are excluded from device logs. Existing records are not backfilled; local expiry without a backend call creates no backend revoke record. Decision statements, signatures and secret values aren't included. Ask again with after set to the last page's cursor for the next page, or later for what's new. The cursor never passes an entry that's still being written. since and until pick a time window; until is excluded.
GET /admin/v1/ssh/krl
The SSH revocation list, for destinations.
Caller: admin socket. Returns: binary data.
The same KRL as GET /v1/ssh/krl, for a script on the server's own machine (deploy/ssh-krl/). 404 when the server has no SSH signer.
GET /admin/v1/downstream
bouncer-admin downstream list.
Caller: admin socket. Returns: DownstreamList.
Every resource whose value is a credential issued by another system, and whether it needs rotating there. Bouncer never calls that system.
POST /admin/v1/downstream/{resource_id}/rotated
bouncer-admin downstream rotated.
Caller: admin socket. Returns: Downstream.
Records that the admin rotated the resource's downstream credential at its system and updated the KV secret. Clears rotation_due and exposed_since; a value released after this counts again. Bouncer doesn't check the rotation. Writes a downstream_rotated log entry.
POST /admin/v1/grants/{grant_id}/review
bouncer-admin grant review.
Caller: admin socket. Returns: Grant.
Re-confirms an active standing grant's review, so it isn't suspended when review_due_at comes. The next review is due a full cadence (durations.always_review, 90 days by default) from now. Writes a review_confirmed log entry. A week before a review is due (or half the cadence, if that's shorter) the server writes review_due and tells the approvers' devices. A suspended grant can't be re-confirmed: the requester files a new request.
POST /admin/v1/personal-credentials/{id}/suspend
bouncer-admin personal suspend.
Caller: admin socket. Returns: an object with credentials, grants_ended.
Suspends Always approved on one personal credential: its grants that came from Always approved end and their tokens are revoked, and requests wait for approval until the owner signs the mode again. Logged as sharing_changed by the admin. A credential that isn't on Always approved, or is already suspended, is left as it is.
POST /admin/v1/personal-namespaces/{namespace}/suspend
bouncer-admin personal suspend --namespace.
Caller: admin socket. Returns: an object with credentials, grants_ended.
The same, for every active personal credential in the namespace.
POST /admin/v1/personal-credentials/{id}/freeze
bouncer-admin personal freeze.
Caller: admin socket. Returns: an object with credentials, grants_ended.
Freezes one personal credential: nobody can use it until it's reassigned, and all its grants end and their tokens are revoked. Use it before rolling back the server (migration 0012).
POST /admin/v1/personal-namespaces/{namespace}/freeze
bouncer-admin personal freeze --namespace.
Caller: admin socket. Returns: an object with credentials, grants_ended.
The same, for every active personal credential in the namespace.
POST /admin/v1/personal-credentials/{id}/reassign
bouncer-admin personal reassign.
Caller: admin socket. Body: an object with owner. Returns: an object with credentials, grants_ended.
Gives a frozen personal credential, or one whose owner left the config file, to another person ({"owner": "<person ID>"}), within the namespace's per-owner limit, so nothing is orphaned. It's active again with its assignments as they were, but Always approved stays suspended until the new owner signs the mode: an operator never chooses it for them. 400 (invalid_body) if the owner isn't a person, the namespace is gone, or the credential isn't frozen.
Errors
Errors are application/problem+json (RFC 9457) with a machine-readable code.
A client that gets a code it doesn't know treats it by its HTTP status.
| Code | HTTP | Meaning |
|---|---|---|
unauthenticated | 401 | No credential, or not a valid one |
forbidden | 403 | Valid credential, but not allowed to do this |
not_found | 404 | No such object, or not visible to this caller |
invalid_body | 400 | The body doesn't match the schema |
idempotency_conflict | 409 | Same idempotency key, different body |
rate_limited | 429 | Too many requests; see Retry-After |
requester_disabled | 403 | This requester is disabled |
device_revoked | 403 | This device is revoked |
not_requestable | 403 | This requester may not ask for this resource |
duration_not_permitted | 422 | The duration isn't allowed for this resource. Never clamped |
reason_invalid | 422 | The reason is empty, too long, or has control characters |
not_an_approver | 403 | This person doesn't approve this resource |
self_approval_not_allowed | 403 | This resource needs a different approver |
channel_not_permitted | 422 | Notification approval isn't allowed here, isn't opted in on this device, or the duration differs from the requested one |
confirmation_missing | 422 | Longer than requested without longer_than_requested, or the confirmation was given when it wasn't longer; or the matching code is missing or different |
request_not_pending | 409 | The request was already decided, expired or cancelled |
revision_mismatch | 409 | The request changed since the device fetched it |
scope_mismatch | 422 | The statement's scope hash doesn't match the request |
audience_mismatch | 422 | The statement is for another Bouncer |
challenge_invalid | 422 | The challenge is unknown, used, expired, or for another device or request |
statement_not_canonical | 422 | The statement bytes aren't canonical JSON |
statement_invalid | 422 | The statement isn't base64url, isn't the right kind, or has fields the contract doesn't define |
signature_invalid | 422 | The signature doesn't verify against this device's key |
unsupported_signature_format | 422 | A signature format the server doesn't accept yet |
key_mismatch | 422 | The statement's device, key ID or epoch isn't this device's current one, or its approver or assurance isn't this device's |
assurance_not_accepted | 422 | The key's assurance or user verification doesn't meet the resource's policy |
grant_not_active | 409 | The grant has expired, been revoked or been suspended |
issuance_failed | 502 | Bouncer couldn't release a credential. The detail says whether a token may have been issued |
write_failed | 502 | OpenBao didn't save a store request's values. The grant is used up anyway; file a new request |
view_off | 403 | The resource doesn't allow viewing its value on a device |
no_grant | 403 | A device view needs an active read grant held by one of this person's own human requesters; an agent's grant never counts |
grant_expired | 403 | The person's grant for this resource has ended or been suspended |
grant_revoked | 403 | The person's grant for this resource was revoked |
store_only_grant | 403 | The person's only grant is a store request's, which saves values and never reads them |
wrong_person | 403 | The active grant for this resource is another person's |
not_found_in_backend | 404 | OpenBao has no value at the resource's path yet |
credential_expired | 409 | The credential's current version has expired; nothing is issued, handed out or shown until a replacement is saved, and never an older version instead |
version_conflict | 409 | The lifecycle operation named a version that is no longer current; nothing was changed |
prune_not_confirmed | 409 | A write would make OpenBao remove an old version's value for good, which Bouncer never does while retention is held; an operator has to raise max_versions first |
lifecycle_off | 403 | The credential has no version history (lifecycle is off) |
pairing_code_invalid | 422 | The pairing code is unknown, used or expired |
proof_required | 422 | This platform pairs with an approval key, so a pairing proof is required |
config_invalid | 422 | The config file was refused; the old one stays loaded |
backend_sealed | 503 | The server is running, but OpenBao, which it issues credentials from, is sealed. An operator must unseal it. An outage, not a refusal. Comes with Retry-After, on every call including GET /v1/health |
backend_unreachable | 503 | The server is running, but can't reach OpenBao. An outage, not a refusal. Comes with Retry-After |
backend_auth_failed | 503 | The server is running, but OpenBao refused the server's own login. An operator must fix it. An outage, not a refusal of the caller's credential. Comes with Retry-After |
database_unavailable | 503 | The server is running, but PostgreSQL is unavailable. Comes with Retry-After; no credentials are issued and the server stays up and checks for recovery. From 0.5.7; 0.5.6 does not send this code. |
resource_not_provisioned | 503 | This resource's kit token role or policy is missing or unsuitable. Comes with Retry-After; requests and issuance for it are blocked while other resources and health continue to serve. A metadata 403 with a live login instead means upgrade_needed, not a proven missing role or policy. From 0.5.7; 0.5.6 does not send this code. |
internal | 500 | Something went wrong on the server |
Config file reference
Every setting in bouncer.yaml, as the config loader reads it in the source this site was built from. Settings that 0.5.6 and earlier refuse are marked "from 0.5.7". Configure the server explains how to use them. The repository's contracts/config/bouncer.example.yaml is a commented example with every section, and contracts/schemas/config.v1.json is the JSON Schema.
General rules:
- Unknown keys are refused, and so are repeated keys. A typo is an error, not ignored.
- Durations are a whole number and a unit:
s,m,hord(90s,15m,6h,7d). - Booleans are only
trueorfalse. - The file holds no secrets: only the paths of files that do.
Top level
| Key | Required | Meaning |
|---|---|---|
version | yes | Must be 1 |
instance | yes | See below |
people | yes | At least one person |
defaults | no | Policy defaults for every resource |
openbao | yes | How Bouncer reaches OpenBao |
pairing | no | Which approval keys may pair |
push | no | Firebase push, or null for none |
resources | yes | At least one resource |
groups | no | Named groups of people, for personal credential sharing |
personal_credentials | no | Storage areas for people's own credentials |
instance
| Key | Meaning |
|---|---|
id | Lower-case letters, digits and hyphens. Goes into every signed statement. Never change it once devices are paired |
name | Display name |
url | https://host[:port], the address apps and requesters use. Carried in pairing codes |
people
A list of:
| Key | Meaning |
|---|---|
id | Lower-case ID, used in approvers, --person and --owner. Each person gets a human requester of the same name |
name | Display name |
defaults
Each of these can also be set on a single resource, which then overrides the default.
| Key | Default | Allowed | Meaning |
|---|---|---|---|
request_wait | 15m | 1m to 24h | How long a request waits for a decision |
credential_ttl | 5m | 30s to 1h | How long each OpenBao token lasts (never past the grant's end) |
durations.presets | [5m, 15m, 1h, 6h, 24h, 7d, always] | 1 to 12 entries, each 1m to 365d or always, no repeats | The quick choices on the approval screen |
durations.min | 1m | 1m to 365d | The shortest custom duration |
durations.max | 365d | 1m to 365d, at least min | The longest custom duration |
durations.always | true | Whether standing grants may be approved. The Bouncer project hasn't decided the policy for standing grants yet. Set this to false | |
durations.always_review | 90d | 1d to 365d | How often a standing grant must be re-confirmed |
self_approval | true | Whether people may approve their own requests and their own agents' | |
notification_approval | true | Whether approving from a notification is allowed (each device must also opt in) | |
require_hardware_uv | false | Whether only biometric hardware keys (platform-hw-uv) may approve | |
require_hardware_key | false | Introduced in 0.5.7; earlier servers refuse the key. In the current source (not yet released), requires verified Android-key or Windows TPM evidence for the current key plus per-use verification. A declared hardware-UV label alone fails. Independent of require_hardware_uv, whose UV-only claim rule is unchanged; both apply when both are set |
openbao
| Key | Meaning |
|---|---|
address | http(s)://host[:port], as both the server and requesters reach OpenBao |
ca_file | A PEM CA bundle for OpenBao's certificate, or null |
kit_prefix | The role kit's prefix (KIT_PREFIX, bouncer by default). Lower-case letters and digits in dash-separated parts, starting with a letter, up to 20 characters. Each resource uses the token role <kit_prefix>-issue-<resource id> |
approle.mount | The role kit's AppRole mount. Must start with the kit prefix and a dash (bouncer-approle) |
approle.role_id_file | The file holding the role_id (/run/secrets/bouncer-role-id in the compose kit) |
approle.secret_id_file | The file holding the secret_id |
ssh.approle.mount, .role_id_file, .secret_id_file | The SSH signer's own login, needed once any resource is an ssh_host. Its mount must start with the kit prefix and differ from the token login's |
Any change to this section needs a server restart.
pairing
| Key | Default | Meaning |
|---|---|---|
allow_software_keys | false | Allow approval keys kept in software. For test setups only |
allow_user_verified_keys | false | Allow phone keys that need biometrics for every signature (platform-hw-uv). Needed for iPhones |
allow_webauthn_keys | false | Allow Windows Hello keys |
require_verified_approval_keys | false | In the current source (not yet released): opt in to verified Android-key or Windows TPM evidence at key installation and every signing gate. Existing unverified keys also fail after reload. Keyless Windows bootstrap remains available. Incompatible with android_attestation: off |
android_attestation | prefer | required, prefer or off (Device keys) |
android_package | com.s6studios.bouncer | The Android app an attestation must name |
android_signing_cert_sha256 | the official upload certificate's | The SHA-256 of each certificate the app may be signed with (64 hex digits each) |
allow_software_keys, allow_user_verified_keys, allow_webauthn_keys and android_attestation: required are checked again whenever a device signs, so turning one off also stops keys that paired while it was on. android_package and android_signing_cert_sha256 apply only when a phone pairs. Turning on allow_software_keys or allow_user_verified_keys, weakening android_attestation, or changing android_package or the signing certificates counts as a loosening and is announced. Turning on allow_webauthn_keys is not announced. Turning off require_verified_approval_keys is a loosening and is announced; check-config and reload report its value. Dropping require_hardware_key also loosens proof requirements while require_hardware_uv remains set. With the new opt-in omitted, an existing UV-only rule still accepts declared claims; upgrading does not activate a policy. See key proof.
push
null turns push off. Otherwise:
| Key | Meaning |
|---|---|
fcm.project_id | The Firebase project ID |
fcm.service_account_file | The service-account key file, such as /run/secrets/fcm-service-account.json |
fcm_also | Needs server build 0.3.8+25 or later. Only while moving to another project: up to 4 more project_id and service_account_file pairs, tried in order after fcm. Each project and key file may appear once |
The key files are read at start-up and on every reload; a missing or broken one refuses the start or the reload.
resources
A list. Each resource:
| Key | Required | Default | Meaning |
|---|---|---|---|
id | yes | Lower-case letters, digits and single dashes, up to 40 characters. Unique. Not starting with pc- | |
name | yes | Display name | |
kind | yes | stored_secret, stored_api_key or ssh_host | |
description | no | none | Shown to requesters and approvers |
folder | no | Unfiled | Folder names joined by / |
credential_type | no | none | One of api_key, password, access_token, certificate, certificate_with_private_key, ssh_private_key, secret_key, key_pair, recovery_codes, otp_seed, other. A label for the apps' icons only. Servers before 0.5.0 refuse it |
kv | yes, except for ssh_host | A list of mount and path (without data/). An ssh_host has none | |
fields | no | none | Field names shown to requesters. Names only |
approvers | yes | Person IDs | |
requesters | no | any active requester | Requester names, or ["*"] for any |
request_wait, credential_ttl, durations, self_approval, notification_approval, require_hardware_uv, require_hardware_key (from 0.5.7) | no | from defaults | As in defaults |
allow_write | no | false | Accept store requests. Needs exactly one kv entry and write in the role kit's line |
lifecycle | no | false | Keep version history and allow expiry, scheduling and replacement from a paired app. Stored secrets and API keys only. Needs exactly one kv entry and lifecycle in the role kit's line. From 0.5.3; see setup, permissions and retention limits |
view | no | off | off, grant_holder or approver: who may view the value in the apps. Needs exactly one kv entry and view in the role kit's line. Not for ssh_host |
allow_device_view | no | false | Older form of view: approver. Give one or the other, not both |
downstream.system | with downstream | The other system's name | |
downstream.kind | with downstream | static_token | |
downstream.expires_at | no | none | When the credential expires at its system, as an RFC 3339 time |
ssh.principal | for ssh_host | The one account on the host: lower-case letters, digits, _, - and ., up to 32 characters, and not root | |
ssh.bind_source_address | no | true | Bind each certificate to the address the requester called from |
Adding a resource needs a restart. Removing one only needs a reload; its standing grants are suspended.
Check a candidate resource configuration
From 0.5.7, use bouncer-server --check-config with
--config before installing a new resource. It checks the candidate file
and OpenBao provisioning without applying it. Run it as the service user;
require exit 0 after the kit upgrade. See
Checking a file before you deploy it
for the login/session-token limits and all exit codes, and
Add a resource for the
kit, preflight, config and restart order. A new entry inherits defaults,
including its duration ceiling, unless it overrides them.
groups
A list of id and members (person IDs). Used only by personal credential sharing.
personal_credentials
A list of storage areas ("namespaces") where people create their own credentials from the apps. Each:
| Key | Default | Meaning |
|---|---|---|
id | The namespace's ID | |
label | from the ID, such as "Personal storage" | The name the apps show. Must differ from every other namespace's, ignoring case |
kv.mount, kv.prefix | Where the values go in OpenBao. The prefix leaves out data/, and mustn't overlap a resource's secret or another namespace. The role kit needs a matching personal line | |
creators | everyone | People or groups who may create here |
fields.names | any | The only field names allowed |
fields.max | 8 | Fields per credential, 1 to 32 |
per_owner | 50 | Credentials per person, 1 to 1000 |
lifecycle | false | Enable lifecycle for every credential in this namespace. The role kit's personal line for it needs lifecycle too (personal lifecycle). Turning it off later keeps recorded expiries, and saves that would prune an old version are still refused; see Credential expiry, replacement and history |
ceilings | required | The block must be present, even if empty (ceilings: {}) |
ceilings.credential_ttl, ceilings.durations | from defaults | The most a credential in this area may allow |
ceilings.reveal | false | Whether values may be viewed in the apps |
ceilings.always_approved | false | Whether an owner may set a credential to be approved automatically. Keep it false: this mode has two open problems (Approvals and access duration) |
CLI reference
This page is the --help output of the bouncer, bouncer-admin, bouncer-mcp and bouncer-server binaries built from the source this site was built from, exactly as they print it. This reference covers Bouncer 0.5.7. Exit code 16 and bouncer-server --check-config do not appear in the 0.5.6 binaries' help. Your server may run another version. On Windows, bouncer also has key save (Saving your key on Windows); self-update and exec --file are Linux only.
bouncer-admin runs only on the Bouncer server's machine. With the compose kit, run it as docker compose exec bouncer bouncer-admin ....
Numbers such as (D22) in the help text point to the project's internal decision log, which isn't published. You don't need it: the text around each number says what the command does.
Two notes on the help text. A command run with exec can still print, log or save the values it gets, and exec doesn't redact its output (Patterns for workloads and agents). For SSH, the 15-second timer is how often hosts try to fetch the revocation list, not confirmed delivery (SSH to a host).
bouncer
Ask for access to a secret, wait for approval on your phone, and use it
Usage: bouncer [OPTIONS] <COMMAND>
Commands:
resources List the resources you may ask for: their fields, durations, and your pending requests and grants
request Ask for access to a resource. Prints the request ID
status Show one request, or your recent ones
wait Wait for the decision on a request. Exits 0 only if it's approved
exec Run a command with a resource's secret in its environment
grants List your grants (active ones, unless you give --all)
revoke End one of your grants now, and revoke its tokens
cancel Withdraw one of your pending requests
put Save a new secret value, once it's approved
ssh Log in to an SSH host resource with a short-lived certificate
help Print this message or the help of the given subcommand(s)
Options:
--json
Print the server's answers as JSON, exactly as they came, for scripts
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version
Connection (optional, see Configuration in bouncer --help):
--server <URL>
The Bouncer server, such as https://bouncer.example.net. Default: the first line of ~/.config/bouncer/server
[env: BOUNCER_URL]
--key-file <PATH>
A file holding the requester key; it must be private (chmod 600). Default: BOUNCER_KEY, else ~/.config/bouncer/key
[env: BOUNCER_KEY_FILE]
Configuration:
BOUNCER_URL The Bouncer server's address (or --server). Or put it in
$XDG_CONFIG_HOME/bouncer/server (~/.config/bouncer/server).
BOUNCER_KEY The requester key itself. Or put it in a file: --key-file,
BOUNCER_KEY_FILE, or $XDG_CONFIG_HOME/bouncer/key
(~/.config/bouncer/key). The file must be private (chmod 600).
The key is never a command-line argument, and never printed.
BOUNCER_CA_FILE Extra CA certificates (PEM) to trust, for Bouncer and OpenBao
Durations are a whole number and a unit, as in the server's config: 30s, 15m,
6h or 7d, or always. A grant lasts from 1 minute to 365 days, or always.
With --json, each command prints the server's answer exactly as it came
(contract bouncer.v1); resources adds pending_request and active_grant to
each resource. An error from the server is printed the same way, as its
problem+json body, and explained on stderr.
Exit codes:
0 Done. For wait, request --wait and exec: the request was approved
1 Something went wrong (the server couldn't be reached, failed, or sent
something this version can't read)
2 The command line was wrong
3 The request was denied
4 The request expired without a decision
5 The request was cancelled or superseded
6 The server refused (key not accepted, not allowed, not found, invalid input)
7 Configuration problem (no server address, no key, a key file others
can read, plain http to another machine, an admin socket that can't
be opened, or resource_not_provisioned: the operator must apply and
check the role kit before retrying; no immediate retries)
8 No active grant for the resource
9 The deadline passed in a request state this version doesn't know
10 Revoked, but not every issued token was confirmed revoked
11 revoke --all wasn't confirmed
12 The server is running, but its vault (OpenBao) is sealed. Not a refusal:
the operator must unseal it
13 The server is running, but can't reach its vault (OpenBao)
14 The server is running, but its vault refused the server's own login.
Not a refusal of your key: the operator must fix the server's login
15 The proxy in front of the server got no answer from it (HTTP 502, 503
or 504 with no Bouncer error): the server is down or restarting
16 The server is running, but can't reach its database (PostgreSQL)
126 exec: the command couldn't be started
127 exec: the command wasn't found
Once exec has started the command, the exit code is the command's own.
bouncer resources
List the resources you may ask for: their fields, durations, and your pending requests and grants
Usage: bouncer resources [OPTIONS]
Options:
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
Connection (optional, see Configuration in bouncer --help):
--server <URL> The Bouncer server, such as https://bouncer.example.net. Default: the first line of ~/.config/bouncer/server [env: BOUNCER_URL]
--key-file <PATH> A file holding the requester key; it must be private (chmod 600). Default: BOUNCER_KEY, else ~/.config/bouncer/key [env: BOUNCER_KEY_FILE]
bouncer request
Ask for access to a resource. Prints the request ID
Usage: bouncer request [OPTIONS] --for <DURATION> --reason <REASON> <RESOURCE>
Arguments:
<RESOURCE> The resource's ID in the server's config, such as demo
Options:
--for <DURATION> How long you need it: 15m, 6h, 7d, always, ...
--reason <REASON> Why you need it, in your own words (up to 280 characters). The approver sees it
--json Print the server's answers as JSON, exactly as they came, for scripts
--wait Wait for the decision too, as bouncer wait does
--client <NAME> The program asking, shown to the approver as reported by you [default: bouncer CLI]
--host <NAME> This machine's name, shown to the approver as reported by you [default: the host name]
-h, --help Print help
Connection (optional, see Configuration in bouncer --help):
--server <URL> The Bouncer server, such as https://bouncer.example.net. Default: the first line of ~/.config/bouncer/server [env: BOUNCER_URL]
--key-file <PATH> A file holding the requester key; it must be private (chmod 600). Default: BOUNCER_KEY, else ~/.config/bouncer/key [env: BOUNCER_KEY_FILE]
bouncer status
Show one request, or your recent ones
Usage: bouncer status [OPTIONS] [REQUEST]
Arguments:
[REQUEST] A request ID (req_…). Without one, lists your recent requests
Options:
--limit <LIMIT> How many recent requests to list [default: 20]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
Connection (optional, see Configuration in bouncer --help):
--server <URL> The Bouncer server, such as https://bouncer.example.net. Default: the first line of ~/.config/bouncer/server [env: BOUNCER_URL]
--key-file <PATH> A file holding the requester key; it must be private (chmod 600). Default: BOUNCER_KEY, else ~/.config/bouncer/key [env: BOUNCER_KEY_FILE]
bouncer wait
Wait for the decision on a request. Exits 0 only if it's approved
Usage: bouncer wait [OPTIONS] <REQUEST>
Arguments:
<REQUEST> The request ID (req_…)
Options:
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
Connection (optional, see Configuration in bouncer --help):
--server <URL> The Bouncer server, such as https://bouncer.example.net. Default: the first line of ~/.config/bouncer/server [env: BOUNCER_URL]
--key-file <PATH> A file holding the requester key; it must be private (chmod 600). Default: BOUNCER_KEY, else ~/.config/bouncer/key [env: BOUNCER_KEY_FILE]
bouncer exec
Run a command with a resource's secret in its environment.
1. Finds your active grant for the resource. If there isn't one, files a
request with --reason and waits for the decision, or stops if you gave
--no-request. --for defaults to the resource's first duration (bouncer
resources lists them).
2. Fetches a short-lived OpenBao token for the grant (5 minutes by default),
unwrapping it at OpenBao if the server sends it wrapped.
3. Reads each of the grant's KV paths from OpenBao with that token, and
names a variable after each field: the field's name in upper case, with
anything other than letters and digits as _ (api_key becomes API_KEY).
Field names come from whoever wrote the secret, so by default only a name
that looks like a secret's is set: KEY, TOKEN, SECRET, PASSWORD or
PASSPHRASE, or one ending in _KEY, _TOKEN, _SECRET, _PASSWORD, _PASSPHRASE
or _ID. Any other field (url, cc, pager) is skipped, and a notice on stderr
names it. Another notice names each variable that was set, never its
value: a GITHUB_TOKEN or AWS_ACCESS_KEY_ID set from a field overrides
what gh or aws keep in their own config. exec stops before running
anything if a default name is protected (VAULT_TOKEN, BOUNCER_KEY,
SSH_KEY, NPM_TOKEN, DOPPLER_TOKEN and the other names below), is already
set, or two fields would get the same name. --env NAME=field picks the
fields and names them yourself; then only those are set. Use
NAME=mount/path:field when two paths have the same field. An --env may
replace an inherited variable, but a protected name also needs
--allow-env-name NAME.
On Linux, --file NAME=field puts a field in a private in-memory file
(mode 0600, sealed, never on disk) and sets NAME to its path, /dev/fd/N.
--stdin field gives a field to the command on its standard input. Once
you give any --env, --file or --stdin, only the fields you name are
passed on. A secret is never put in the command's arguments.
4. Runs the command, with BOUNCER_KEY taken out of its environment. Nothing
is revoked afterwards: the token expires by itself.
The values are read once, at the start. A long-running command keeps those
values, but the token itself expires within minutes, so the command can't
read anything new from OpenBao later.
bouncer never prints, logs or saves the secret. The exit code is the
command's own; bouncer --help lists bouncer's own codes.
Protected names: BOUNCER_*, VAULT_*, BAO_*, DOPPLER_*, INFISICAL_*, BWS_*, GIT_*, SSH_*, SSL_*, OPENSSL_*, CURL_*, XDG_*, BASH*, LESS*, TERMINFO*, PYTHON*, NODE_*, NPM_*, YARN_*, PERL*, RUBY*, GEM_*, BUNDLE_*, PIP_*, UV_*, LUA_*, ERL_*, DOTNET_*, CORECLR_*, CARGO_*, RUST*, CGO_*, DOCKER_*, KRB5*, LD_*, DYLD_*, MALLOC_*, *_PROXY, *FLAGS, *PAGER, *EDITOR, *_OPTS, *_OPTIONS, *_RSH, *_PUBLIC_KEY, PATH, HOME, SHELL, USER, LOGNAME, TMPDIR, TMP, TEMP, IFS, ENV, PS0, PS1, PS2, PS3, PS4, PROMPT_COMMAND, SHELLOPTS, HISTFILE, INPUTRC, ZDOTDIR, CC, CXX, CPP, LD, AR, MAKE, MAKEFILES, VISUAL, BROWSER, VIMINIT, GVIMINIT, EXINIT, NO_PROXY, REQUESTS_CA_BUNDLE, SSLKEYLOGFILE, NETRC, WGETRC, HOSTALIASES, LOCALDOMAIN, KUBECONFIG, GNUPGHOME, GPG_KEY, OP_SERVICE_ACCOUNT_TOKEN, OP_CONNECT_TOKEN, GCONV_PATH, GLIBC_TUNABLES, LOCPATH, NLSPATH, CLASSPATH, PHPRC, PHP_INI_SCAN_DIR, GOFLAGS, GOPROXY, GOSUMDB, GONOSUMDB, GONOPROXY, GOPRIVATE, GOINSECURE, GOTOOLCHAIN, GOENV, GOROOT, in any case.
Usage: bouncer exec [OPTIONS] <RESOURCE> -- <COMMAND>...
Arguments:
<RESOURCE>
The resource's ID in the server's config, such as demo
<COMMAND>...
The command to run, after --
Options:
--for <DURATION>
If there's no active grant: how long to ask for [default: the resource's first duration, as bouncer resources shows]
--reason <REASON>
If there's no active grant: why you need it
--json
Print the server's answers as JSON, exactly as they came, for scripts
--no-request
Don't ask for access: fail if there's no active grant
--env <NAME=FIELD>
Set NAME from a field: NAME=field, or NAME=mount/path:field. Repeatable
--file <NAME=FIELD>
Put a field in a private in-memory file and set NAME to its path (/dev/fd/N): NAME=field, or NAME=mount/path:field. Repeatable. Linux only
--stdin <FIELD>
Give a field to the command on its standard input: field, or mount/path:field. Linux and Windows
--prefix <PREFIX>
Put PREFIX in front of every default variable name
--allow-env-name <NAME>
Let an --env or --file set NAME even though it's a protected name (BOUNCER_*, VAULT_*, *_PROXY, GIT_*, CC, PATH, ...). Repeatable
--client <NAME>
The program asking, shown to the approver as reported by you [default: bouncer CLI]
--host <NAME>
This machine's name, shown to the approver as reported by you [default: the host name]
-h, --help
Print help (see a summary with '-h')
Connection (optional, see Configuration in bouncer --help):
--server <URL>
The Bouncer server, such as https://bouncer.example.net. Default: the first line of ~/.config/bouncer/server
[env: BOUNCER_URL]
--key-file <PATH>
A file holding the requester key; it must be private (chmod 600). Default: BOUNCER_KEY, else ~/.config/bouncer/key
[env: BOUNCER_KEY_FILE]
bouncer grants
List your grants (active ones, unless you give --all)
Usage: bouncer grants [OPTIONS]
Options:
--all List every grant, not just the active ones
--limit <LIMIT> How many to list [default: 50]
--json Print the server's answers as JSON, exactly as they came, for scripts
--resource <RESOURCE> Only the grants for this resource
--id-only Print only the grant IDs, one per line, newest first: GRANT=$(bouncer grants --resource demo --id-only | head -n 1)
-h, --help Print help
Connection (optional, see Configuration in bouncer --help):
--server <URL> The Bouncer server, such as https://bouncer.example.net. Default: the first line of ~/.config/bouncer/server [env: BOUNCER_URL]
--key-file <PATH> A file holding the requester key; it must be private (chmod 600). Default: BOUNCER_KEY, else ~/.config/bouncer/key [env: BOUNCER_KEY_FILE]
bouncer revoke
End one of your grants now, and revoke its tokens
Usage: bouncer revoke [OPTIONS] <GRANT>
Arguments:
<GRANT> The grant ID (grt_…)
Options:
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
Connection (optional, see Configuration in bouncer --help):
--server <URL> The Bouncer server, such as https://bouncer.example.net. Default: the first line of ~/.config/bouncer/server [env: BOUNCER_URL]
--key-file <PATH> A file holding the requester key; it must be private (chmod 600). Default: BOUNCER_KEY, else ~/.config/bouncer/key [env: BOUNCER_KEY_FILE]
bouncer cancel
Withdraw one of your pending requests
Usage: bouncer cancel [OPTIONS] <REQUEST>
Arguments:
<REQUEST> The request ID (req_…)
Options:
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
Connection (optional, see Configuration in bouncer --help):
--server <URL> The Bouncer server, such as https://bouncer.example.net. Default: the first line of ~/.config/bouncer/server [env: BOUNCER_URL]
--key-file <PATH> A file holding the requester key; it must be private (chmod 600). Default: BOUNCER_KEY, else ~/.config/bouncer/key [env: BOUNCER_KEY_FILE]
bouncer put
Save a new secret value into a resource, once it's approved.
Files a store request naming the fields (never the values), waits for the
approver to approve it on their phone or PC, then sends the values to the
Bouncer server, which saves them into the resource's secret in OpenBao. Other
fields in that secret are kept. Each approval saves once.
The value is never a command-line argument, so it stays out of your shell
history and the process list. Pipe it in, or give --file:
printf %s "$NEW_KEY" | bouncer put example-api-key --field api_key --reason "Rotated"
bouncer put example-api-key --field api_key --file ./new-key.txt --reason "Rotated"
With one --field, the whole input is the value (one trailing newline is
dropped). With several, the input is a JSON object with one string per field:
{"api_key": "...", "region": "..."}.
The resource must allow writes (allow_write in the server's config). Exits 0
once saved, 3 if denied, 4 if the request expired.
Usage: bouncer put [OPTIONS] --field <NAME> --reason <REASON> <RESOURCE>
Arguments:
<RESOURCE>
The resource's ID in the server's config, such as example-api-key
Options:
--field <NAME>
The field to save, such as api_key. Repeat for several fields
--file <PATH>
Read the value from this file instead of standard input
--json
Print the server's answers as JSON, exactly as they came, for scripts
--reason <REASON>
Why you're saving it, in your own words (up to 280 characters). The approver sees it
--for <DURATION>
How long, once approved, the values may still be sent: 1m to 1h
[default: 5m]
--client <NAME>
The program asking, shown to the approver as reported by you [default: bouncer CLI]
--host <NAME>
This machine's name, shown to the approver as reported by you [default: the host name]
-h, --help
Print help (see a summary with '-h')
Connection (optional, see Configuration in bouncer --help):
--server <URL>
The Bouncer server, such as https://bouncer.example.net. Default: the first line of ~/.config/bouncer/server
[env: BOUNCER_URL]
--key-file <PATH>
A file holding the requester key; it must be private (chmod 600). Default: BOUNCER_KEY, else ~/.config/bouncer/key
[env: BOUNCER_KEY_FILE]
bouncer ssh
Log in to an SSH host resource with a short-lived certificate.
1. Finds your active grant for the resource, or files a request (--reason,
and --for or the resource's first duration) and waits for the decision,
as exec does.
2. Makes a new ed25519 key with ssh-keygen, in a private temporary folder.
3. Sends its public half to Bouncer, which has OpenBao sign a certificate
for it: one account (the resource's principal), at most the resource's
credential TTL (5 minutes by default), never past the grant's end, and
usually bound to the address the server saw you call from.
4. Runs ssh with that key and certificate only (no agent, no other keys,
no passwords) as <principal>@<the --to host>, then deletes the key.
The private key never leaves this machine. A revoke stops new logins once
the host has fetched Bouncer's revocation list, normally within 15 seconds;
a session that is already open stays open. The exit code is ssh's own.
Usage: bouncer ssh [OPTIONS] --to <HOST> <RESOURCE> [-- <COMMAND>...]
Arguments:
<RESOURCE>
The SSH host resource's ID in the server's config, such as web1
[COMMAND]...
A command to run on the host instead of a shell, after --
Options:
--to <HOST>
The host to connect to: a name or address ssh understands
--port <PORT>
The port, if it isn't 22
--for <DURATION>
If there's no active grant: how long to ask for [default: the resource's first duration, as bouncer resources shows]
--json
Print the server's answers as JSON, exactly as they came, for scripts
--reason <REASON>
If there's no active grant: why you need it
--no-request
Don't ask for access: fail if there's no active grant
--ssh-option <KEY=VALUE>
Pass an option to ssh, as ssh -o does, such as UserKnownHostsFile=~/.ssh/work_hosts. Repeatable
--client <NAME>
The program asking, shown to the approver as reported by you [default: bouncer CLI]
--host <NAME>
This machine's name, shown to the approver as reported by you [default: the host name]
-h, --help
Print help (see a summary with '-h')
Connection (optional, see Configuration in bouncer --help):
--server <URL>
The Bouncer server, such as https://bouncer.example.net. Default: the first line of ~/.config/bouncer/server
[env: BOUNCER_URL]
--key-file <PATH>
A file holding the requester key; it must be private (chmod 600). Default: BOUNCER_KEY, else ~/.config/bouncer/key
[env: BOUNCER_KEY_FILE]
bouncer self-update
Update a user-local install of bouncer and bouncer-mcp (from install.sh) to the newest signed release. It does nothing unless you run it: no background checks.
The release manifest must be signed by the key built into this bouncer, list a build for this machine, and be newer than this version. Each binary must match the manifest's SHA-256. The old binaries are kept beside the new ones as .bouncer.old and .bouncer-mcp.old.
It refuses while another bouncer or bouncer-mcp from this install is running, and for binaries a package manager owns (/usr/bin, or anything dpkg or rpm knows): update those with apt or dnf.
Usage: bouncer self-update [OPTIONS]
Options:
--check
Only say whether an update is available
--prerelease
Follow the prerelease channel instead of stable
--allow-downgrade
Allow installing an older version than this one
--rollback
Put back the binaries the last update replaced
--feed <URL>
The update feed's base URL (https, or http to this machine)
[env: BOUNCER_UPDATE_FEED=]
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version
bouncer-admin
Pair devices, manage requester keys and pull the kill switch, on the Bouncer server's own machine
Usage: bouncer-admin [OPTIONS] <COMMAND>
Commands:
device Pair, list and revoke phones and PCs
requester Create requesters (people, agents and hosts), rotate their keys, disable them
revoke The kill switch: end every grant, cancel every pending request, revoke every token
config The policy config file
downstream Credentials issued by other systems (a Proxmox API token, say), which Bouncer can't revoke there
grant Standing (Always) grants: re-confirm their review
log The approval log
personal Personal credentials (D63): suspend Always approved, freeze, reassign
help Print this message or the help of the given subcommand(s)
Options:
--socket <PATH>
The server's admin socket
[env: BOUNCER_ADMIN_SOCKET=]
--json
Print the server's answers as JSON, exactly as they came, for scripts
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version
bouncer-admin runs on the Bouncer server's own machine. It talks to the
server over a local Unix socket, never the network: --socket, else
BOUNCER_ADMIN_SOCKET, else /run/bouncer/admin.sock. The socket's file
permissions decide who is the admin.
With --json, each command prints the server's answer exactly as it came
(contract bouncer.v1).
Exit codes:
0 Done. For wait, request --wait and exec: the request was approved
1 Something went wrong (the server couldn't be reached, failed, or sent
something this version can't read)
2 The command line was wrong
3 The request was denied
4 The request expired without a decision
5 The request was cancelled or superseded
6 The server refused (key not accepted, not allowed, not found, invalid input)
7 Configuration problem (no server address, no key, a key file others
can read, plain http to another machine, an admin socket that can't
be opened, or resource_not_provisioned: the operator must apply and
check the role kit before retrying; no immediate retries)
8 No active grant for the resource
9 The deadline passed in a request state this version doesn't know
10 Revoked, but not every issued token was confirmed revoked
11 revoke --all wasn't confirmed
12 The server is running, but its vault (OpenBao) is sealed. Not a refusal:
the operator must unseal it
13 The server is running, but can't reach its vault (OpenBao)
14 The server is running, but its vault refused the server's own login.
Not a refusal of your key: the operator must fix the server's login
15 The proxy in front of the server got no answer from it (HTTP 502, 503
or 504 with no Bouncer error): the server is down or restarting
16 The server is running, but can't reach its database (PostgreSQL)
126 exec: the command couldn't be started
127 exec: the command wasn't found
Once exec has started the command, the exit code is the command's own.
bouncer-admin device
Pair, list and revoke phones and PCs
Usage: bouncer-admin device [OPTIONS] <COMMAND>
Commands:
pair Make a one-time pairing code, shown as a QR code to scan with the app
list List every device, active and revoked
revoke Revoke a device: it can no longer sign in, decide or see anything. Its Always grants end; its finite grants stay until they end
help Print this message or the help of the given subcommand(s)
Options:
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin device pair
Make a one-time pairing code, shown as a QR code to scan with the app
Usage: bouncer-admin device pair [OPTIONS] --person <PERSON>
Options:
--person <PERSON> The person the device pairs as: their ID in the config file
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
--ttl <TTL> How long the code works: 1m to 30m [default: 5m]
-h, --help Print help
bouncer-admin device list
List every device, active and revoked
Usage: bouncer-admin device list [OPTIONS]
Options:
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin device revoke
Revoke a device: it can no longer sign in, decide or see anything. Its Always grants end; its finite grants stay until they end
Usage: bouncer-admin device revoke [OPTIONS] <DEVICE>
Arguments:
<DEVICE> The device ID (dev_…)
Options:
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin requester
Create requesters (people, agents and hosts), rotate their keys, disable them
Usage: bouncer-admin requester [OPTIONS] <COMMAND>
Commands:
add Create a requester and its first key. The key is shown once
list List every requester
rotate-key Issue a new key and stop the old one at once. The new key is shown once. Its standing grants are suspended
disable Disable a requester: its key stops working, its pending requests are cancelled and its grants revoked [alias: revoke]
help Print this message or the help of the given subcommand(s)
Options:
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin requester add
Create a requester and its first key. The key is shown once
Usage: bouncer-admin requester add [OPTIONS] --kind <KIND> <NAME>
Arguments:
<NAME> A name: lower-case letters, digits, dots, dashes and underscores, such as build-agent
Options:
--kind <KIND> What it is [possible values: agent, host, human]
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
--owner <OWNER> The person it belongs to, by their ID in the config file. Their requests are labelled as theirs (D18)
-h, --help Print help
bouncer-admin requester list
List every requester
Usage: bouncer-admin requester list [OPTIONS]
Options:
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin requester rotate-key
Issue a new key and stop the old one at once. The new key is shown once. Its standing grants are suspended
Usage: bouncer-admin requester rotate-key [OPTIONS] <REQUESTER>
Arguments:
<REQUESTER> The requester's ID (rqr_…) or name
Options:
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin requester disable
Disable a requester: its key stops working, its pending requests are cancelled and its grants revoked
Usage: bouncer-admin requester disable [OPTIONS] <REQUESTER>
Arguments:
<REQUESTER> The requester's ID (rqr_…) or name
Options:
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin revoke
The kill switch: end every grant, cancel every pending request, revoke every token
Usage: bouncer-admin revoke [OPTIONS] --all
Options:
--all Everything. Required: there's no partial kill switch
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-y, --yes Don't ask for confirmation
-h, --help Print help
bouncer-admin config
The policy config file
Usage: bouncer-admin config [OPTIONS] <COMMAND>
Commands:
reload Load the config file again. An invalid one is refused and the old one stays
help Print this message or the help of the given subcommand(s)
Options:
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin config reload
Load the config file again. An invalid one is refused and the old one stays
Usage: bouncer-admin config reload [OPTIONS]
Options:
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin downstream
Credentials issued by other systems (a Proxmox API token, say), which Bouncer can't revoke there
Usage: bouncer-admin downstream [OPTIONS] <COMMAND>
Commands:
list List each one, and whether it needs rotating at its system
rotated Record that you rotated one at its system and updated its secret
help Print this message or the help of the given subcommand(s)
Options:
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin downstream list
List each one, and whether it needs rotating at its system
Usage: bouncer-admin downstream list [OPTIONS]
Options:
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin downstream rotated
Record that you rotated one at its system and updated its secret
Usage: bouncer-admin downstream rotated [OPTIONS] <RESOURCE>
Arguments:
<RESOURCE> The resource ID in the config file
Options:
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin grant
Standing (Always) grants: re-confirm their review
Usage: bouncer-admin grant [OPTIONS] <COMMAND>
Commands:
review Re-confirm a standing grant, so it isn't suspended when its review is due (D22)
help Print this message or the help of the given subcommand(s)
Options:
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin grant review
Re-confirm a standing grant, so it isn't suspended when its review is due (D22)
Usage: bouncer-admin grant review [OPTIONS] <GRANT>
Arguments:
<GRANT> The grant ID (grt_…)
Options:
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin log
The approval log
Usage: bouncer-admin log [OPTIONS] <COMMAND>
Commands:
export Write every entry, oldest first, as JSON lines, for an archive, syslog or a SIEM. Never holds a secret
help Print this message or the help of the given subcommand(s)
Options:
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin log export
Write every entry, oldest first, as JSON lines, for an archive, syslog or a SIEM. Never holds a secret
Usage: bouncer-admin log export [OPTIONS]
Options:
--since <SINCE> Only entries from this time on: a time such as 2026-11-01T00:00:00Z, or how long ago, such as 24h or 7d
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
--until <UNTIL> Only entries before this time, in the same forms
--after <AFTER> Carry on after this cursor, from the end of an earlier export
--cursor-file <FILE> Start after the cursor in this file, if it exists, and save the new one there when done. For a job that ships only what's new each run
--out <FILE> Write to this new file (mode 0600) instead of stdout. An existing file isn't overwritten
-h, --help Print help
bouncer-admin personal
Personal credentials (D63): suspend Always approved, freeze, reassign
Usage: bouncer-admin personal [OPTIONS] <COMMAND>
Commands:
suspend Suspend Always approved: requests wait for approval until the owner signs it again (D22)
freeze Freeze: nobody can use it until it's reassigned; its grants end
reassign Give a frozen credential, or one whose owner left the config file, to another person
help Print this message or the help of the given subcommand(s)
Options:
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin personal suspend
Suspend Always approved: requests wait for approval until the owner signs it again (D22)
Usage: bouncer-admin personal suspend [OPTIONS] [CREDENTIAL]
Arguments:
[CREDENTIAL] The personal credential ID (pc-…)
Options:
--namespace <NAMESPACE> Every personal credential in this namespace instead
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin personal freeze
Freeze: nobody can use it until it's reassigned; its grants end
Usage: bouncer-admin personal freeze [OPTIONS] [CREDENTIAL]
Arguments:
[CREDENTIAL] The personal credential ID (pc-…)
Options:
--namespace <NAMESPACE> Every personal credential in this namespace instead
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-admin personal reassign
Give a frozen credential, or one whose owner left the config file, to another person
Usage: bouncer-admin personal reassign [OPTIONS] --owner <OWNER> <CREDENTIAL>
Arguments:
<CREDENTIAL> The personal credential ID (pc-…)
Options:
--owner <OWNER> The new owner, a person ID from the config file. Always approved stays suspended until they sign it
--socket <PATH> The server's admin socket [env: BOUNCER_ADMIN_SOCKET=]
--json Print the server's answers as JSON, exactly as they came, for scripts
-h, --help Print help
bouncer-mcp
bouncer-mcp: the Bouncer MCP server. It lets an AI agent ask a human for
access to a secret, wait for the human to approve it on their phone, and then
read the secret. Agents can never approve anything.
An MCP client starts it and talks to it over stdin and stdout. For Claude Code:
claude mcp add bouncer \
--env BOUNCER_URL=https://bouncer.example.net \
--env BOUNCER_KEY_FILE=$HOME/.config/bouncer/agent-key \
-- /path/to/bouncer-mcp
Usage:
bouncer-mcp Serve MCP over stdin and stdout
bouncer-mcp --check Check the settings and the key against the server, then exit
bouncer-mcp --version Print the version
bouncer-mcp --help Print this help
Settings (environment variables):
BOUNCER_URL The Bouncer server's address: https://, or http:// to this
machine only
BOUNCER_KEY_FILE Required. The file holding the agent's own requester key.
It must be private (chmod 600). The CLI's default key file
is never used, and the key itself is never read from the
environment.
BOUNCER_CA_FILE Extra CA certificates (PEM) to trust, for Bouncer and OpenBao
The key must belong to an agent requester. At start-up, and with --check,
bouncer-mcp asks the server who the key belongs to, and refuses to run with a
person's or a host's key. Make an agent requester with:
bouncer-admin requester add <name> --kind agent --owner <person>
Logs go to stderr. The key, the OpenBao tokens and secret values never appear
in them.
bouncer-server
The server's own options. The compose kit sets them for you (--trusted-proxy 127.0.0.1 in compose.yaml, and --config and --listen from the entrypoint).
usage: bouncer-server --config <file> [--listen <address:port>] [--admin-socket <path>] [--release-mode wrapped|direct] [--trusted-proxy <ip>]... [--fake-backend]
--config <file> the policy config file (required)
--check-config read-only OpenBao preflight for this candidate file;
print each resource's result and exit (no database)
--listen <addr:port> the public API's TCP address (default 127.0.0.1:8080)
--admin-socket <path> the admin API's Unix socket (default: $BOUNCER_ADMIN_SOCKET,
else /run/bouncer/admin.sock)
--release-mode <mode> how tokens are handed over: wrapped (default) or direct
--trusted-proxy <ip> a proxy whose X-Forwarded-For is believed, for the caller's
address; repeat for more. None by default. Behind
tailscale serve, use 127.0.0.1
--fake-backend use a built-in fake instead of OpenBao, for trying the
server out. Its tokens are fake and open nothing.
Without --fake-backend, the server issues tokens through OpenBao, using the
config's openbao section and the role kit's role ID and secret ID files.
The database URL comes from DATABASE_URL. Push is set in the config file's
push section.
Environment variables
bouncer (the CLI)
| Variable | Meaning |
|---|---|
BOUNCER_URL | The Bouncer server's address. --server overrides it. Without either, the first line of ~/.config/bouncer/server is used |
BOUNCER_KEY_FILE | The file holding the requester key. --key-file overrides it |
BOUNCER_KEY | The requester key itself, used when no key file is given. A file is safer |
BOUNCER_CA_FILE | A PEM file of extra CA certificates, trusted for both Bouncer and OpenBao |
HTTPS_PROXY, ALL_PROXY, NO_PROXY | Proxy for HTTPS calls and hosts that bypass it. Lower-case names work too. HTTP_PROXY is never used |
XDG_CONFIG_HOME | When set, overrides the configuration folder on Linux and Windows. Without it, Linux uses ~/.config; on Windows, the defaults are %LOCALAPPDATA%\bouncer\server and %LOCALAPPDATA%\bouncer\key |
SSL_CERT_FILE | Where the system's CA certificates are, if not in the usual places |
BOUNCER_UPDATE_FEED | The update feed for bouncer self-update (Linux) |
bouncer exec removes BOUNCER_KEY from the child environment. It passes BOUNCER_KEY_FILE on, and the child can still read the key file. Trust the command you run.
bouncer-mcp
| Variable | Meaning |
|---|---|
BOUNCER_URL | Required. The Bouncer server's address: https://, or http:// to this machine only. Unlike bouncer, it does not read ~/.config/bouncer/server |
BOUNCER_KEY_FILE | Required. The agent's key file. The key itself is never read from the environment |
BOUNCER_CA_FILE | Extra CA certificates, as for bouncer |
HTTPS_PROXY, ALL_PROXY, NO_PROXY | Proxy settings as for bouncer, including lower-case names |
bouncer-admin
| Variable | Meaning |
|---|---|
BOUNCER_ADMIN_SOCKET | The admin socket. --socket overrides it. Default /run/bouncer/admin.sock |
NO_COLOR | Set to stop device pair forcing white-on-black colours for the QR code |
bouncer-server
| Variable | Meaning |
|---|---|
DATABASE_URL | The PostgreSQL connection URL. Never logged. The compose kit leaves the password out of it and supplies it separately |
PGPASSWORD | The database password, when DATABASE_URL has none. The compose kit's entrypoint sets it from the password file |
BOUNCER_ADMIN_SOCKET | Where to create the admin socket. --admin-socket overrides it |
RUST_LOG | Log filter, including full EnvFilter directives. Default info; levels include error, warn and debug |
BOUNCER_TEST_FCM_ENDPOINT, BOUNCER_TEST_FCM_TOKEN_URI | Tests only. Point push at a fake on this machine. Never set them on a real server |
The container entrypoint
The entrypoint uses these defaults unless a value is supplied. compose.yaml sets some of them; change its values through .env where noted.
| Variable | Default | Meaning |
|---|---|---|
BOUNCER_CONFIG | /etc/bouncer/bouncer.yaml | The config file inside the container |
BOUNCER_LISTEN | 127.0.0.1:8080 | The address the server listens on. From BOUNCER_PORT in .env |
BOUNCER_DB_PASSWORD_FILE | /run/secrets/bouncer-db-password | The database password file |
BOUNCER_WAIT_FOR_OPENBAO | empty | Ignored from 0.5.6, and the entrypoint logs that it is. It used to hold the server back until OpenBao was unsealed; the server now starts anyway and answers 503 until OpenBao is ready (When Bouncer is unavailable) |
The compose .env file
deploy/compose/.env holds settings, never secrets: docker compose config prints them.
| Variable | Default | Meaning |
|---|---|---|
BOUNCER_PORT | 8080 | The port on 127.0.0.1 |
BOUNCER_CONFIG_DIR | /etc/bouncer/config | The folder holding bouncer.yaml, mounted read-only at /etc/bouncer |
BOUNCER_SECRETS_DIR | /etc/bouncer/secrets | The folder holding the secret files |
BOUNCER_IMAGE | localhost/bouncer-server:local | The server image |
BOUNCER_VERSION, BOUNCER_REVISION | local, unknown | Labels for a local build |
BUILD_JOBS | empty | Parallel compile jobs, for a small machine |
BOUNCER_WAIT_FOR_OPENBAO | empty | See above |
RUST_LOG | info | The server's log level |
COMPOSE_FILE | compose.yaml | Add compose.push.yaml, compose.push2.yaml or compose.ssh.yaml, separated by : |
Ports and files
Ports
| Port | Where | What |
|---|---|---|
| 443 | Your HTTPS front end | What apps and requesters connect to (instance.url) |
| 8080 | 127.0.0.1 on the server | The Bouncer server's plain HTTP listener. Change with BOUNCER_PORT |
| 8200 | OpenBao | OpenBao's API. The deploy/openbao kit listens on 127.0.0.1:8200 and puts HTTPS in front, on 8443 in its README |
| none | PostgreSQL has no network; the server uses its Unix socket | |
| none | The admin API is a Unix socket only |
Outbound from the server: OpenBao, and Firebase (Google, port 443) if push is on.
On the server's machine
These modes are set by the install instructions. The requester key's mode is checked by code; the other modes are deployment requirements.
| Path | Mode and owner | What |
|---|---|---|
~/bouncer | The repository checkout. Nothing secret | |
/opt/bouncer/releases/<full commit> | With ship.sh: that commit's deploy/ folder only. Nothing secret | |
~/bouncer/deploy/compose/.env (or /opt/bouncer/releases/<full commit>/deploy/compose/.env) | Compose settings. Nothing secret | |
/etc/bouncer/config/bouncer.yaml | 0644 | The config file |
/etc/bouncer/config/openbao-ca.pem | 0644 | OpenBao's CA, if needed |
/etc/bouncer/secrets/ | 0700, user 10001 | The secret files |
/etc/bouncer/secrets/bouncer-role-id | 0400, user 10001 | OpenBao AppRole role_id |
/etc/bouncer/secrets/bouncer-secret-id | 0400, user 10001 | OpenBao AppRole secret_id |
/etc/bouncer/secrets/bouncer-db-password | 0400, user 10001 | The database password |
/etc/bouncer/secrets/bouncer-ssh-role-id | 0400, user 10001 | SSH signer AppRole role_id, if SSH is on (compose.ssh.yaml) |
/etc/bouncer/secrets/bouncer-ssh-secret-id | 0400, user 10001 | SSH signer AppRole secret_id, if SSH is on |
/etc/bouncer/secrets/fcm-service-account-2.json | 0400, user 10001 | Second Firebase key while moving projects (compose.push2.yaml) |
/etc/bouncer/secrets/fcm-service-account.json | 0400, user 10001 | Firebase key, if push is on |
/var/backups/bouncer/ | 0700 | Daily backups from the timer |
/usr/local/libexec/bouncer-backup | 0755 | backup.sh, installed for the timer |
/etc/systemd/system/bouncer-logical-backup.{service,timer} | 0644 | The backup timer |
Inside the server container
| Path | What |
|---|---|
/etc/bouncer/ | The config folder, read-only |
/run/secrets/<name> | The secret files, read-only |
/run/bouncer/admin.sock | The admin socket, mode 0600, on the bouncer-run volume |
/run/postgresql/ | PostgreSQL's socket, read-only, on the pg-socket volume |
The container's root filesystem is read-only, it has no Linux capabilities, and it runs as user 10001.
Docker volumes
| Volume | What |
|---|---|
bouncer_pgdata | PostgreSQL's data. docker compose down -v deletes it |
bouncer_pg-socket | PostgreSQL's socket, a small in-memory volume |
bouncer_bouncer-run | The admin socket |
On a requester's machine
| Path | Mode | What |
|---|---|---|
~/.local/bin/bouncer, ~/.local/bin/bouncer-mcp | 0755 | The binaries (or /usr/local/bin, or /usr/bin from a package) |
~/.config/bouncer/ | 0700 | Settings folder |
~/.config/bouncer/server | The server's address | |
~/.config/bouncer/key | 0600 | The requester key |
%LOCALAPPDATA%\bouncer\server, %LOCALAPPDATA%\bouncer\key | private to the Windows account | Windows CLI settings and encrypted key |
The role kit
| Path | What |
|---|---|
deploy/openbao-role-kit/resources | Your list of secrets. Keep it, in your own repository; the emergency stop needs it |
deploy/openbao-role-kit/kit.env | Your kit settings, if you changed any |
deploy/openbao-role-kit/rendered/ | Policies the kit rendered |
All three are ignored by Git in the Bouncer repository.
Get Bouncer
This page says where each part of Bouncer comes from today. The files are in private releases on the Bouncer project's GitLab. There's no public download, store listing, package repository or container registry yet. Platforms and status has the state of each test channel, such as Google Play internal testing, Firebase and TestFlight.
Where the files are today
The published releases are private releases on the Bouncer project's GitLab. As checked on 19 November 2026, these include 0.5.4, 0.5.5 and 0.5.7. Version 0.5.6 was built and tested, but has no GitLab release. The private download links only work for someone signed in to that GitLab with access to the project, so testers get them from whoever gave them access to Bouncer. If you don't have access, ask that person for the files. They aren't publicly available.
The Android 0.5.7 internal build on Firebase App Distribution is the same file as the one in the GitLab release.
Each release has one SHA256SUMS file with the SHA-256 of every file in it.
Check what you downloaded against it before you install anything. On Linux,
in the folder with the files:
sha256sum -c SHA256SUMS --ignore-missing
Each file you have must say OK. --ignore-missing skips the release's other
files, the ones you didn't download. If a line says FAILED, download that
file again, and don't use it until it matches. On Windows, run
Get-FileHash -Algorithm SHA256 <file> in PowerShell and compare the hash
with that file's line in SHA256SUMS.
The sums show that a file is the one the release describes. They aren't a
signature, so get SHA256SUMS from the release itself, not from a copy
someone forwarded.
Private 0.5.7 release
The private GitLab release v0.5.7+34 is from commit
b329764d1b909dc6cc5fbd560d018933d14ab8e0. It has the 21 files below,
all checked against their SHA256 hashes after upload. The source repository
and release are private. Get the private links from the person who gave
you access to Bouncer, as for the earlier releases.
| Part | Release files |
|---|---|
| Android | bouncer-android-0.5.7+34.apk, bouncer-android-0.5.7+34-internal.apk, bouncer-android-0.5.7+34.aab, bouncer-android-0.5.7+34-receipt.json, bouncer-android-0.5.7+34-internal-receipt.json and bouncer-android-upload-certificate.pem |
| Windows app | bouncer-windows-x64-0.5.7+34.msix, bouncer-windows-x64-0.5.7+34.zip, bouncer-beta-signing.cer and bouncer-windows-install-instructions.md |
| Linux CLI and MCP | install.sh, bouncer-cli-0.5.7+34-x86_64-linux.tar.gz, bouncer-cli_0.5.7+34-1_amd64.deb and bouncer-cli-0.5.7+34-1.x86_64.rpm |
| Windows CLI and MCP | install-windows-cli.ps1 and bouncer-cli-0.5.7+34-x86_64-windows.zip |
| Server | bouncer-server-0.5.7+34-image.tar.gz, bouncer-server-0.5.7+34-compose.tar.gz, bouncer-server-0.5.7+34-SHA256SUMS and INSTALL-SERVER.md |
| Whole release | SHA256SUMS |
iOS 0.5.7 is in internal TestFlight for S6 Studios' own testing. Platforms and status has the state of each test channel, and the 0.5.7 notes list the changes.
What each release has
The table below uses the file names of the earlier 0.5.5 private release. Other releases name their files the same way, with their own version. There's no 0.5.6 GitLab release.
| You want | The files | How to install |
|---|---|---|
| The Android app | bouncer-android-0.5.5+32.apk | Install on Android |
| The Android internal test build (testers only) | bouncer-android-0.5.5+32-internal.apk | This is the file in the 0.5.5 private release. The newer Firebase build and test-build differences are described under Test builds |
| The Windows app | bouncer-windows-x64-0.5.5+32.msix with bouncer-beta-signing.cer and bouncer-windows-install-instructions.md, or the portable bouncer-windows-x64-0.5.5+32.zip | Install on Windows |
| The CLI and MCP server on Linux | install.sh with bouncer-cli-0.5.5+32-x86_64-linux.tar.gz, or the packages bouncer-cli_0.5.5+32-1_amd64.deb and bouncer-cli-0.5.5+32-1.x86_64.rpm | Install the CLI |
| The CLI and MCP server on Windows | install-windows-cli.ps1 with bouncer-cli-0.5.5+32-x86_64-windows.zip | Install the CLI |
| The server | bouncer-server-0.5.5+32-image.tar.gz and bouncer-server-0.5.5+32-compose.tar.gz, with INSTALL-SERVER.md and the release's SHA256SUMS; see The server | Install the server |
| The iPhone and Mac apps | None | iPhone and Mac |
0.5.5 also has the Android App Bundle (.aab), which is for Google Play
and isn't installed by hand, the Android upload certificate, and a receipt for
each APK.
The server
The 0.5.5 and 0.5.7 private releases include the server image as a file, so the server needs no access to the source and compiles nothing. Download these files:
bouncer-server-<version>-image.tar.gz, the image, which you load withdocker load;bouncer-server-<version>-compose.tar.gz, the deploy kit: the Compose files, the OpenBao role kit, the dedicated OpenBao kit and the guides they point to;INSTALL-SERVER.md, the install guide for that release.
The 0.5.7 release also has bouncer-server-0.5.7+34-SHA256SUMS, with the
sums of just those three files. Check them with:
sha256sum -c bouncer-server-0.5.7+34-SHA256SUMS
The 0.5.5 release has no server-only file, so use the release's
SHA256SUMS:
sha256sum -c SHA256SUMS --ignore-missing
The 0.5.5 INSTALL-SERVER.md says sha256sum -c SHA256SUMS. Add
--ignore-missing so files from the rest of the release are skipped.
0.5.5 was the first published release with the server image and kit. 0.5.4 and earlier were published before the step that builds them existed. For those, build the image from the source, which needs access to the source repository. Install the server covers both ways.
The image isn't signed yet. Check the sums and the image labels against the release details you got through a channel you trust. The labels don't prove who built the image.
Licence and planned pricing
The licence files in each release and in the source apply. The source repository is private. S6 Studios plans to move the self-hosted server to the Elastic License 2.0 (ELv2) and to price it per active person; service accounts and agents won't count as seats. Free use for up to 10 people is planned as the normal way to evaluate Bouncer, with an optional trial for larger evaluations. Prices and legal wording aren't final. Neither the licence change nor seat limits have shipped; they're planned for after the store launch, or whenever they can be built.
What isn't decided yet
Where public downloads will live, and whether the server image will also go into a container registry, aren't decided. Until they are, this page won't give an address for them.
Platforms and status
This page says what exists on each platform today. It uses these labels:
- Beta: a released build, in use for testing.
- Internal testing: built, and distributed only for S6 Studios' own testing.
- Blocked: built, but waiting on something outside the code. The Notes say what.
- In development: being written. Nothing to install yet.
- Not planned: no work on it for the first release.
Status on 19 November 2026
- GitLab releases. The private GitLab releases include 0.5.4, 0.5.5 and 0.5.7. Version 0.5.6 was built and tested but has no GitLab release.
- Google Play. The internal track is for S6 Studios' own testing. It has 0.5.7 as a draft, while 0.5.4, signed by Play, is still the active internal release.
- Firebase App Distribution. The Android 0.5.7 internal build is distributed for S6 Studios' own testing. It isn't installed on a phone yet, and the App Tester icon check is still pending.
- TestFlight. S6 Studios installed an earlier iPhone test build
(
0.5.4+32) from internal TestFlight on a real iPhone, paired it, received a lock-screen notification and approved a request with it. iOS 0.5.7 is in internal TestFlight for S6 Studios' own testing, and hasn't been checked on a real iPhone yet. - Windows. The MSIX is signed with S6 Studios' own certificate, not one from the Microsoft Store or a public certificate authority. Enrolling a real PC with a Windows Hello TPM attestation is still pending.
- Device checks. 0.5.7 hasn't yet been checked on real phones and PCs. That includes the iPhone's reconnecting notice, its Notification settings and push.
- Store submissions. Nothing has been submitted for review on Google Play, the App Store or the Microsoft Store, and there's no public store listing.
Apps for approvers
| Platform | Status | What you can install | Notes |
|---|---|---|---|
| Android 9 or later | Beta | An APK from the private GitLab release. Firebase and Play internal testing have test builds for S6 Studios' own testing (see above) | A copy from Google Play and a sideloaded APK are signed with different keys, so one can't update the other. Install on Android |
| Windows 11 | Beta | A test-signed installer (MSIX), or a portable ZIP, from the private GitLab release | Requests arrive only while Bouncer is running, because there's no push to a closed app. To approve, you need Windows Hello with a TPM security chip, and your server has to accept Windows Hello keys (it doesn't by default). From 0.5.7, the server checks a TPM attestation at enrolment when Windows supplies one, but no real PC has passed that check yet, and keys enrolled before it stay unchecked (Device keys). Install on Windows |
| iPhone (iOS 15 or later) | Internal testing | Nothing yet. iOS 0.5.7 is in internal TestFlight for S6 Studios' own testing (see above) | iPhone and Mac |
| Mac | In development | Nothing yet | |
| Linux desktop | Not planned | Use the command-line tools on Linux. |
Tools for requesters and administrators
| Tool | Status | What you can install |
|---|---|---|
bouncer and bouncer-mcp on Linux (x86_64) | Beta | A tarball with an installer script, or a .deb or .rpm file, from the private GitLab release. A package repository and the update channel are built and tested, but not published yet. |
bouncer and bouncer-mcp on Windows (x86_64) | Beta, from 0.5.1 | A zip with a per-user installer. Not code-signed yet. Install the CLI |
bouncer-admin | Beta | Runs on the Bouncer server's own machine |
The server
| Part | Status | Notes |
|---|---|---|
| Bouncer server, with OpenBao | Beta | The Bouncer project's own production server runs build 0.3.8+25. The private 0.5.7 release includes a server image and kit; 0.5.6 is built but has no GitLab release. The source repository is private. You can also build from source. Get Bouncer |
Known limits that apply everywhere
- People are set up in the server's config file. Each person who can approve or ask for access is an entry in the server's configuration. Signing in with an organisation account (for example through Keycloak or another OpenID Connect provider) isn't connected yet.
- Approving from a notification is Android only. On Windows, a notification only opens the request.
- Folders can be made, but not renamed, moved or deleted in the apps.
- Bouncer covers OpenBao secrets and SSH hosts. It works with the secrets kept in OpenBao and with SSH hosts set up for it. It doesn't control access to other systems on its own, and it can't end sessions those systems keep open.
How it was tested
Many features have been checked on Android emulators, a Windows test machine and Apple's iPhone simulator, and a few on real phones and PCs. The release notes say what each release was checked on.
Releases
Every Bouncer app, the command-line tools and the server share one version
number, such as 0.5.7. Each build also has a build number, which goes up with
every build. The full build string, such as 0.5.7+34, appears in file
names, under Settings > About and in bouncer --version. A published
GitLab release is tagged with it too: the private GitLab release of 0.5.7 is
v0.5.7+34.
All releases so far are betas. Platforms and status says
which releases are published, and what each test channel has. Updating a
client doesn't upgrade its server. The Bouncer project's own production
server runs build 0.3.8+25.
To find the version you have, open Settings in the app and look under
About, or run bouncer --version.
Versions
| Version | Main changes for app users |
|---|---|
| 0.5.7 | Reconnecting notice after unlock or resume, iOS Notification settings, clearer Library ownership and sharing, Android icons, new hardware-key settings and Windows TPM enrolment checks. Server upgrade, role-kit update and migrations 0017 to 0019; see the upgrade and rollback notes. |
| 0.5.6 | Android, Windows, the command line and the server. A server from this release stays up while OpenBao is sealed, and answers 503 with the reason instead of restarting in a loop. The apps and the command line say why Bouncer is unavailable. A device that can't approve a request says why, and which of your devices can. Pair this PC checks the server first. No migration. |
| 0.5.5 | Android and Windows, and the first server download. Revoke says who had already revoked a grant, instead of "Revoked", and a confirmed Revoke is always sent. A standing grant reads "Standing, since". The server comes as an image file with its deploy kit and install guide, so you can run it without building it. The role kit upgrades its own earlier policies. No server upgrade needed. |
| 0.5.4 | Android and Windows. Grants has one "Secrets you have access to" section, and the Library offers Show and Copy only where your server would allow them. A standing grant whose review is due shows as Suspended, and suspensions show at once. Version actions show only where they'd work. Revoke says when a grant had already ended. The approval screen says where its time limit comes from. Android also gets 0.5.3's two fixes. No server upgrade needed. |
| 0.5.3 | Windows only; Android stays on 0.5.2. A request approved or denied on another device leaves the Windows inbox and says how it ended, and Windows Hello closes only once the server confirms it. A time-limited grant leaves Grants when it ends. No server upgrade needed. |
| 0.5.2 | Android and Windows only. New credentials start with their type (password, API key, SSH key and so on) and its fields. Edit on a credential's details, changing only the fields you type in. What you type survives switching apps and is cleared by a lock. Settings > Privacy has Hide values when switching apps and Allow screenshots. The apps tell your server about screenshots, recordings and copies they notice, never with the picture or the value. The server needs a database migration. |
| 0.5.1 | Requests work with a keyboard and screen readers, and on Windows Enter presses the button that has the focus, so it can't approve by mistake. Windows calls the app "Bouncer Desktop". Notifications give a request the same title as its inbox card. On Windows, Bouncer asks Windows to keep a copied value out of clipboard history and cloud sync, and clears it when it quits. A native Windows command line, not code-signed yet. |
| 0.5.0 | Redesigned approval screens that lead with the decision. Credential types with icons. When an Android phone can't use its approval key, it now says why (for example the phone is locked, or Android needs a fresh unlock) instead of always "Unlock it and try again". |
| 0.3.8 (builds 20 to 26) | Test builds, not released widely. An easier add-credential form, folders from your library, a folder tree, and names kept exactly as typed. On your own requests for resources that need another approver, the app now says "Another approver has to approve this" and offers only Deny, instead of refusing your approval with a confusing message. |
| 0.3.7 | Longer access with its end date shown. Personal credentials, shared with people and groups. |
| 0.3.6 | A simpler New request form, with a single resource picker. |
| 0.3.5 | Show value appears only where the server will show the value. Clearer wording when a save or view takes too long. |
| 0.3.4 | A fix: Show value shows the value again. |
| 0.3.3 | The credential Library. Grants of up to 7 days with short-lived tokens. Saving and editing a secret from the app. |
| 0.3.2 | Viewing a secret on a phone or PC where a resource allows it. Android pairings survive app updates. |
| 0.3.1 | SSH access with short-lived certificates. |
| 0.3.0 | The first release with every app at one version. Saving a secret through a request, Windows Hello approvals, Sign out and Switch server. |
Earlier builds (0.1 and 0.2) were internal test candidates.
Numbers such as (#263) in these notes refer to the project's private issue tracker, which isn't published. The text around each number says what changed.
Updating
- Android: install the newer APK over the old one. Your pairing stays. See Install on Android.
- Windows: an installer (MSIX) installed from its update link updates itself; otherwise install the newer MSIX over the old one. The portable ZIP never updates itself. See Install on Windows.
- The server is upgraded by its administrator. Some releases change the server too; the release notes say so.
Bouncer 0.5.7
Published as a private GitLab release, v0.5.7+34, from commit
b329764d1b909dc6cc5fbd560d018933d14ab8e0. It has 21 files, all checked
against their SHA256 hashes after upload. The source repository and release
are private. The Android internal build is on Firebase App Distribution and
iOS 0.5.7 is in internal TestFlight, both for S6 Studios' own testing.
Neither has been installed on a real device yet. Updating a client doesn't
upgrade its server, and the Bouncer project's own production server still
runs build 0.3.8+25.
Changes in the apps
- A brief "Reconnecting…" notice after unlock or resume (#285). While Bouncer reconnects, it shows this notice instead of a server-error banner. A real response error still has its own message.
- Notification settings on iPhone (#288). Settings > Notifications > Notification settings opens iOS notification settings, or the app's settings on iOS 15. If iOS cannot open it, Bouncer shows the manual path through Settings > Notifications > Bouncer.
- Clearer Library ownership and sharing. Credential details show who owns the credential and how you have access. The information shown depends on your role; it does not reveal everyone else's access.
- Android launcher and round icons. The packages include square and round PNG icons at all five standard densities, alongside the unchanged adaptive and themed monochrome artwork. The in-app credential icons, app label and package identity stay the same. Emulator checks passed; the icon still needs checking in Firebase App Distribution and App Tester after the next signed build is distributed. Install over the earlier app to keep pairing; do not uninstall for this fix.
- Which keys meet a resource's settings. Apps explain the key requirement. New Windows Hello enrolments send available TPM evidence and show the server's verification result in Settings. Existing keys gain no evidence through an update. No real PC has passed an attested enrolment yet.
Changes for command-line users and administrators
- Requester listings, JSON and key-issuance log details have a non-secret 12-hex-character key identifier to distinguish rapid key rotations.
- Resource provisioning errors explain the operator repair, with exit 7 and no immediate CLI/MCP retries. Database outages use exit 16.
- The admin log export includes token issuance, backend revoke, provisioning and CA-change records. The matching admin client preserves future kinds and fields. The compatibility and evidence limits below matter to exporters.
- The server checks resource provisioning separately and offers
bouncer-server --check-config. The role kit adds narrow metadata reads. - After it has read a CA public key once, the server can serve new SSH revocations during an OpenBao outage, including after a restart.
- The manual has new or expanded guidance on credential lifecycle, installation, audit matching, outages, SSH host delivery and restores. Each chapter's "How this was checked" note says what was tested.
Versions and build status
| Component | Version in this source | Distribution status |
|---|---|---|
| Server, Linux and Windows CLI, admin and MCP | 0.5.7 | Private GitLab release; production remains on build 0.3.8+25 |
| Android | versionName 0.5.7, versionCode 34; internal versionName 0.5.7-internal | Private GitLab release; the internal build is on Firebase App Distribution for S6 Studios' own testing; no Play submission |
| iOS | short version 0.5.7, build 34 | Internal TestFlight for S6 Studios' own testing; no App Review submission |
| Windows app | 0.5.7; beta MSIX 0.5.34.0, internal 0.5.34.1, Store 1.0.34.0 | MSIX and ZIP in the private GitLab release; no Microsoft Store submission |
The App Tester icon check, checks on real phones and PCs, and a real PC's Windows Hello TPM enrolment are still to do.
See Get Bouncer for the release files and the separate availability of earlier builds. The 0.5.6 build's files and checksums stay unchanged.
For operators
- Role kit: you can upgrade the server before the kit: it keeps issuing tokens as before, as described below. Resources whose provisioning metadata cannot be checked show
upgrade_needed, and--check-configexits 4. The P1 to P6 upgrade with this release's kit is recommended, and is required before turning on credential lifecycle. After the kit upgrade, require exit 0 before adding resources. - Rollback: restore the pre-upgrade backup; never edit the migration table. Migrations 0017 to 0019 are new. After a restore or rollback, reset each SSH host's KRL version state as the manual's "Reset host version state" section describes, after waiting the longest SSH
credential_ttlplus five minutes from the server stop. - SSH revocation lists while OpenBao is down: Bouncer now serves them from its database, including after a restart, once the CA public key has been read once. A CA rotation is logged as a warning and an
ssh_ca_changedapproval-log entry. An upgraded installation with no observed CA still needs one successful read before it can publish a list. - Audit export: a stand-alone
bouncer-adminfrom 0.5.6 or earlier stops at the firsttoken_issued,backend_revoke,resource_provisioning_changedorssh_ca_changedentry. Earlier entries, including entries on that failed page, may already have been written; the cursor file is unchanged. Use the matching CLI, resume from the saved cursor and remove repeats byid. The new CLI may reorder JSON keys. - Audit log noise: until the kit upgrade, OpenBao's audit log gets about one permission-denied entry per resource per minute from the provisioning checks.
- Health:
/v1/healthis unauthenticated and now shows counts of unprovisioned resources and checks needing a kit upgrade, without resource names. These are last-known counts, not a new synchronous probe or a list of resources. - Exit 7: with this release's CLI and MCP, exit 7 now also covers a server-side provisioning gap,
resource_not_provisioned, with an operator repair message and no immediate retries. A 0.5.6 or earlier CLI or MCP doesn't know this code: it sees an HTTP 503 server error, exits 1 and may retry. Upgrade agent hosts' CLI and MCP with the server, and update any wrapper that reads exit codes. - Android: the launcher and round icons are fixed in this release. The release keeps the same package and must use the same signer, with versionCode 34, so the in-place update preserves existing pairing. The icon resources do not change pairing storage. Signed in-place update verification is still a release-build check. The 0.5.6 build's files and checksum pins must not be replaced.
- Attestation limit (#282):
android_attestation: requiredapplies only to devices that declare Android; it is not a requirement for verified hardware evidence on every platform. The limit also affects existing servers that setpairing.allow_user_verified_keys: true. See Known limits below. No policy change is included here.
Upgrading the server first keeps an older kit working, but the older kit hasn't passed the new checks. The server retains earlier issuance checks when metadata permissions or an exact older policy format prevent full inspection; create capability and token vetting still apply. A metadata 403 with a live login means upgrade_needed, not a proven missing object. A definite missing or unsuitable role or policy is a per-resource refusal. A seal, unreachable OpenBao or failed login remains a backend outage. Lifecycle stays off by default, and a kit from before 0.5.3 (policy format 1) must be upgraded before lifecycle is turned on.
Token records are admin-export-only and contain non-secret accessors, never token values or stored secrets. Feed the full accessor to sys/audit-hash for the same OpenBao audit device to obtain its matching HMAC. Records are not a complete account of every external call: a failed database commit can follow a backend call, older records are not backfilled, and missing or uncertain issuance evidence does not prove that a token was released.
require_hardware_key is off by default. It accepts a per-use hardware key without requiring the check itself to be biometric; require_hardware_uv retains its biometric requirement, and both must pass if both are set. Replacing the biometric setting with the hardware-key setting is a named policy loosening, not an automatic upgrade step. Read #282 below before treating a platform label as verified hardware evidence.
Upgrade order
- Save the pre-upgrade database backup and matching config and release files. Prepare matching CLI/admin binaries and pause any scheduled export that still runs an older stand-alone admin client.
- Upgrade the role kit first. Use this release's kit for the P1 to P6 procedure, preserving the existing
resources,kit.envand SSH resource settings. Review the dry run, apply the kit, and complete its checks and verification. If P1 to P6 used the 0.5.6 kit already, run the new kit's dry run again: it adds the provisioning reads tobouncer-server. Investigate unrelated policy drift. - Run the candidate server's
--check-confignext, as its service user with the intended config and OpenBao settings. Require exit 0 before adding resources or proceeding with the new setup. The preflight does not open the database, migrate it, apply the config or start listeners; its AppRole login can create an expiring server-session token, never a resource credential. Exit 1 means global setup/login failure, 2 usage, 3 a definite resource gap, and 4 an upgrade-needed or transient check. A definite gap takes precedence over an incomplete check. - Upgrade the server after the successful check. It applies the new migrations at startup. Verify health and the resource counts, and confirm an intended request and revoke. If PostgreSQL becomes unavailable while the server runs, it answers 503
database_unavailablewithRetry-Afterand recovers without a restart; CLI/MCP use outage exit 16. A resource provisioning gap can leave health 200 while that resource is refused. - Resume exporters with the matching
bouncer-admin, then update CLI/MCP and apps. Upgrade the server before apps that send the new enrolment fields. A config that setsrequire_hardware_keyrequires the new server; 0.5.6 or earlier refuses that setting. Existing Windows Hello keys do not acquire TPM evidence by upgrade; verified evidence can be attached only during a new enrolment.
| Migration | What it adds |
|---|---|
0017_token_audit.sql | Token audit metadata for issuance and backend revoke export records. |
0018_event_resource.sql | The resource association for provisioning events. |
0019_ssh_ca_keys.sql | Retained CA public keys, sequenced observations and per-issuance CA identity for durable KRL delivery. |
Rollback and SSH host recovery
Use the matching pre-upgrade backup, config and older image. An older server cannot simply use the migrated database. Never remove migration records or change their checksums to make it start. A restore also returns device, requester, grant, key and lifecycle state to the backup, so keep outside access closed and reconcile changes made since the backup using the restore runbook.
For SSH, wait until the longest credential_ttl used by the SSH host resources, plus five minutes, has elapsed since stopping the server for the restore or rollback. The restored database cannot revoke certificates for grants it never recorded. Confirm the intended restored publisher, reconcile revokes and keep independent recovery access. Then reset each destination's version state deliberately. Follow the five-step Reset host version state procedure on each destination host. Stop its timer and service, then remove only its version file. Keep the installed KRL, trusted CA and last_ok; use the configured state directory if it differs from the default. If outside access is still closed, defer the fetch until it is reopened. Start a manual service fetch, inspect its successful log and version, and only then resume the timer.
If the fetch fails, keep the timer stopped, fix the cause and check freshness with bouncer-krl-pull --check using the service's state-directory and age settings. A successful fetch alone does not repair missing revoke history; keep affected principals removed until expiry if that history cannot be reconstructed. Never clear state merely to silence an unexplained older-version error. Follow the full restore procedure. Nobody has yet run a 0.5.7 rollback end to end.
Known limits
- #282 remains open. Bouncer can't verify every device's description of its own key:
android_attestation: requiredapplies only to devices that declare Android, andrequire_hardware_uvandrequire_hardware_keycan't by themselves prove hardware on every platform. This affects existing servers and earlier versions too, whereverpairing.allow_user_verified_keysistrue. Until it's fixed, give pairing codes only to the intended person, and review which resources rely on those two settings. This release changes no enforcement or approval eligibility for this limit. - #283 remains open. Restoring or rolling back the database can move the publisher's KRL revision below the revision hosts hold. Automatic continuity is not implemented; the deliberate, reconciled host reset above is still required. Using the clock to keep revisions moving forward would not be enough on its own, because the clock can be set back and an older binary would not know the rule.
- #284 is postponed. This release has no gateway, session recording or gateway-enforced session cutoff.
- Open sessions stay open (D29). An expired certificate can't start a new login, and a revoked one can't once the host has fetched a list that includes the revoke. Neither ends an SSH session that is already open. Until a host fetches the new list, a previously issued certificate can still log in until it expires. With the stale policy
keep, the host keeps its last list, reportsSTALEand exits 2 after the configured age, rather than locking everyone out. A host that has never fetched a list refuses every certificate login until its first successful fetch. - #287 remains open. After a push service outage recovers, a phone can receive a burst of notifications that are no longer current, such as closures for requests that were already handled. Open Bouncer to see which requests still need a decision.
- #289 remains open. On Android, a notification can stay on the phone after its request was handled or dismissed on another device. Open the request in Bouncer and check its current state before acting on it.
- CA and TPM evidence have limits. An old CA never observed by Bouncer cannot be reconstructed, and certificates issued before the upgrade are matched to the first CA Bouncer reads after it; upgrade and let that read succeed before rotating. Observed CAs are retained without pruning. Windows TPM verification is covered by automated tests. No real PC has completed an attested enrolment yet.
Bouncer 0.5.6
Version 0.5.6 was built and tested, but has no GitLab release (checked on
17 November 2026). Builds exist for Android, Windows, the command
line and the server. They weren't published or rolled out to
production. Both apps show 0.5.6+33 under Settings > About. On
Android the version code is 33. On Windows, the portable ZIP and the
test-signed installer (package version 0.5.33.0) are the build.
There's no iPhone or Mac build of 0.5.6.
For administrators: the server stays up while OpenBao isn't ready
A server from this release behaves differently when OpenBao is sealed.
Before, the server exited and restarted in a loop, and everyone saw "502".
Now it stays up and answers 503 with backend_sealed,
backend_unreachable or backend_auth_failed, /v1/health included, until
OpenBao is ready. It issues nothing meanwhile, but still accepts revokes and
cancels. It notices by itself once OpenBao is unsealed. Unsealing is still
yours to do.
- A monitor on
/v1/healthsees 503 with one of those codes, not 502. - The container shows unhealthy meanwhile, and Docker doesn't restart it.
BOUNCER_WAIT_FOR_OPENBAOis now ignored. Remove it from.env.- The
bouncercommand line exits 12 to 15 for these outages, where it used to exit 1.
When Bouncer is unavailable explains each message and who acts.
Fixed in this build
The apps say why Bouncer is unavailable
When the server can't serve, the apps say so by name, for example "Your Bouncer server's vault is sealed", and that there's nothing to fix on your device. See Troubleshooting.
Why a device can't approve, and which one can
Where a request needs a key kept in secure hardware that asks for your fingerprint or face, Windows says so, names your devices that have such a key, and offers only Deny. A phone whose key doesn't qualify shows the same notice, with Approve turned off. See Answer requests.
Pair this PC checks the server first
On Windows, Bouncer checks the server's address, certificate and API before it sends the pairing code, and Details shows the certificate. The setup and offline messages no longer assume Tailscale. See Pair the app with your server.
The server download
The server's files come with their own sums file,
bouncer-server-0.5.6+33-SHA256SUMS, so you can check them without the rest
of the release. See Get Bouncer.
Upgrading
- Android: the update installs over the earlier internal builds and keeps your pairing.
- Windows portable: unzip 0.5.6 into a new folder next to the old one, and keep the old folder to go back to. Your pairing carries over.
- Windows installer: installs over 0.5.32.0 and keeps your pairing.
- Server: no migration. The app fixes don't need a server upgrade.
Known issues
- Automatic unsealing isn't live yet. After a reboot, OpenBao still has to be unsealed by hand.
- A Windows Hello key can't meet a secure-hardware policy yet. Checking the PC's security chip (TPM attestation) is not in this release. From the private 0.5.7 release, the server checks a TPM attestation at enrolment when Windows supplies one, but no real PC has passed that check yet, and keys enrolled before it stay unchecked.
- Windows Hello closing by itself when a request is decided elsewhere has been tested only with automated tests, not with a real Windows Hello PIN.
What was checked, and on what
-
Automated tests for every fix, before this build was made.
-
Pre-release checks passed for the Windows MSIX, portable app and CLI on a test machine, the Linux CLI, and the server download against a throwaway OpenBao with fake data. These checks don't include the signed Android build. It needs its own check, because a check of an unsigned build doesn't cover it.
-
As checked on 17 November 2026, the Bouncer project's own production server runs build
0.3.8+25. These source changes are not deployed there. -
On 18 November 2026, the 0.5.6 internal Android build was on Firebase for S6 Studios' own testing only. See Platforms and status.
Bouncer 0.5.5
For Android and Windows, with two Grants fixes, and the first
release with a server download. Both apps show 0.5.5+32 under
Settings > About. On Android the version code is 32. On Windows, the
portable ZIP and the test-signed installer (package version 0.5.32.0) are
the build. It's a private release. Platforms and status
has the current test channels.
There's no iPhone or Mac build of 0.5.5. The command line is rebuilt at 0.5.5 with no changes of its own.
Fixed in this build
Revoke says who revoked
If someone else had already revoked a grant before your app heard, Revoke used to say "Revoked" anyway. Now it says who did it and when, for example "Already revoked by Sam on Sam's iPhone at 14:02. Nothing more to revoke." The access was gone either way; only the message was wrong.
A Revoke you confirm is now always sent, even if another grant above it disappeared from the list while the dialog was open (#270).
"Standing, since"
A grant with no end now reads Standing, since its start date on its card, as the section and History call it. Always stays the name you choose when you approve.
New: the server as a download
The release has the server image as a file, the deploy kit, and an install guide, so you can run your own Bouncer server without the source or a build. Get Bouncer lists the files, and Install the server covers both ways.
For administrators
The OpenBao role kit now recognises the policies an earlier kit wrote, and upgrades them without an extra flag. The emergency stop works on an upgraded install. See Upgrades.
Upgrading
- Android: the private-release APK installs over a 0.5.4 or 0.5.2 APK and keeps your pairing. It can't update the 0.5.4 copy from Google Play's internal track, which has a different signing key. Read Update before uninstalling anything.
- Windows portable: unzip 0.5.5 into a new folder next to the old one, and keep the old folder to go back to. Your pairing carries over.
- Windows installer: installs over 0.5.29.0, 0.5.30.0 or 0.5.31.0 and keeps your pairing.
- Server: no upgrade needed for these fixes.
Known issues
-
The server's
INSTALL-SERVER.mdsayssha256sum -c SHA256SUMS, but that file lists every release file. If you downloaded only the server files, runsha256sum -c SHA256SUMS --ignore-missinginstead. Every downloaded file must sayOK(Get Bouncer). -
Windows Hello closing by itself when a request is decided elsewhere has been tested only with automated tests, not with a real Windows Hello PIN.
-
A review falling due (#267) has been tested only with automated tests: a review period can't be shorter than a day.
-
Version history is off unless your administrator turns it on.
What was checked, and on what
As recorded when this build was made:
- Automated tests for every fix, before this build was made.
- The check of the installed 0.5.5 build on a Windows test machine with test data, of the server download in a throwaway test box, and of the signed Android build on an emulator, come next.
- Not yet accepted by S6 Studios, and not yet in daily use.
Bouncer 0.5.4
For Android and Windows, with fixes to Grants and requests. Both
apps show 0.5.4+31 under Settings > About. On Android the version code
is 31. On Windows, the portable ZIP and the test-signed installer (package
version 0.5.31.0) are the build. 0.5.4 is a private GitLab release, and
Google Play's internal testing track has it too, signed by Play, for
S6 Studios' own testing. See Platforms and status.
iPhone builds of 0.5.4 went to internal TestFlight for S6 Studios' own testing. There's no Mac build of 0.5.4, and no new command line.
Fixed in this build
One list of what you can use
Grants has one section, Secrets you have access to, in place of the two lists for viewing and saving. Each credential has one row, which says whether you may view it, save into it, or both. The Library no longer offers Show value or Copy value on a device your server wouldn't show it to, and says why (#265).
A standing grant whose review is due
A grant approved for Always is suspended when its review date passes, unless an administrator confirms it again. The app now shows it as Suspended at that date, without Revoke. Before, it could still look active until something else refreshed the screen. Your server had already suspended it; only the screen was out of date (#267).
Version actions only where they'd work
On a credential with version history turned on, Replace, Expire now, Schedule and Clear now show only on a device your server accepts them from (#268).
Suspensions show at once, and Revoke says what happened
When your server suspends a standing grant, for example after a policy change, the app now updates straight away. If you tap Revoke on a grant that was already suspended or had already ended, the app says so, instead of "Revoked" (#269).
On Android: the inbox and Grants follow your server
These two came to Windows in 0.5.3:
- A request approved or denied on another device, or cancelled, leaves the inbox within about 10 seconds while the app is open. An approval card that's open says who decided (#263).
- A time-limited grant leaves Time-limited in Grants when it ends, and History shows when it expired (#264).
Where the time limit comes from
When you approve a request, the duration choice now says how long this credential can be approved for, and that your Bouncer administrator sets that in the server's settings. Windows shows it in the request's details, and the Library under Longest access. Nothing about what can be approved has changed. Administrators: see Resources and policy.
Upgrading
- Android: the private-release APK installs over a 0.5.2 APK and keeps your pairing. Google Play's internal-testing copy has a different signing key, so neither can update the other. Read Update before uninstalling anything.
- Windows portable: unzip 0.5.4 into a new folder next to the old one, and keep the old folder to go back to. Your pairing carries over.
- Windows installer: installs over 0.5.29.0 or 0.5.30.0 and keeps your pairing.
- Server: no upgrade needed for these fixes.
Known issues
- Windows Hello closing by itself when a request is decided elsewhere has been tested only with automated tests, not with a real Windows Hello PIN.
- A review falling due (#267) has been tested only with automated tests: a review period can't be shorter than a day.
- If someone else revoked a grant just before you, Revoke can still say "Revoked". The access is gone either way (#270, open).
- Version history is off unless your administrator turns it on.
What was checked, and on what
As recorded when this build was made:
- Automated tests for every fix, before this build was made.
- The check of the installed 0.5.4 build on a Windows test machine with test data, and of the signed Android build on an emulator, come next.
- Not yet accepted by S6 Studios, and not yet in daily use.
Bouncer 0.5.3
For Windows only, with two fixes for daily use. The portable ZIP and
the test-signed installer (package version 0.5.30.0) show 0.5.3+30 under
Settings > About. There was no GitLab release of 0.5.3.
Platforms and status says what you can install today.
Android stays on 0.5.2: there's no Android, iPhone or Mac build of 0.5.3, and no new command line.
Fixed in this build
A request decided on another device leaves the inbox
When you approve or deny a request on your phone, or the requester cancels it, the Windows app now notices within about 10 seconds, or as soon as you bring its window back. The request leaves the inbox and the tray count, and its pane says how it ended, such as Already approved, by whom, on which device and when. Before, it could stay there as waiting, with its countdown and Deny, until its time ran out (#263).
If Windows Hello is open for that request, Bouncer checks with your server first, then closes the prompt and tells you nothing was signed on this PC.
An ended grant leaves Grants on time
A time-limited grant now leaves Time-limited in Grants when it ends, and History shows when it expired. Before, it could stay with "0 min left" and Revoke long after your server had ended it (#264). The server had already recorded it as expired; only the screen was out of date.
For administrators
- These fixes don't need a server upgrade. They work with a 0.3.8 or 0.5.2 server.
- A server built from this release applies a new database migration (0015) when it starts. It adds one table for credential version history, which is off unless you turn it on (see Credential expiry, replacement and history). Back up the database first. To roll back to 0.5.2, restore that backup.
Known issues
- Windows Hello closing by itself when a request is decided elsewhere has been tested only with automated tests, not with a real Windows Hello PIN.
- A standing grant whose review falls due isn't changed by this fix (#267, open).
- "Secrets you have access to" (#265) comes in the next build.
What was checked, and on what
- Automated tests, and a Windows test machine with test data, before this build was made.
- The check of the installed 0.5.3 build (the upgrade from 0.5.2 keeping the pairing, both fixes, and going back to 0.5.2) comes next, on the same test machine.
- Not yet accepted by S6 Studios on a real PC, and not yet in daily use.
Bouncer 0.5.2
For Android and Windows. Both apps show 0.5.2+29 under Settings >
About. On Android the version code is 29. On Windows, the test-signed
installer is package version 0.5.29.0. The Windows command line is still a
zip that isn't code-signed. There was no GitLab release of 0.5.2.
Platforms and status says what you can install today.
There's no iPhone or Mac build of 0.5.2.
The server changes in this release: it adds a database migration (0014) that holds the screenshot, recording and copy records described below. Your administrator upgrades the server; the new server applies the migration when it starts. The 0.5.2 apps also work with a 0.5.0 or 0.5.1 server, but then they send no records.
What's new for app users
Choose the type first
New credential starts by asking what you're adding, such as a Password, an API key or an SSH private key, and sets up the usual fields for it. Secrets are hidden as you type, each with its own Show button, and pasted keys keep their line breaks. You can change the type later in the form without losing what you typed. See Credentials and copying.
Edit a credential
A credential's Details screen has an Edit button wherever you're allowed to save new values from this device. Type only the fields you want to change: a field you leave empty keeps its current value. If you may also view the credential, Load current values fills the form, which is recorded as a view. On Windows, Edit needs Windows Hello approvals. See Edit a credential's values.
Switching apps keeps what you typed
On Android and Windows, what you've typed into a new or edited credential stays when you switch to another app or minimise Bouncer. It's kept in memory only, and cleared when your device locks, when you sign out, or when you discard the form. On iPhone it's still cleared whenever Bouncer goes to the background. See If you switch apps while typing.
Privacy settings
Settings has a Privacy group:
- Hide values when switching apps (on by default) hides again any value you chose to show when you switch away.
- Allow screenshots (Android and Windows, off by default) lets the screens that show values be captured. A screenshot of a value contains the value, so turn it on only when you need it.
See Privacy settings.
Screenshots, recordings and copies are recorded
While a screen that shows a secret, or a form where you're typing one, is open, the app tells your organisation's server when it notices a screenshot (Android 14 and later), a screen recording (Android 15 and later), or a copy of a value you're viewing (Android and Windows). The iPhone app will report these in a later build. They show in History marked "Reported by the device". The record never includes the picture, the value or what you typed, and goes only to your organisation's server. Windows can't tell an app about screenshots or recordings, so on Windows Bouncer records copies, and any time Windows couldn't keep its window out of screen capture. See the privacy policy.
For administrators
- Migration 0014 adds three empty columns and an index to the approval log. Back up the database before upgrading.
- To roll back, restore that backup, as
Upgrades describes. Don't rely on the rollback statements at the end of the
migration file: an older server can't read the new History entries, so
after those statements alone, any History page or log export that
includes one fails. If you do roll back that way, also delete the
reported_*rows from the approval log before starting the older server. - No config changes.
- The command line and MCP server don't change, apart from the version.
Known issues
- The Windows command line isn't code-signed. Check the zip against
SHA256SUMS; the installer does this for you. - "Always" and "Always approved" are still experimental, as described in the 0.5.0 notes.
What was checked, and on what
- The changes were tested with automated tests, on an Android emulator and on a Windows test machine.
- The release check of the installed 0.5.2 apps hasn't passed yet. It comes next, on the emulator and the test machine.
- Not yet checked on real phones and PCs, and not yet in daily use. The Android screenshot notice was seen on an Android 16 emulator only.
Bouncer 0.5.1
Every app shows 0.5.1+28 under Settings > About. On Android the
version code is 28. On Windows, the test-signed installer is package version
0.5.28.0. The new Windows command line comes as a zip that isn't code-signed
yet. There was no GitLab release of 0.5.1.
The server doesn't change in this release: no new database migrations and no config changes. The 0.5.1 apps work with a 0.5.0 server, so upgrading the server is optional.
What's new for app users
Approving with a keyboard or a screen reader
- A request reads as parts. TalkBack and Narrator read the headline as a heading, then the reason, each of the three rows, what approving does, the save window and the Deny tip on their own. More information is its own button again, and says whether it's open.
- Enter is safe on Windows. Enter presses the button that has the keyboard focus: Deny denies, Approve approves. Enter approves from the window only when nothing in it has the focus, and the footer says so. If you cancel a Windows Hello prompt, the focus goes back to the button that started it. A new request that replaces the one on screen takes the focus itself, so Enter can't approve it by accident. Esc still denies.
- Tab order and focus rings on Windows. Tab goes through the side rail, then the pane: in the inbox, from the list to More information and then the request's buttons. A screen reader can now find Settings in the rail and reads its name. Focus rings show where the keyboard is.
Windows: the app is called "Bouncer Desktop"
The window title, the Start menu, notifications, the tray, Settings > About and the install guides now say Bouncer Desktop. It's the same app: upgrading keeps your pairing and your Windows Hello passkey.
Notifications name the request
Android and Windows notifications now give a request the same title as its inbox card, such as "Read Staging demo key", and the next line says who is asking and when to answer by.
- On Android, the line after that says what access is asked for, such as "Access for 15 minutes" or "One-time save of 1 field", so the time to answer isn't confused with how long access lasts. The notification no longer shows the reported host; it's under More information on the request.
- On Windows, the line after that says where you can answer: in Bouncer Desktop with Windows Hello, on another paired device, or, for your own request that needs someone else, that another approver has to approve it.
The lock-screen text and the Approve and Deny actions don't change.
Windows: a copied value stays private
When you copy a value in Bouncer Desktop, Windows is asked to keep it out of clipboard history (Win+V) and cloud clipboard sync. If Windows won't take the copy that way, nothing is copied and Bouncer says so. Bouncer clears the copy after 30 seconds, and also when it quits or you sign out of Windows, but not after a crash or a forced close. See Credentials and copying.
Clearer text about approving
Android Settings, and Windows without Windows Hello approvals, now say plainly who can approve today, without promising features in a later update. Where a PC can't approve, it says a PC can approve only with Windows Hello, and only if your server accepts it.
For requesters: the Windows command line
bouncer and bouncer-mcp now run natively on x86_64 Windows, from a zip
with a per-user installer. Your key file is saved for your Windows account
only and sealed with DPAPI. exec --stdin works on Windows; exec --file
and self-update stay Linux only. See Install the
CLI.
Known issues
- The Windows command line isn't code-signed. Check the zip against
SHA256SUMS; the installer does this for you. - "Always" and "Always approved" are still experimental, as described in the 0.5.0 notes.
What was checked, and on what
- The changes were tested with automated tests, on an Android emulator, on a Windows test machine and on Apple's iPhone simulator.
- Not yet checked on real phones and PCs: a real Windows Hello prompt cancelled and then Enter pressed, TalkBack and Narrator actually reading the new screens, and whether Windows keeps a copy out of cloud clipboard sync (on the test machine, it stayed out of clipboard history).
Bouncer 0.5.0
Every app shows 0.5.0+27 under Settings > About. On Android the version
code is 27. On Windows, the test-signed installer is package version
0.5.27.0. There was no GitLab release of 0.5.0. The first 0.5 release
published on GitLab is 0.5.4.
This release changes the server as well as the apps. The apps still work with a 0.3.8 server; they just don't show credential types until the server is upgraded.
For administrators
- Migration 0013 adds an optional credential type to personal credentials. The server applies it at start-up. Back up before upgrading.
- Upgrade the server before adding
credential_typetobouncer.yaml. Servers older than 0.5.0 refuse it: reload is refused and restart fails. - To roll back, remove
credential_typefrom the config, then restore your backup (Upgrades).
What's new for app users
Requests lead with the decision
A request now opens with who wants to do what to which credential, then the requester's reason (marked as not checked by Bouncer), then three short rows: who is asking, the requesting app exactly as the requester reported it, and the credential with a Read or Save · N fields label. One sentence says what approving does, and the time left to answer is shown apart from how long access would last.
- A read says how long access lasts. A save says it allows one update of N fields, that the saved changes stay after the sending window, and that it doesn't give read access.
- The clock counts down to the deadline for answering. With reduced motion turned on in your system settings it doesn't move, and it never flashes. Screen readers hear the time left by the minute, then at 30 and 10 seconds. Once time runs out, nothing can be approved or denied.
- More information, closed at first, holds the host, network address, app, key and field details.
- Inbox cards lead with a short title, such as "Save new values to Demo API key", and say "N left to answer".
- On Windows, the request pane says what approving gives, in the same words as the phone, and the footer reads "Approving signs with Windows Hello on this PC, and so does denying."
Credential types
A credential can say what kind it is (API key, password, certificate, SSH private key and so on), and the apps show a matching icon. The type only changes the icon; it doesn't change who can use the credential. The owner of a personal credential can choose its type in the app once the server supports it.
Clearer messages when an Android phone won't approve or deny
Before, the app said "Unlock it and try again" for every problem. Now it says which one it is: the check was cancelled, the phone is locked, there were too many attempts, the key needs pairing again, or Android needs a fresh unlock.
On Android 12 to 14, a phone unlocked by face (on many phones) or by Smart Lock doesn't count as unlocked for Bouncer's approval key. Lock the phone and unlock it with your PIN, pattern, password or fingerprint, then try again. The app now explains this as "Android needs a fresh unlock".
iPhone
When a request is decided, expires or is cancelled, the server now sends iPhones a silent update instead of a second alert. (The iPhone app wasn't released then.)
Windows fixes
- The install guide no longer says uninstalling removes the pairing. Sign out before you uninstall.
- Pairing again clears a confirmed "removed" notice.
- After you answer No to Windows' passkeys question, the message names both the passkeys setting and the Windows Hello PIN.
Known issues
- "Always" and "Always approved" are experimental, and their policy is not decided. Personal Always approved is off unless an administrator allows it. It has two open problems: a person's command-line key can get the value with no device, and the kill switch does not stop new Always approved uses. Default durations include Always unless disabled. Administrators: keep both off with
durations.always: falseandceilings.always_approved: false(Approvals and access duration). In the apps choose a time limit and Approval required. Check any standing grants with your administrator. - Some Android phones need a fresh unlock before they approve, as described above.
What was checked, and on what
- The new screens: automated widget and screenshot tests (phones at two widths, large text, light and dark, and the Windows pane), and the release checks of the installed test build on an Android emulator and a Windows test machine.
- Not yet checked on real phones and PCs: real fingerprint and Windows Hello prompts, TalkBack and Narrator reading the clock, and the system reduced-motion setting.
- The iPhone silent update: the server's tests only. No push had reached a real iPhone when this build was made.
Frequently asked questions
About Bouncer
What is Bouncer?
An approval system for access to secrets. A person, script or AI agent asks your organisation's Bouncer server for a secret, an API key or SSH access. An approver gets the request in the Bouncer app and approves it for a length of time, or denies it. The secrets are kept in OpenBao, not in Bouncer.
How do I get the apps?
Ask your organisation's Bouncer administrator. The Android and Windows apps come from Bouncer's private GitLab release: an APK for Android, or an installer or ZIP for Windows. S6 Studios also has internal test builds on Google Play's internal track and Firebase App Distribution for its own testing. There's no store listing. Get Bouncer says what's in the release.
Then follow Install on Android or Install on Windows, and pair the app with the pairing code your administrator gives you.
Is there an iPhone or Mac app?
Not yet. The iPhone app is in internal testing at S6 Studios, through Apple's TestFlight. A Mac app is in development. Until then, approve on an Android phone or a Windows PC. See iPhone and Mac.
Does S6 Studios see my requests or secrets?
No. S6 Studios makes Bouncer, but your organisation runs its own Bouncer server, and requests, decisions and secrets stay between your devices and that server. On Android, notifications go through Google's Firebase Cloud Messaging, and they carry only random IDs, never the request's details or a secret. On Android, the QR code scanner uses Google's ML Kit, which reads the code on the phone. No camera image leaves the phone, but ML Kit sends Google technical information such as the device model and app version. You can type or paste the pairing code instead. The privacy policy has the details. It's still a draft for owner and legal review.
Approving
How long do I have to answer a request?
As long as your server lets requests wait: 15 minutes by default. The request shows the time left. If nobody answers in time, the request expires and nothing is granted. See Approvals and access duration.
Is the time to answer the same as how long access lasts?
No. The time to answer is how long the request waits. How long access lasts is what you choose when you approve, and it can be shorter or longer than the requester asked for, within the resource's limits.
I approved something by mistake. What do I do?
Open Grants, find the grant and tap Revoke. New reads stop at once. A value that was already read can't be recalled, so if in doubt, change the secret where it's used.
What happens to access when it ends?
Bouncer stops issuing tokens and revokes the ones it issued, so new reads stop. Copies the requester already made, and sessions it already opened (such as a database connection), aren't affected. Bouncer can't recall a secret that has been read.
Can I approve my own requests?
Only if the resource's policy allows it. If it doesn't, the request says "Another approver has to approve this", and you can only deny it.
What does "I don't recognise this" do?
It denies the request and marks it as not recognised in the approval log. Use it when you didn't expect the request at all. The app then shows the commands your administrator can use to revoke that requester's key or end every grant at once.
Can I approve from the notification?
On Android, yes, if you turn on Approve from notifications in Settings and the resource allows it. It approves for the requested duration only. To choose another duration, open the request. Windows notifications only open the request.
What is "Always"?
Standing access with no end time. Your server may offer it: it's in the default list unless your administrator turns it off. Always is experimental and may change or be removed, so choose a time limit instead. If you see standing grants, check them with your administrator. See Standing access.
Devices
What do I do if my phone is lost or stolen?
Tell your administrator straight away. They revoke the device on the server, and it can't approve anything after that. Then pair a replacement.
What do I do when I get a new phone?
Pair the new phone first, then sign out on the old one (Settings, then Sign out). Signing out asks the server to revoke the old phone.
Why don't I get requests on Windows when Bouncer is closed?
The Windows app has no push service. It asks the server for new requests while it's running, in its window or in the notification area (the tray). Quit it, and requests wait until you open it again. They also reach your other paired devices.
Will I lose what I typed if I switch apps?
Not on Android or Windows, from 0.5.2. A credential you're making or editing keeps what you've typed while you switch to another app or minimise Bouncer. By default (Settings > Privacy), values you chose to show are hidden again. Locking your device, signing out or discarding the form clears it. On iPhone it's still cleared whenever Bouncer goes to the background. See If you switch apps while typing.
How do I edit a credential?
Open it in the Library and tap Edit. You only see Edit where you're allowed to save new values from that device. Fields you leave empty keep their current value. See Edit a credential's values.
Do I need a VPN, such as Tailscale?
Not for Bouncer itself. The app needs a network connection that reaches your organisation's Bouncer server, whatever that network is. Some organisations put the server on a VPN; if yours does, connect it first. If the app says it can't reach your server, check the address and your network connection.
Running and integrating
Does the Bouncer server store our secrets?
Not at rest. OpenBao stores the values, and Bouncer's database holds metadata and access records. But the running server handles values in memory when a device views or saves a secret, and when someone creates a personal credential, and its OpenBao role can read paths enabled for viewing and personal credential namespaces. See How Bouncer protects access.
Can an AI agent approve its own request?
No. Agents use a requester key, and a requester key can never approve. Only a signature from a person's paired phone or PC approves. The MCP server has no tool that approves anything. See Connect an AI agent through MCP.
If I revoke a grant, is the secret safe again?
Not if it was already read. A revoke stops new token issuance at once and asks OpenBao to revoke the grant's existing tokens; check the result for failures. The kill switch ends every grant and asks OpenBao to revoke every token Bouncer issued. Check its report for any revoke it couldn't confirm. A copied value keeps working until you change it at its source. See Copied secrets and revocation limits.
How do I get a secret into a program without it showing up in ps or my shell history?
Use bouncer exec with --env, --file or --stdin. The value goes
straight to the command, rather than into its arguments. Check the command's output with fake data first; see
Patterns for workloads and agents.
Does Bouncer support single sign-on?
Not in this version. People are listed in the server's config file, and each person proves who they are by holding a device paired as them. See Known limits.
Does Bouncer need to be on the internet?
No, and it shouldn't be. Put it on a network only your people and machines reach (a LAN, or a VPN such as Tailscale), with HTTPS in front. Phones and requesters reach it over that network. See TLS and networking.
What happens if the Bouncer server goes down?
Nobody can get new access until it's back. Tokens already issued keep working for the few minutes they last. Revocations recorded before the outage are retried when it returns. See Health checks.
Can I run Bouncer with more than one server for high availability?
Not in this version. It's a single server with one PostgreSQL database. Back it up regularly (Backup and restore).
What if someone loses their phone?
Revoke the device with bouncer-admin device revoke, then decide about the
grants it approved. See Recovery.
Is there a Windows or macOS command-line client?
Yes for Windows: from 0.5.1, bouncer and bouncer-mcp run natively on
x86_64 Windows, from a zip that isn't code-signed yet. There's no macOS
CLI. See Install the CLI.
Glossary
The words these pages and the Bouncer apps use. The first part has the words you'll meet in the apps. The second part has the terms that matter mostly to the people who run the server or connect scripts to it. Each part is in alphabetical order.
Words in the app
Access duration
How long access lasts after a request is approved. The approver chooses it. It's separate from the time to answer. See Approvals and access duration.
Administrator
The person who runs your organisation's Bouncer server. They add people and
requesters, decide which resources exist and who may approve them, make
pairing codes, and revoke devices. They use the bouncer-admin tool on the
server itself. This isn't the same as having administrator rights on a
Windows PC.
APK and sideloading
An APK is an Android app file. Sideloading means installing an APK yourself, instead of from Google Play. Bouncer's Android app has no public Google Play listing, so you sideload it. See Install on Android.
Approval key
A key your device makes when you pair it, and keeps to itself. The app signs each approval and denial with it, so the server can check that the decision came from your paired device and matches the request you saw. How it's protected depends on the device:
- Android: kept in the phone's Keystore (in its secure hardware), and usable only while the phone is unlocked. If you chose it when pairing, each use also needs your fingerprint.
- iPhone: kept in the Secure Enclave, and each use needs Face ID or Touch ID.
- Windows: a Windows Hello passkey, used after your PIN, face or fingerprint. From 0.5.7, the server checks a TPM attestation at enrolment when Windows supplies one, but no real PC has passed that check yet, and keys enrolled before it stay unchecked (Device keys).
Approval log
Bouncer's own record of what happened: who asked for what, who approved,
denied or revoked it, what was issued, and what changed in the config. It's
kept in the server's database, never holds a secret value, and an
administrator can export it with bouncer-admin log export. The apps show
the part that concerns you, under Grants, then History.
Approver
A person allowed to approve or deny requests for a resource. The server's configuration says who the approvers are for each resource.
Device
A phone or PC paired with a Bouncer server. Each device has its own approval key and its own ID. An administrator can list and revoke devices; you can remove your own by signing out.
FCM
Firebase Cloud Messaging, Google's push service. Bouncer uses it to wake Android phones (and, through Apple's push service, iPhones) when a request arrives. Each push carries only a random ID; the app then fetches the details from your organisation's server.
Grant
The access that an approval gives: one requester, one resource, one action, until an end time. Grants are listed under Grants in the app, where you can revoke one early.
Human requester
The requester that belongs to a person. The server makes one for each person in its configuration. Requests you make in the app come from it, and so do requests from the command line once your administrator gives you its key. Scripts, agents and hosts have their own requesters.
Key attestation
Proof from a phone's own hardware about its approval key: where the key is kept, and what the phone needs before the key can be used. An Android phone can give this proof, signed by its hardware and traceable back to Google. When a phone sends it, Bouncer checks it when you pair (unless the administrator has turned the check off), so it doesn't just take the phone's word for it. A server can also be set to require it. Then it won't pair an Android phone that says its key is in hardware unless the proof checks out. iPhones have no server-verified key attestation. From 0.5.7, the server checks a TPM attestation at enrolment when Windows supplies one, but no real PC has passed that check yet, and keys enrolled before it stay unchecked. Attestations signed with RS1 (RSA with SHA-1) are refused.
OpenBao
OpenBao is an open-source fork of HashiCorp Vault, managed by the Linux Foundation. Bouncer keeps secrets in OpenBao and asks it for short-lived tokens when a request is approved. Bouncer doesn't replace OpenBao, and it doesn't keep secret values in its own database. See openbao.org.
Pairing
Connecting an app to a Bouncer server. Your administrator makes a one-time pairing code; you scan it or paste it into the app. Pairing registers the device and its approval key with the server. See Pair the app with your server.
Pairing string
The pairing code and server address as one line of text, starting
bouncer-pair:, for pasting into the app instead of scanning the QR code.
Your administrator sees it under "Or copy this pairing string" when they run
bouncer-admin device pair, and sends it to you privately.
Personal credential
A credential that a person creates in the app and owns, rather than one the administrator set up in the server's configuration. The owner chooses who it is shared with. Your server needs to be set up for these.
Requester
Whatever asks for access: a person, a script or host, or an AI agent. Each requester has its own requester key, issued by Bouncer. The app shows what kind of requester it is.
Requester key
The secret a requester uses to ask Bouncer for access and to
use what's approved. Bouncer issues it; it starts with brk_. Keep it like a
password. It lets the holder ask, but never approve.
Resource
Something people can ask for access to, set up by the administrator: a stored secret, a stored API key, or SSH access to a host. The app also calls these credentials.
Revoke
To end access before its end time. Revoking a grant stops Bouncer issuing tokens and revokes the ones already issued. A value that was already read can't be recalled.
Rotate
To change a secret where it's used (a new password, a new API key), so an old copy stops working. Bouncer can't do this for you.
Save request (store request)
A request to save new values into a secret, rather than read it. The app shows it as Save · N fields. Approving allows one save of the named fields. You never see the values.
Self-approval
Approving your own request, or a request from your own agent. Each resource's policy says whether it's allowed. Where it isn't, the app says "Another approver has to approve this", and you can only deny.
Standing access
Access with no end time, also called a standing grant. The app shows it as Always. Your server may offer it: it's in the default list unless your administrator turns it off. Always is experimental and may change or be removed, so choose a time limit instead. See Approvals and access duration.
Standing grant
A grant with no end time. See Standing access.
StrongBox and TEE
The two places an Android phone can keep a key away from the rest of the system. StrongBox is a separate security chip, on phones that have one. The TEE (trusted execution environment) is a protected part of the main processor. Bouncer's Android key uses StrongBox when the phone has it, and the TEE otherwise.
Tailscale
A VPN service. The deployment kit's examples use tailscale serve to put
HTTPS in front of the server, but Bouncer doesn't need Tailscale or any other
VPN: the apps need a network connection that reaches the server. If your
organisation's server is on Tailscale, the Tailscale app has to be connected
on your phone or PC first. Whether you need it is up to your organisation.
TestFlight
Apple's service for trying out iPhone apps before they're in the App Store. See iPhone and Mac.
Time to answer
How long a request waits for an approver before it expires. 15 minutes by default. The app shows it as "N left to answer".
Token
A short-lived pass that lets a requester read the one secret it was approved for, under one grant. Tokens are only for reading: a save request gets no token, because the server writes the values itself. OpenBao makes each token when Bouncer asks. Each token lasts a few minutes, and Bouncer hands out new ones until the grant ends. It isn't the same as a device token, which tells the server which of your devices is calling.
TPM
Trusted Platform Module, a security chip in most recent PCs. Windows Hello uses it to protect its keys. A TPM's presence alone is not proof of where a particular key lives. Existing Windows Hello keys remain unattested.
User verification
A check that the person, not just the device, is there for each use of a key: a fingerprint, a face, or a Windows Hello PIN. iPhone and Windows Hello keys need it every time you approve or deny. An Android key needs only an unlocked phone, unless you chose Confirm every signature with biometrics when you paired. See Setting up biometric approvals later.
Windows Hello and passkeys
Windows Hello is how Windows checks that it's you: a PIN, your face or your fingerprint. A passkey is a key that Windows keeps and uses only after a Windows Hello check. When you turn on approvals on a PC, Bouncer makes a passkey named "Bouncer on PC-NAME" and signs approvals with it. See Turn on approvals with Windows Hello.
Server and OpenBao terms
These are mostly for the people who run the Bouncer server or connect scripts and agents to it.
Accessor
A second ID for each OpenBao token. It can be used to look up or cancel the token, but not to read anything with it. Bouncer's records name tokens by their accessor, so its log can be compared with OpenBao's without anyone handling a real token.
AppRole
How a program, rather than a person, logs in to OpenBao. It works like a username and password for the program: the role_id names the program and isn't secret on its own, and the secret_id is the password. Bouncer logs in to OpenBao this way. The role kit sets it up.
Device token
A token the server gives a device when it pairs. The app sends it with each call, so the server knows which paired device is asking. It isn't the approval key: the token only identifies the device, and approvals still have to be signed with the key. Revoking the device makes its token stop working.
Downstream credential
A secret that really belongs to another system, such as a cloud provider's API key, which OpenBao only stores for Bouncer to hand out. Bouncer can stop handing it out, but it can't cancel the key at that other system. An administrator can mark a resource as downstream. Then, if the key was handed out under a grant that has since ended, Bouncer lists it as due to be changed at that other system.
Emergency stop
The role kit's emergency-stop.sh, run with an OpenBao admin token. It cuts
Bouncer off from OpenBao without needing the Bouncer server at all: it
removes Bouncer's logins, revokes the tokens Bouncer issued and empties the
kit's policies. Compare the kill switch, which runs inside
Bouncer.
Key labels
The label the server records for each device's approval key when it pairs. In the labels, hw means hardware, sw means software, and uv means user verification (a fingerprint, face or PIN check):
platform-hw-unlocked: kept in the phone's secure hardware, and usable while the phone is unlocked. This is a standard Android key.platform-hw-uv: kept in secure hardware, with a fingerprint or face check on every use. This is an Android key paired with Confirm every signature with biometrics, or an iPhone key.platform-sw-uv: a Windows Hello key, with a check on every use. A passing Windows Hello check doesn't prove the key is in hardware.platform-sw-unlocked: a key kept in software. Servers refuse these unless their administrator allows them.
Unless key attestation proves it, a label is what the device said about itself.
Kill switch
bouncer-admin revoke --all, run on the server by an administrator. It ends
active grants, cancels pending requests and asks OpenBao to revoke every token Bouncer issued. Check its report for any revoke it couldn't confirm. It does not suspend personal
credentials' Always approved mode; use bouncer-admin personal suspend
for each namespace as well (Recovery). Compare the
emergency stop, which works without Bouncer.
KV version 2
The part of OpenBao that stores plain secrets. Each secret sits at a path and
has named fields, for example a password field at apps/billing/db-password.
It keeps earlier versions of each secret. Bouncer reads stored secrets from
it.
MCP
The Model Context Protocol, which AI agents and their client apps use to call
tools. bouncer-mcp lets an agent ask for access through Bouncer.
Migration
A numbered change to the Bouncer server's database that comes with a new version. The server runs any new migrations itself when it starts. If one fails, the server stops instead of starting with the wrong database layout.
Personal-credential namespace
A storage area in OpenBao that an administrator sets aside for personal credentials: a place to keep them, and limits on how long their tokens and access may last. The apps call it a Storage area.
Policy loosening
A change to the server's settings that makes access or pairing easier.
When an administrator reloads the config (bouncer-admin config reload),
Bouncer looks for these changes: for a resource, longer durations or token
lifetimes, new requesters, approvers or secrets, allowing self-approval,
approving from a notification or viewing values, and no longer requiring a
hardware key; for pairing, allowing software keys or user-verified keys, a
weaker Android attestation setting, or a changed Android app identity. For
each one it finds, the approval log records exactly what was loosened, and
the approvers' devices are told. Anything else isn't announced. For example,
turning on Windows Hello keys isn't one of the changes it looks for. A change made while the server
was stopped isn't announced: the log only records that the config was
loaded. Changes that only make things stricter aren't announced either.
Raft snapshot
A backup of OpenBao's own storage (Raft is the name of that storage). What's in it stays encrypted, so restoring it also needs OpenBao's unseal key, in its Shamir shares, unless the server uses a static seal, in which case it needs that seal's key (see Sealed and unsealed). Keep the shares or the seal key safe, and separate from the snapshots.
Role kit
The scripts in deploy/openbao-role-kit that set up Bouncer's narrow role on
an OpenBao: its AppRole login, its policies, and a
token role for each resource. An administrator runs it once
with an OpenBao admin token, and again when resources change.
Root token
The token with every permission, which OpenBao prints once, when it's first set up. Bouncer never uses it. The kit's instructions encrypt it as soon as it's printed. If it's lost, a new one can be made with the unseal shares.
Sealed and unsealed
OpenBao encrypts everything it stores. When it starts, it's sealed: it can't read its own data until it's given its key, which is called unsealing. While OpenBao is sealed, Bouncer can't issue any tokens, so nobody can read a secret through it.
Shamir shares
Pieces of OpenBao's unseal key. When OpenBao is first set up, the key is split into several shares, and a minimum number of them, the threshold, is needed to unseal it. Bouncer's server kit uses three shares with a threshold of two, so no single person holds the whole key. If OpenBao is moved to a static seal, the shares become recovery keys: they can no longer unseal it, and are only used for a few recovery tasks.
SSH revocation list
For SSH access, Bouncer hands out short-lived certificates, and these can't
be revoked from OpenBao. Each configured host's timer attempts to fetch a
list every 15 seconds. Its SSH server refuses listed certificates only
after a successful installation and when sshd uses the list through
RevokedKeys. OpenSSH calls this a KRL (key revocation list).
Bouncer can't confirm delivery: a revoke reports unknown with
pending: krl_delivery. Existing SSH sessions stay open.
Static seal
An OpenBao option where OpenBao unseals itself after a restart, instead of someone typing in shares. Bouncer's repository has an optional setup that keeps the seal key so that only the machine's TPM can decrypt it at boot. That protects against someone copying the disk, but not against someone with full control of the running machine or its host.
Threshold
How many Shamir shares are needed to unseal OpenBao.
Token role
A rule in OpenBao that says what kind of token may be made for a resource: which policy it gets and how long it may last. The role kit makes one for each resource, and Bouncer can only issue tokens through them.
Support
Draft. The support contact details and how quickly we reply aren't decided
yet, so this page shows placeholders such as <SUPPORT_EMAIL> where they will
go.
Bouncer is the approval app for a Bouncer server that your organisation runs.
If something's wrong with your access itself (who may ask for what, or a
device you've lost), your organisation's Bouncer administrator can help
fastest. For problems with the app, email <SUPPORT_EMAIL> and say which
device and app version you have (shown near the bottom of Settings).
Don't send secret values, pairing codes, pairing strings, the keys your scripts or agents use to ask for access, or screenshots that show any of them. The FAQ answers the common questions.
Getting started
- Ask your administrator to run
bouncer-admin device pairfor you. It shows a QR code and a pairing string. The pairing string is your server's address and a one-time pairing code together, as one line of text; the QR code holds the same thing. Both work once and expire after a few minutes. - On a phone, tap Scan QR code, or Enter the code instead and paste the pairing string. On Windows, copy the pairing string and click Paste pairing string, or type the server address and the pairing code separately.
- Check the server and your name, name the device, and tap Pair.
- On a phone, allow notifications when asked, so you hear about new requests. On Windows, Bouncer waits in the notification area and shows a Windows notification while it's running. If you quit it, it can't tell you about new requests until you start it again.
The device needs a network connection that reaches your Bouncer server. Some organisations put the server on a VPN to keep it off the open internet. If yours does, connect it first.
Common problems
"Can't reach your Bouncer server." The device can't get to the server. Check your network connection (and your VPN, if your organisation uses one for Bouncer), and that the address is right. Nothing is approved or changed while the app is offline.
"This code has expired or was already used." Each pairing code works once and only for a few minutes. Ask for a new one.
"Too many wrong codes." Wait a few minutes, then try again with a fresh code.
The camera doesn't open. Allow camera access for Bouncer in the system settings, or use Enter the code instead. The camera is only used to read the pairing QR code. The Windows app doesn't use the camera.
I don't get notifications. Phone notifications only work with a Bouncer server that S6 Studios has set up to send them. Servers run by other organisations can't send them, so open the app to see what's waiting: requests always show in the inbox. If your server does send notifications, check Notification settings in Settings; Android 13 and later ask for permission first. On Windows, Bouncer Desktop shows a notification only while it's running (when it's installed from the Store or an MSIX package, it starts at sign-in unless you turned that off).
A request vanished from the inbox. Requests wait for a limited time. If nobody answers in time it expires and nothing is granted. Whoever asked can ask again.
I approved something by mistake. Open Grants and tap Revoke. Bouncer then stops handing out anything new for that access. Anything it has already handed out, such as a token or a server login, can keep working until it runs out or until the system it opens stops accepting it. A password that was already read can't be taken back, so ask whoever looks after it to change it and to close any logins that used it.
New, lost or retired device
- Switching to a new phone: pair the new one, then sign out on the old one (Settings > Sign out). Signing out asks the server to remove that device.
- Lost or stolen phone: tell your administrator straight away. They remove
the device on the server (
bouncer-admin device revoke), and it can't approve anything after that. - Switching servers: Settings > Switch Bouncer server. The app asks the old server to remove this device first.
- Removing everything: sign out, then uninstall. See the privacy policy for what's kept and where.
Security problems
If you think you've found a security problem in Bouncer, email
<SECURITY_EMAIL> (or <SUPPORT_EMAIL>) privately rather than posting it in
public. We'll reply within <RESPONSE_TIME, TO DECIDE>.
Bouncer privacy policy
Draft for owner and legal review. Not in force. This is the draft privacy
policy for the Bouncer apps. The company details, contact addresses, dates and
how long information is kept aren't settled yet, so they show as placeholders
such as <PRIVACY_EMAIL>. The text may change after that review.
Last updated: <DATE>. Draft: not yet published.
This policy covers the Bouncer apps: Bouncer Mobile for Android and iPhone,
and Bouncer Desktop for Windows. They're made by <LEGAL_ENTITY_NAME>,
called "S6 Studios", "we" or "us" on this page. The apps let you approve or
deny requests for access to your organisation's systems. This page explains
what the apps do with information. There's no Mac app yet; this policy will
be updated before there is one.
Your organisation's server
Bouncer only works with a Bouncer server that your organisation runs itself. We don't run that server and can't see anything on it.
When you pair an Android phone or an iPhone with that server, the phone makes an approval key. It's a pair of keys: the private key stays locked inside the phone and signs your approvals, and the public key goes to the server so it can check that an approval really came from your phone. When you pair, the app sends the server:
- the one-time pairing code;
- the device name you type, and the kind of device (Android, iPhone or Windows);
- on Android and iPhone, the public key (on Android, with a certificate from the phone saying where the key is kept) and a push token, so the server can notify you.
A Windows PC pairs without an approval key. If you turn on Windows Hello approvals, the PC makes one then, as a Windows Hello passkey, and the app sends the server its public key. From version 0.5.7, it also sends any certificate Windows gives from the PC's security chip saying where that key is kept.
The server also sees your device's network address when it connects, as any web server does. It records the address the device was paired from and when the device was last seen.
After that, the app sends your signed approve and deny decisions, and fetches the requests and access waiting for you. If you ask for access in the app, it sends your organisation's server what you asked for, for how long, and the reason you type. If you save a secret or create a credential in the app, the values you type go to your organisation's server. If you share a credential, or change who it's shared with, that change goes to the server too. When you approve a request from someone else to save a new secret, the value goes from them to your organisation's server and never passes through the app.
If your organisation allows it, you can view a stored secret in the app. The app fetches the value from your organisation's server, shows it on that one screen and doesn't keep it. The server records each view. The value never goes to us, Google or Apple.
The app has no sign-in of its own: your organisation's server knows you by the name its administrator set up, and your device by its pairing. Your organisation decides how long it keeps all of this and who can see it. Ask its administrator.
Screenshots, screen recordings and copies
If your Bouncer app is version 0.5.2 or later, it tells your organisation's server when one of these happens while a screen that shows a secret is open, or a form where you're typing one, or just after it closes because the app went to the background:
- A screenshot is taken. Android 14 and later, and iPhone.
- The screen starts or stops being recorded or mirrored. Android 15 and later, and iPhone.
- You copy a secret you're viewing. Android, iPhone and Windows.
- Windows couldn't keep Bouncer's window out of screen capture. Windows only.
What the app sends is a short record: what happened, when, whether the screen showed a saved secret (and which one) or a form, and whether Bouncer had asked your device to keep that screen out of captures. Your organisation's server adds who you are and which device it was, and keeps the record in its log. You can see your own in History. So can the people who approve access to that secret, and your organisation's administrator.
The record never includes the screenshot or the recording, the secret, anything you typed, or what you copied. Bouncer doesn't take, read or keep pictures of your screen. The record goes only to your organisation's server, never to us, Google or Apple.
The app sends these records only to a server new enough to keep them. There isn't a setting to turn them off.
Bouncer only knows what your device tells it, so not every screenshot or recording is noticed. On Android 13 and earlier, only copies are recorded. The Windows app can't detect a screenshot or a recording at all. Nothing is recorded on Bouncer's other screens. On Android 14 and later, Android may show its own note that Bouncer detected a screenshot.
On Android and Windows, Bouncer asks the system to keep those screens out of screenshots and recordings, unless you turn on Allow screenshots in Settings. iPhone doesn't let an app do that; instead, the iPhone app hides a value on screen while the screen is being recorded. Each record says whether the screen was protected, or whether you had turned on Allow screenshots.
Notifications
On Android, the app uses Google's Firebase Cloud Messaging to notify you. On iPhone it uses Firebase Cloud Messaging through Apple's push service. Firebase gives the app an installation ID and a push token: two codes that let a notification find this copy of the app.
Phone notifications only reach you if your organisation's server is set up to send them through our Firebase project. Today, only servers that we have set up can do that. Without notifications, the app shows what's waiting whenever you open it.
Firebase and Apple carry only an ID for the event and an ID for the request, and on iPhone the fixed text "Open Bouncer to check your inbox." Neither ID says anything about the request. A notification never contains the request's details, a secret, or anything that could approve it. The app then fetches the details from your organisation's server. On an unlocked Android phone, the notification shows who is asking, from where, for what, why and for how long; on the lock screen it shows only "Access request pending".
In the store apps, we use Firebase only to deliver notifications. Firebase's own software also sends Google technical information about how it's working, such as the app and system version and the device model. Google lists this as used for diagnostics and analytics, and Google says it isn't linked to you. Google describes how it handles it in its own privacy policy. Google and Apple may handle this information outside your country.
The Windows app doesn't use a push service or Firebase. While it's running, it asks your organisation's server directly for new requests, so it can't notify you while it's closed.
Scanning the pairing QR code
On Android, the QR scanner uses Google's ML Kit, which reads the code on your phone. When the scanner runs, ML Kit sends Google technical information about how it's working: the device model and system version, the app's name and version, an identifier for this installation, and performance and error details. Google says it uses this for diagnostics and analytics and doesn't pass it to anyone else. No image from the camera leaves your phone. If you'd rather not use the scanner, type or paste the pairing code instead.
On iPhone the scanner uses Apple's own on-device code and sends nothing. The Windows app has no scanner.
On your device
The pairing and your approval key stay on your device:
- Android: the key is kept in Android's protected key storage (the Keystore), which doesn't let it be copied off the phone. The code the app uses to prove it's paired is stored encrypted, and Bouncer's data is left out of backups.
- iPhone: the key is kept in the Secure Enclave, a separate security chip inside the iPhone. The pairing is kept in the iPhone's keychain and isn't backed up or synced to your other devices.
- Windows: the key is a Windows Hello passkey. From version 0.5.7, when you turn on Windows Hello approvals, Bouncer asks Windows for evidence that the key is kept in your PC's security chip, and your organisation's server checks any evidence Windows gives. Earlier versions don't ask, and keys set up before 0.5.7 have no such evidence (Device keys). The pairing is encrypted for your Windows account.
Fingerprint, face and PIN checks are done by your device itself; Bouncer never sees them.
From version 0.5.2, the app keeps two settings on your device as on-or-off values: Hide values when switching apps and Allow screenshots (iPhone has only the first). Bouncer never sends them. On iPhone and Windows, a backup of your device or your Windows profile may include them, as it can any app's settings.
If you view a secret, the app shows it on that screen and doesn't keep it. If you copy it:
- iPhone: the copy stays on that iPhone (it isn't shared with your other Apple devices), and iPhone removes it after 30 seconds.
- Android: the copy is marked sensitive, and Bouncer clears it after 30 seconds if Bouncer is still running.
- Windows: from Bouncer 0.5.1, the copy is kept out of clipboard history and isn't synced to your other devices by cloud clipboard. Bouncer clears it after about 30 seconds, when Bouncer quits, or when Windows ends your session (when you sign out or shut down, for example). If Bouncer crashes or is forced to close, it can't clear the copy, and the copy stays on the clipboard until something else is copied. Earlier versions used the ordinary clipboard, where clipboard history and sync could keep a copy.
What we don't do
The apps show no ads, don't track you across apps or websites, and have no analytics or crash reporting of our own. We don't sell your information. Apart from Google's Firebase and ML Kit, and Apple's push service, described above, we don't share it with anyone.
Test builds that we send to named testers through Firebase App Distribution include Firebase's in-app feedback, which sends a tester's report and screenshot to our Firebase project when the tester chooses to send it. The apps in Google Play, the App Store and the Microsoft Store don't include it.
Deleting your data
Sign out in Settings. The app asks your organisation's server to remove this device, then deletes the pairing from the device, and on Android and iPhone the approval key too.
- Android: uninstalling also deletes everything Bouncer keeps on the phone.
- iPhone and Windows: sign out before you uninstall. Uninstalling may not remove the pairing: iPhone usually keeps keychain items after an app is deleted, and Windows doesn't always remove the pairing either. On Windows, the Windows Hello passkey stays after both; on Windows 11 you can remove it under Settings > Accounts > Passkeys.
Uninstalling removes the push token from your device, not from Firebase;
Firebase deletes tokens that aren't used on its own schedule. Records on your
organisation's server are deleted by its administrator. We have no account
for you, so there's nothing for us to delete. If you have a question, email
<PRIVACY_EMAIL>.
How long information is kept
- Your organisation's server: your organisation decides.
- Google and Apple: they keep push tokens and technical information for the periods in their own policies.
- Emails you send us:
<RETENTION, TO DECIDE>.
Your choices
You can choose not to use the QR scanner (type or paste the pairing code
instead), not to allow notifications (you then see requests when you open
the app), and to sign out at any time. For information on your
organisation's server, contact your organisation, which is responsible for
it. <YOUR_RIGHTS, TO DECIDE>
Children
Bouncer is a workplace app and isn't meant for children.
Changes
When this policy changes, we'll update this page and the date at the top. If the apps start sending anything new, we'll update this policy before that version is released.
Who we are
<LEGAL_ENTITY_NAME>, registered in <JURISDICTION>.
Postal address: <POSTAL_ADDRESS>.
Privacy questions: <PRIVACY_EMAIL>. Help with the app: <SUPPORT_EMAIL>.
This policy is governed by <GOVERNING_LAW>.