Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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

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

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:

  1. 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.
  2. 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.
  3. A one-time pairing code from your administrator. They make it with bouncer-admin device pair on the server. It works once and only for a few minutes.

On Windows, "tap" means click.

The tasks, in order

  1. 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.
  2. 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.
  3. Answer requests. Approve for a length of time you choose, or deny.
  4. Understand approvals and access duration. The time to answer and the length of access are different things.
  5. See and end access you've approved, in Grants.
  6. Ask for access yourself, if your administrator lets you.
  7. View, save and share credentials in the Library, where your server allows it.
  8. Replace, lose or remove a device, including signing out and switching servers.
  9. 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.

AndroidWindows
See requests, grants and your own requestsYesYes
Approve and denyYesYes, if the PC has a TPM and your server accepts Windows Hello keys. Then turn on Windows Hello.
PairQR code or pairing stringPairing string
NotificationsPush notifications, even when the app is closedWindows notifications, only while Bouncer is running (in the window or the tray)
Approve from a notificationIf you turn it on, and your server allows itNo

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.

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

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, and SHA256SUMS. SHA256SUMS has a checksum for every file in the release: a 64-character string of letters and numbers that only that exact file produces.

Install

  1. Check the file, if you can, before installing it. On a computer, in the folder with the APK and SHA256SUMS:

    sha256sum -c SHA256SUMS --ignore-missing
    

    It should say bouncer-android-<version>.apk: OK. On a Mac, run shasum -a 256 bouncer-android-<version>.apk instead. On Windows, run Get-FileHash .\bouncer-android-<version>.apk in PowerShell. On a Mac or Windows, check that the long string it prints matches the APK's line in SHA256SUMS. If it doesn't match, don't install it, and tell whoever gave it to you.

  2. Copy the APK to the phone, or download it there.

  3. Open the APK on the phone, from your Downloads or Files app.

  4. 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.

  5. 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.

  6. 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

  1. 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.
  2. 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 seeWhat to do
Android won't open the APKCheck the file finished downloading, and that the checksum matches.
App not installed when updatingThe new APK was signed with a different key. See Update.
Bouncer opens on the pairing screen after an updateThe 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 notificationsSee Troubleshooting.

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

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 PCYes, once: someone with administrator rights on the PC trusts S6 Studios' certificateNo
Start menu entryYesNo
Starts in the tray when you sign inYes (you can turn it off)Only if you add a shortcut
UpdatesFrom its update link, if you installed it that wayNever; download each new version
Remove itSettings > AppsDelete 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 certificate bouncer-beta-signing.cer, SHA256SUMS and bouncer-windows-install-instructions.md, or the ZIP bouncer-windows-x64-<version>.zip and SHA256SUMS.
  • 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

  1. 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.
  2. Open the extracted Bouncer-<version> folder and run Bouncer.exe. Keep the DLL files and the data folder beside it. Don't run it from inside the ZIP.
  3. 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.appinstaller file): 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:

  1. 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.
  2. Quit the ZIP copy from the tray icon, and delete its folder.
  3. 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:

  1. 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 revoke command for your administrator.

  2. Quit Bouncer Desktop from the tray icon.

  3. 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.
  4. 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.

  5. 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.

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

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.

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

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

  • The app installed: Android or Windows.

  • 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 pair on 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

  1. Open Bouncer. You see To pair this phone with the command your administrator runs.
  2. 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.
  3. 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.
  4. 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".
  5. 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.
  6. Tap Pair.
  7. 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.
  8. 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

  1. Open Bouncer. You see Pair this PC.
  2. On the server, your administrator runs bouncer-admin device pair and gives you the line under "Or copy this pairing string". Copy it.
  3. In Bouncer, choose Paste pairing string. It fills in the Server address and Pairing code. (You can also type them.)
  4. Check the Device name, then choose Pair.
  5. 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.
  6. 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:

  1. 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.
  2. On Windows 11, Windows may ask "Let Bouncer Desktop create and use passkeys?" If it does, choose Yes.
  3. 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.
  4. 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 saysWhat 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 saysWhat 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."

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

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

  1. 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.
  2. 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.
  3. 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.
  4. 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

  1. 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.
  2. 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:

  1. Open Settings.
  2. 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 seeWhy, and what to do
Another approver has to approve thisIt'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 expiredNobody answered in time. Nothing was granted. The requester can ask again.
Already approved, Already denied or CancelledSomeone answered on another device, or the requester cancelled. Nothing to do.
This phone couldn't check this requestWhat'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 helpThe 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 itThe request uses something newer than your app. Update the app.
Couldn't send your decisionThe 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.

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

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.

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

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

  1. In Grants, Active, find the grant and tap Revoke.
  2. Revoke this grant? says who loses access to what, and how early.
  3. Tap Revoke to confirm.
  4. 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.

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

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

  1. Open the Requests tab and tap New request. On Windows, choose New request… from the tray menu, or New request in the window.
  2. 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.
  3. 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.
  4. Under Reason, answer Why do you need it? in up to 280 characters. Your approver sees it as your own words.
  5. 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 seeWhat 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.

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

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.

  1. Open the credential in the Library (or in Grants, under Secrets you have access to).
  2. Read the warning: "Anyone who sees this value has it. Viewing can't be undone."
  3. 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").
  4. 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:

MessageMeaning
Hidden: "Show and Copy appear once you have an active read grant."Ask for access first.
Viewing is off for this credentialYour administrator hasn't allowed viewing it on a device. Scripts and agents can still use it with a grant.
Nothing to showIt's SSH access, which uses a new certificate for each connection. There's no stored value.
Your grant only saves valuesA save grant lets you save new values, not read them.
Nothing is stored yetThe secret store has no value for it yet. Save one first.
This grant isn't yoursOnly 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.

  1. Open the credential in the Library and tap Edit.
  2. The fields it already has are listed by name, empty and hidden. Opening the form doesn't fetch anything.
  3. 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.
  4. 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.
  5. 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.
  6. 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

  1. In Library, open the credential's Details and find Versions.
  2. 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.
  3. 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.
  4. 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

  1. Open the credential's Details, check Versions, then tap Replace in Versions, or the Replace (new version) button that takes the place of Edit.
  2. 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.
  3. Tap Save replacement and confirm it's you.
  4. 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.

  1. In Versions, tap View on the older version. It only appears if you're allowed and this device's key is suitable.
  2. 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."
  3. 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.

  1. In Library, tap New personal credential.
  2. 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.
  3. 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.
  4. Under Access, choose Approval required (you approve each request).
  5. 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.
  6. Tap Review, check You're authorising, then Verify and create and confirm it's you.
  7. 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

TypeFields (optional ones in brackets)
Password(username), password, (url)
API keyapi_key, (url)
Access tokentoken, (url)
Certificate onlycertificate, (chain)
Certificate + private keycertificate, private_key, (chain), (passphrase)
SSH private keyprivate_key, (public_key), (passphrase)
Encryption / signing secret keysecret_key
Public / private key pairprivate_key, public_key, (passphrase)
Recovery / backup codesrecovery_codes, (account), (url)
Authenticator / OTP seedotp_seed, (account), (url)
Secret bundle / otherone 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.

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

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

  1. Pair the new device with a new pairing code.
  2. Check it works: open a request on it, or look in its Settings under Your other devices for the old one.
  3. 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 revoke command, 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.

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

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".

  1. Check the device is connected to a network that reaches your Bouncer server.
  2. If your organisation uses a VPN for Bouncer, check it's connected on this device.
  3. 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 saysWhat'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

  1. 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.
  2. Android 13 and later ask for permission to show notifications. If you chose Not now when pairing, turn notifications on there.
  3. Battery savers can delay notifications. If they come late, let Bouncer run unrestricted in Android's battery settings for the app.
  4. 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 seeWhat to do
Your phone is lockedUnlock it, then try again.
Android needs a fresh unlockOn 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 confirmedYou cancelled the fingerprint check, or it timed out. Try again.
Too many attemptsWait a moment, or lock the phone and unlock it with your PIN, pattern or password.
Bouncer wasn't on screenKeep Bouncer open while you confirm.
Fingerprint check isn't availableCheck a fingerprint is set up in Android settings.
Another confirmation is openFinish or cancel the other fingerprint check.
This phone's key stopped workingYour fingerprints changed, so Android retired the key. Pair again.
This phone couldn't use its keyUnlock the phone and try again. If it keeps happening, pair again.

Windows Hello problems

What you seeWhat 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.

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

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-mcp gives 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

  1. The program files a request: a resource, a duration and a reason. (bouncer request, or the MCP tool request_access.)
  2. 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.
  3. The server records a grant: permission to use that resource until a set time.
  4. 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 exec and the MCP tool get_secret do this for you.
  5. 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

  1. Install the CLI.
  2. Set up a requester with the key your admin gives you.
  3. Use the CLI, or connect an AI agent through MCP.
  4. 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

ClientStatus 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 CLINot 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.

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

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):

  • SHA256SUMS
  • install.sh
  • bouncer-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.sh checks the tarball against SHA256SUMS, checks every file inside it, and installs bouncer and bouncer-mcp. It installs to ~/.local/bin as a normal user, to /usr/local/bin when run as root (sudo sh install.sh), or to --prefix DIR. It downloads nothing and never touches your key.
  • If it says ~/.local/bin isn't on your PATH, 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 installedHow to update
install.shInstall 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 .rpmInstall 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:

  • SHA256SUMS
  • install-windows-cli.ps1
  • bouncer-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\bin and adds that folder to your own PATH (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

  • exec gives a secret in an environment variable (--env) or on standard input (--stdin). --file is Linux only, and bouncer never 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.

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

Set up a requester

A requester is whoever asks Bouncer for access: you at the command line, an AI agent, or a host such as a build server. Each one has its own requester key, a random string starting brk_. The key lets the requester ask and use what's approved for it. It can never approve anything.

1. Get a key from your admin

The admin creates the requester on the Bouncer server and gives you its key as a file (People, requesters and devices). Ask for:

  • one requester per agent, host or pipeline, so the approver can tell them apart and the admin can disable one without affecting the others;
  • the right kind: agent for anything an AI runs (the MCP server refuses any other kind), host for a machine, human for you.

If you're listed as a person in the server's configuration, your own human requester already exists. The admin gives it a key with bouncer-admin requester rotate-key <your-id>, which also stops any key it had before.

The key is shown to the admin only once. If it's lost, the admin makes a new one, and the old one stops working.

2. Store the key

Copy the key file to the machine that will use it (for example with scp), then, as the user who will run bouncer:

install -d -m 700 ~/.config/bouncer
install -m 600 build-agent.key ~/.config/bouncer/key
shred -u build-agent.key
echo https://bouncer.example.com > ~/.config/bouncer/server

bouncer now reads the server's address and the key from those two files, so there's nothing to export.

The key file is checked the way ssh checks a private key: it must belong to you or root, and other users must not be able to read or change it. bouncer refuses it otherwise, with exit code 7.

To use a different key, for example for an agent running under your own user, keep it in another file and point to it:

export BOUNCER_KEY_FILE=~/.config/bouncer/agent-key

The order bouncer uses:

SettingTaken from, first match wins
Server--server, then BOUNCER_URL, then the first line of ~/.config/bouncer/server
Key--key-file, then BOUNCER_KEY_FILE, then BOUNCER_KEY (the key itself), then ~/.config/bouncer/key
Extra CA certificatesBOUNCER_CA_FILE, a PEM file trusted on top of the system's, for both Bouncer and OpenBao

$XDG_CONFIG_HOME replaces ~/.config when it's set.

Never type the key as an argument. bouncer refuses any argument that looks like a key, because it would end up in your shell history and in the process list where other users can see it. BOUNCER_KEY works, but a file is safer: an environment variable is passed to every program you start.

3. Check it works

bouncer resources

Expected result: a table of the resources this requester may ask for:

RESOURCE          NAME                           KIND     FIELDS    FOR                  WRITE  NOW
prod-db-password  Production database password  secret   password  5m,15m,1h,6h,1d      no     -
deploy-token      Deploy token                   api-key  token     5m,15m,1h            yes    -

If it fails:

Exit code and messageWhat to do
7, no server addressWrite the address to ~/.config/bouncer/server, or set BOUNCER_URL
7, the key file can be read by otherschmod 600 ~/.config/bouncer/key
7, plain HTTPThe server address must start with https:// (plain http:// works only for an address on this machine, for testing)
6, the key isn't acceptedThe key is wrong, was replaced, or the requester was disabled. Ask your admin
1, the server can't be reachedCheck the address, your network or VPN, and any proxy settings
1, a certificate errorIf your organisation uses a private CA, set BOUNCER_CA_FILE to its PEM file

Proxies

HTTPS calls go through HTTPS_PROXY (or ALL_PROXY) when one is set, except to the hosts in NO_PROXY. The proxy only sees an encrypted tunnel. Plain HTTP and calls to this machine never go through a proxy, and HTTP_PROXY is never used, so a proxy can never see the key or a token in clear.

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

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")
  • --for is a whole number and a unit (30s, 15m, 6h, 7d), or always for a standing grant where the server allows it. Ask for the shortest time that does the job.
  • --reason is up to 280 characters. The approver reads it before deciding, labelled as reported by you, so say what the task is.
  • --host and --client change 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"
OutcomeMessageExit code
ApprovedApproved by Alice on Alice's phone. Grant grt_..., for 15 minutes.0
DeniedDenied by Alice on Alice's phone.3
Nobody decided in time4
CancelledCancelled.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

OptionWhat it does
--env NAME=fieldSets the environment variable NAME from field. Repeatable. Once you use it, only the fields you name are passed
--file NAME=fieldPuts 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 fieldGives the field to the command on its standard input, without a trailing newline. One field only. Linux and Windows (from 0.5.1)
--prefix PPuts 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_* and BOUNCER_* (bouncer exec --help lists 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

  • --json prints 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.
  • bouncer never 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.

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

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-keygen and 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.md covers 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_FILE for a private CA. No particular VPN is required;
  • access to bouncer-admin on 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.

SymptomWhat to check
No connection or a TLS errorBouncer'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 errorThe configured key path, readability and mode (600 or 400)
HTTP 401 or 403The key, the requester's enabled state and its host kind. Replace a lost or exposed key through the admin route
HTTP 404In 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 500An 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 503In 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 refusedFind 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 inConfirm 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.

  1. 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. If ssh.service or sshd.service is active, the helper tries those units first. Run systemctl show -p MainPID ssh.service sshd.service and 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 pidfile
    

    The named file must hold the process ID of the daemon serving logins. The helper does not check either identity.

  2. Remove the host's Bouncer CA and account trust, then reload the daemon. If you applied the trust with ssh-host-trust.sh, run ssh-host-trust.sh --rollback as root. It reloads the SSH daemon before it stops bouncer-krl.timer and 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 the TrustedUserCAKeys, RevokedKeys and AuthorizedPrincipalsFile lines you added, and reload the SSH daemon.

  3. 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 your Match blocks test. Neither trustedusercakeys nor revokedkeys may name a file under /etc/ssh/bouncer/. If you omit a detail a Match block 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.

  4. 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.key
    

    Before 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.krl
    

    An 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.

  5. 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.

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

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-mcp installed on the agent's machine (Install the CLI). Install bouncer beside it too, so the agent can deliver a secret to a command without fetching it through get_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.

VariableMeaning
BOUNCER_URLThe Bouncer server's address. HTTPS, or plain HTTP to this machine only
BOUNCER_KEY_FILERequired. The agent's key file. It must be private (chmod 600)
BOUNCER_CA_FILEOptional. Extra CA certificates (PEM) for Bouncer and OpenBao

The tools

ToolArgumentsWhat it does
list_resourcesnoneLists what this agent may ask for, with each resource's durations, decision time and token lifetime
request_accessresource, duration, reasonFiles 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_statusrequest_idOne request, without waiting
wait_for_decisionrequest_id, optional timeout_secondsWaits for the decision, 55 seconds by default and at most 120. If it's still pending, the agent calls it again
get_secretresourceFor an active grant, fetches a short-lived token, reads the secret and returns its field values. Never returns the token
list_grantsoptional include_endedThe agent's grants
revoke_grantgrant_idEnds one of the agent's grants now
cancel_requestrequest_idWithdraws a pending request
request_storeresource, fields, reasonAsks permission to save new values into a resource that allows writes. Field names only
save_secretrequest_id, valuesAfter 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.

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

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:

  1. Standard input, if the tool can read a secret there: bouncer exec ... --stdin password -- tool --password-stdin.
  2. 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 command bouncer starts, 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.
  3. 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 list shows 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 exec command the MCP tools suggest over get_secret to 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_grant when 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.

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

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.

CodeMeaning
0Done. For wait, request --wait and exec: the request was approved
1Something went wrong: the server couldn't be reached, failed (HTTP 5xx or 429), or sent something this version can't read
2The command line was wrong
3The request was denied
4The request expired without a decision
5The request was cancelled or superseded
6The 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
7Configuration: 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)
8No active grant for the resource, including a grant that has just ended
9The deadline passed while the request was in a state this version doesn't know
10Revoked, but OpenBao didn't confirm the revoke of every issued token. The grant is still ended
11bouncer-admin revoke --all wasn't confirmed (no yes, or no --yes when not on a terminal)
12The server is running, but its vault (OpenBao) is sealed (backend_sealed). An outage, not a refusal: the server's administrator must unseal it
13The server is running, but can't reach its vault (backend_unreachable). An outage, not a refusal
14The 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
15Can'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
16From 0.5.7: the server is running, but PostgreSQL is unavailable (database_unavailable). The server's administrator must check the database
126exec: the command was found but couldn't be started
127exec: 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:

CodeHTTPMeaningExit code
unauthenticated401No key, or not a valid one6
requester_disabled403This requester has been disabled6
forbidden403A valid key, but not allowed to do this6
not_requestable403This requester may not ask for this resource6
not_found404No such object, or not visible to this requester6
invalid_body400The request doesn't match the API6
reason_invalid422The reason is empty, too long, or has hidden characters6
duration_not_permitted422The duration isn't allowed for this resource6
request_not_pending409The request was already decided, expired or cancelled6
grant_not_active409The grant has expired, been revoked or been suspended8
idempotency_conflict409The same idempotency key was used with a different request6
rate_limited429Too many attempts; try again later1
issuance_failed502Bouncer couldn't release a credential1
write_failed502OpenBao didn't save the values1
internal500Something failed on the server; its log has the details1
backend_sealed503The server is running, but its vault (OpenBao) is sealed12
backend_unreachable503The server is running, but can't reach its vault13
backend_auth_failed503The server is running, but its vault refused the server's own login14
resource_not_provisioned503From 0.5.7: this resource needs the server's administrator to repair its role-kit token role or policy. One call, no retries7
database_unavailable503From 0.5.7: the server is running, but PostgreSQL failed its readiness probe16
(none: a bare 502, 503 or 504)The proxy in front of the server got no answer from it15

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_unreachable and backend_auth_failed, and (from 0.5.7) resource_not_provisioned. They need the server's administrator, so bouncer says 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.

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

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):

FolderWhat it sets up
deploy/composeThe Bouncer server and PostgreSQL 18, with Docker Compose or Podman
deploy/openbao-role-kitThe 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/openbaoA 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).
  • 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 bao command, jq and 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.

CheckWhat to have ready
Version and filesChoose 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 OpenBaoRecord 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 recoveryMake 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 storageChoose 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 trustChoose 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 policyChoose 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.
NotificationsWith 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 drillPlan 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

  1. Set up OpenBao, or check the one you have: running, unsealed, with a KV version 2 mount.
  2. Install the server: the OpenBao role, the config, the secret files, the image, and the first start.
  3. Set up HTTPS and networking.
  4. Add people, requesters and devices, and pair the first phone.
  5. Try a request end to end, then run the kill switch once so you know it works.
  6. 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.sh and test-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.

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

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 password at apps/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:

    • ssh access to the VM, and a network route to OpenBao's address (for example on the same Tailscale network), because bao and curl talk 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 bao command, jq, curl, python3 and age;
    • an age key 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 --verify and ./emergency-stop.sh --dry-run to check that it can read everything the stop needs. The SSH kit's admin policy must match your kit.env and ssh/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.hcl doesn'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 authenticated sys/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.

  1. 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 = false
    

    Then docker compose restart openbao, and unseal it.

  2. 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)
    
  3. 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
    
  4. 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 -decode doesn't work here: it needs a token before it decodes one.)

  5. Do what you needed the token for, then bao token revoke -self and unset BAO_TOKEN.

  6. Take the line out of openbao.hcl again, 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/health included, with HTTP 503 and backend_sealed or backend_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-admin and 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.

  1. Keep the pre-upgrade backup and the old release's files.
  2. In the new release's deploy/openbao-role-kit, copy resources and kit.env from the old kit, and ssh/ssh-resources if you use SSH hosts. Log in to OpenBao with an authorised admin token. Run ./setup.sh --dry-run and read every change it proposes.
  3. 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.
  4. With the single-use check login from Install, step 2c, run ./check.sh to check the role's permissions. Do not give it the admin login.
  5. Run ./setup.sh --verify. It must exit 0.
  6. 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.

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

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 SHA256SUMS and --ignore-missing. The 0.5.6 build introduced its own bouncer-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:

  1. Check the files against the release's combined SHA256SUMS. For 0.5.5:

    sha256sum -c SHA256SUMS --ignore-missing
    

    It must say OK for each file you downloaded. If one says FAILED, download it again and don't use it. --ignore-missing skips app and CLI files you didn't download. For a release that includes bouncer-server-<version>-SHA256SUMS, use sha256sum -c bouncer-server-<version>-SHA256SUMS instead; it lists only the three server files.

  2. Load the image:

    gunzip -c bouncer-server-<version>-image.tar.gz | docker load
    

    It ends with Loaded image: localhost/bouncer-server:<short commit>. With Podman: podman load -i bouncer-server-<version>-image.tar.gz.

  3. 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.md shows them. If it doesn't, stop.

  4. Unpack the kit into a folder of its own, so the release before it stays for a rollback, and point .env at 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>' >> .env
    

    The last two lines record the release in .env and 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 example 10.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 as example-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 example https://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.pem and set ca_file: /etc/bouncer/openbao-ca.pem (the config folder is mounted at /etc/bouncer inside the container).
  • resources: one entry per resource, with the same IDs and KV paths as the role kit's resources file.
  • pairing: leave allow_software_keys: false. Add allow_user_verified_keys: true if anyone will approve from an iPhone, and allow_webauthn_keys: true if 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 to false, and take always out of defaults.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: null for 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

  1. Put HTTPS in front of the server.

  2. Create requesters and pair your phone.

  3. 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 is value, use --env PASSWORD=value.

  4. Run the kill switch once, so you know it works before you need it:

    docker compose exec bouncer bouncer-admin revoke --all
    

    It 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.

  5. Schedule backups.

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.

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

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

FromToPort (defaults)Notes
Phones, PCs, requestersYour HTTPS front end443The address in instance.url
HTTPS front endBouncer server127.0.0.1:8080Plain HTTP, on the same machine
Bouncer serverPostgreSQLnoneA Unix socket on a shared volume. PostgreSQL has no network at all
Bouncer serverOpenBao8443 with deploy/openbao, or whatever your OpenBao usesUse HTTPS. The config accepts plain HTTP too, but then tokens cross the network unencrypted; use it only when OpenBao is on the same machine
RequestersOpenBaothe sameRequesters read secrets from OpenBao directly with the short tokens Bouncer gives them
Bouncer serverFirebase (Google)443, outboundOnly if push is on
bouncer-adminBouncer servernoneA 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.

  1. In the Tailscale admin console, turn on MagicDNS and HTTPS certificates.

  2. On the Bouncer server:

    sudo tailscale serve --bg --https=443 http://127.0.0.1:8080
    tailscale serve status
    
  3. tailscale serve status shows the HTTPS address (it ends in .ts.net). Set instance.url in the config to exactly that address, then run docker compose exec bouncer bouncer-admin config reload.

  4. From another machine on your tailnet:

    curl -s https://<the address from step 3>/v1/health
    

    Expected result: the same health answer as on the server itself, with "status":"ok" and your instance.url, which is your .ts.net address (the example uses this guide's placeholder):

    {"status":"ok","instance":{"id":"example-home","name":"Example home","url":"https://bouncer.example.com", ...
    

    If curl complains 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-For to 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.pem and set openbao.ca_file: /etc/bouncer/openbao-ca.pem, then restart;
  • each requester: set BOUNCER_CA_FILE to 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.

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

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

SectionWhat it holds
versionAlways 1
instanceThe 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
peopleEveryone who pairs a device and approves. Each person also gets a human requester with the same name, for requests they make themselves
groupsOptional named groups of people, used by personal credential sharing
defaultsThe policy every resource gets unless it sets its own: waiting time, token lifetime, the duration choices, self-approval and approval from notifications
openbaoWhere OpenBao is, its CA file, the role kit's prefix, and the AppRole files
pairingWhich kinds of approval key may pair (see Device keys)
pushFirebase push settings, or null for no push (Push notifications)
resourcesOne entry per secret Bouncer guards (Resources and policy)
personal_credentialsOptional 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 openbao section;
  • 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:

ExitMeaning
0All checks passed
1Global setup or login failure
2Command usage error
3A definite resource gap, such as a missing or unsuitable role or policy
4Kit 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.

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

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]
SettingMeaning
idThe 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, descriptionWhat people see in the apps and in bouncer resources
folderWhere the apps' library files it, as folder names joined by /. Leave it out for "Unfiled". Changing it doesn't affect any grant
kindstored_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_typeOptional. 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
kvThe OpenBao KV version 2 secrets behind it: one or more mount and path pairs
fieldsOptional. The field names in the secret, shown to requesters so they know what to ask for. Names only, never values
approversThe people (by their id in people) who may approve requests for it
requestersWho 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:

  1. Add its line to the role kit's resources file, then run the kit upgrade and permission checks.
  2. 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.
  3. Install the checked config. The resource takes its durations from defaults unless you set its own; you don't need a shorter maximum because it's new.
  4. 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 (default true). When it's true, 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's false, those requests need another approver. Denying is always allowed. See Separation of duties.
  • notification_approval (default true). 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 (default false). When true, 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 (default false). 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 unverified platform-hw-uv claim 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_uv keeps 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_keys opt-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.

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

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

ActionEffect
Expire nowBouncer 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 expiryBouncer 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
ReplaceBouncer 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:

OperationConfigured resourcePersonal credential
List version history, without valuesIts approversIts owner and people it is shared with
Expire, schedule or remove a scheduled expiryIts approversIts owner, Editors and Managers
ReplaceIts approvers, with allow_write: true and self_approval: trueIts owner, Editors and Managers
View an old version's valueIts approvers, with view enabledOwner 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

  1. 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.
  2. 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.
  3. Check the KV mount's and the secret's max_versions, and any delete_version_after setting, 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.
  4. Decide who should be able to expire values and inspect old ones using the table above. Enabling lifecycle on a resource with view enabled also gives its approvers the separate old-value view, and a reload records this as a policy_loosened entry 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.

  1. In the role kit's resources file, add lifecycle to the resource's line. For the example in step 3, the line is:

    example-api-key  kv  apps/example/api-key  lifecycle
    

    The lifecycle word 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. The write and view words control their own data permissions.

  2. 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.

  3. Add lifecycle: true to 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 write on the role-kit line, allow_write: true and self_approval: true. Self-approval also lets Alice approve her own access requests, so review that policy separately. App viewing needs view in both places. See Resources and policy.

  4. For an existing resource, reload from your Compose folder:

    docker compose exec bouncer bouncer-admin config reload
    

    A new resource needs a server restart instead.

  5. Check the reload succeeded, then read the approval log for any policy_loosened entries. 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 1h if 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.

  1. Add lifecycle to the namespace's line in the role kit:

    personal  kv  bouncer-personal  personal lifecycle
    
  2. Apply and check the role kit, as for a resource above.

  3. Add lifecycle: true to 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
    
  4. 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.

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

People, requesters and devices

Bouncer has three kinds of identity. This page explains each one and the bouncer-admin commands that manage them.

IdentityWhat it isCredential
PersonSomeone who approves. Listed in the config fileThe devices paired as them
RequesterWhoever asks for access: a person at the command line, an AI agent, or a host such as a build serverA requester key, a random string starting brk_, kept in a file
DeviceA phone or PC paired to a person, which shows requests and signs approvalsA 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
  • --kind is agent (an AI agent or other automation acting for a person), host (a machine, such as a build server) or human.

  • --owner links 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

  1. 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.
  2. Revoke each of their devices (device list, then device revoke).
  3. Disable each requester they own, including their human requester (requester disable).
  4. Remove them from people, from every resource's approvers and from any groups, then reload and check that it succeeded. Their name stays in old log entries.
  5. If they could read static secrets, rotate those secrets at their source (Copied secrets).

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

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 people in 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:

AppHow
Android, iOSScan the QR code, or type the address and code
WindowsPaste 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:

SettingDefaultMeaning
allow_software_keysfalseA key kept in software rather than the device's secure hardware. Leave it off; only test setups turn it on
allow_user_verified_keysfalsePhone 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_keysfalseWindows Hello keys on Windows PCs
android_attestationpreferWhether 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 saysWhat to do
The code is refused as invalid or expiredCodes work once and for a few minutes. Make a new one
rate_limitedMore than 10 wrong codes from one address in 10 minutes. Wait, then try again with a fresh code
The app can't reach the serverThe 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: requiredThe 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.

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

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

PlatformPush
AndroidFCM, with the event ID only
iOSFCM, 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
WindowsNo 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.dart says 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.

  1. 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
    
  2. In /etc/bouncer/config/bouncer.yaml, replace push: null with:

    push:
      fcm:
        project_id: example-firebase-project
        service_account_file: /run/secrets/fcm-service-account.json
    
  3. In deploy/compose/.env, add the push compose file, which mounts the key file:

    COMPOSE_FILE=compose.yaml:compose.push.yaml
    
  4. 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 bouncer
    

    Wait 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.

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

Health checks

What to watch

CheckHowHealthy answer
Bouncer readinesscurl -s http://127.0.0.1:8080/v1/health on the server, or https://bouncer.example.com/v1/health from elsewhereHTTP 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 containersdocker compose psBoth services healthy
OpenBaocurl -s https://openbao.example.com:8443/v1/sys/healthHTTP 200 (initialised, unsealed and active)
BackupsThe newest file in your backup folder, and the backup timer's statusLess than about a day old
Disk spaceYour usual monitoringUnder 80% on the Docker volumes and OpenBao's data and audit volumes
OpenBao secret_id expiryThe date you noted at installRenew 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/health on 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 again records 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 provisioned and resource 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 revoke failures, 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.

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

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 answerbouncer CLI (exit code)MCP tool errorAppsWhat's wrongWho 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 probeThe 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 sealedThe 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-upThe 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 networkCheck 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_unreachable or backend_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 saysMeaning
the database isn't ready; answering 503 database_unavailable until it isFrom 0.5.7: the PostgreSQL probe failed. Check the database; Bouncer stays up
the database is ready againFrom 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 isStarted 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 isOpenBao stopped answering while the server ran
the credential backend is ready againOpenBao is back, and the server issues again
the credential backend answers again, but fails the start-up checkOpenBao 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 checkThe 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 isOpenBao 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 ignoredRemove 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 in server/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.rs and mcp/src/tools.rs, with their tests. The apps' are from app/lib/ui/copy.dart, tested in app/test/screens/inbox_test.dart and app/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_confirmed before the token expired.

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

Everyday maintenance

Run these from ~/bouncer/deploy/compose on the server.

Common commands

TaskCommand
Statusdocker compose ps
Logsdocker compose logs -f bouncer
Reload the config after an editdocker 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 everythingdocker compose stop
Start again and wait for healthdocker compose up -d --wait --wait-timeout 120
Revoke a devicedocker compose exec bouncer bouncer-admin device revoke <device-id>
Disable a requesterdocker compose exec bouncer bouncer-admin requester disable <name>
The kill switchdocker compose exec bouncer bouncer-admin revoke --all
Re-confirm a standing grantdocker compose exec bouncer bouncer-admin grant review <grant-id>
Export the approval logdocker 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.

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

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:

  1. finds the running release from Docker's labels, and copies its .env into the new release with the new image, version and revision;
  2. 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);
  3. stops the server, so nothing changes after the backup, and takes a backup with backup.sh;
  4. starts the new release and waits for /v1/health (240 seconds by default, BOUNCER_WAIT);
  5. if that fails, restores the backup (only when the new server ran migrations) and starts the old release again, then exits 1;
  6. on success, records the new release in CURRENT and the old one in PREVIOUS in 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:

  1. 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.

  2. Stop the current server from the folder it runs from: the new release's deploy/compose for a release download, or ~/bouncer/deploy/compose for a source build. Run docker compose stop bouncer there. Then use the route that matches your installation:

    From a release download: use the old release's image and compose kit, with the .env you 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 .env from your pre-upgrade copy:

    tar -xzf 'bouncer-server-<old version>-compose.tar.gz' -C ~/bouncer-releases
    

    Do not unpack over an existing release folder. In its deploy/compose, confirm BOUNCER_IMAGE, BOUNCER_VERSION and BOUNCER_REVISION name 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)"
    
  3. For both routes: if the new version added settings the old one refuses (for example require_hardware_key before 0.5.7, credential_type before 0.5.0, or push.fcm_also before build 0.3.8+25), take them out of /etc/bouncer/config/bouncer.yaml now. The old server will not start with them. Removing a security setting such as require_hardware_key lets 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 (up and logs). 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_migrations or reverse SQL changes by hand.

  4. Start the old version from its compose folder. up -d recreates 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
    
  5. 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_ttl of 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:

  1. Stop scheduled fetches and any fetch in progress:

    sudo systemctl stop bouncer-krl.timer
    sudo systemctl stop bouncer-krl.service
    
  2. Remove only the version file:

    sudo rm -f /var/lib/bouncer-krl/version
    

    That's the kit's default path. If /etc/bouncer/krl.env sets BOUNCER_KRL_STATE_DIR, remove the version file 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) or last_ok.

  3. 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
    
  4. 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/version
    

    If 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 reports STALE once the freshness limit passes. If /etc/bouncer/krl.env sets BOUNCER_KRL_STATE_DIR or BOUNCER_KRL_MAX_AGE, give --check the same settings. This only checks freshness; fix the cause, then repeat step 3.

  5. 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.

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

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

WhatHowNotes
Bouncer's databasebackup.sh, daily and before every upgradeThis page
Your config file and the role kit's resources and kit.envKeep them in your own Git repositoryWithout them you can't rebuild the server
OpenBao's datadeploy/openbao/snapshot.shPlus the unseal material, kept separately
The secret files in /etc/bouncer/secretsDon't back them up. Make new ones insteadSee 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:

VariableDefaultMeaning
BOUNCER_PROJECTbouncerThe Compose project name
BOUNCER_BACKUP_DIR/var/backups/bouncerWhere dumps go
BOUNCER_BACKUP_KEEP30How 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 active now but was revoked before: docker compose exec bouncer bouncer-admin device revoke <device-id>;

  • disable each requester that is active now but was disabled before: 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 ID column: a short label for each requester's current key, 12 lower-case hexadecimal characters, that isn't secret. For each requester, compare its KEY ID in 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 the KEY ISSUED times match. Ignore LAST USED here.

    If either list has no KEY ID column, 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 every requester_key_issued entry since the backup, replace the keys it shows were issued after the backup. Otherwise replace every active requester key. Matching KEY ISSUED times 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 freeze leaves 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.

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

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.

  1. 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 is sudo tailscale serve --https=443 off. Use your proxy's own stop procedure otherwise. This needs neither Bouncer nor OpenBao, and bouncer-admin still works. It does not revoke existing OpenBao tokens or copied values.

  2. 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.

  3. 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 --all
    

    Revoke the device before the kill switch. The kill switch alone leaves the device paired, so it could approve the next request.

  4. 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:8080
    

    Then pair the replacement. The person's other devices get a "New device paired" alert.

  5. 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 lostWhat to do
The person who ran the server has leftAnyone 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 serverRegain it the way you would for any machine you own (console, hypervisor, cloud provider). Bouncer has no back door
The server itselfBuild 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 fileRestore 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 tokenUse 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:

ExitMeaning
0Bouncer is cut off. Nothing had been changed by hand, and everything was revoked
1Not 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
2Bouncer 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:

  1. 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.
  2. ./setup.sh --accept-unrevocable-tokens, which restores the kit's policies.
  3. ./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.
  4. Give Bouncer a new secret_id (Maintenance).
  5. If you stopped the SSH signer, run ./ssh/setup-ssh.sh again with the same kit.env and ssh/ssh-resources. It restores the policy. Make a new signer secret_id as in step 3 of the kit's ssh/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

SituationWhat to do
OpenBao restarted and is sealedUnseal it with two of its three shares (OpenBao for Bouncer). Restarting it again won't help
OpenBao's data is lostRestore 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 failsUse 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.

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

Audit: what is logged and where

There are three records, each answering a different question.

RecordWhere it isWhat it answers
Bouncer's approval logBouncer's PostgreSQL databaseWho asked for what, who decided, which grants ended, and what changed in the config
The server's logThe container's output (docker compose logs bouncer)What the server did and why it failed, for troubleshooting
OpenBao's audit logOpenBao's audit device, if you turned one onEvery 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).

FieldWhat it identifies
grant_id, request_id, requester, resourceThe grant and its recorded context
atOn 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_idThe particular token or wrapped read
token_audit.roleThe 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.accessorThe 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_outcomenull 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:

  1. Export the approval log with a bouncer-admin from the same version as the server (See it and export it). Find the grant and its token_issued entry. Match later backend_revoke entries by grant_id and token_audit.issuance_id.

  2. 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.hash
    

    Replace file with 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.

  3. Look for that hash in the creation-response field from the table below, in auth.accessor on later uses of the token, and in request.data.accessor on auth/token/revoke-accessor. On the creation record itself, the top-level auth.accessor belongs 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 outExported accessorOpenBao creation-response field to compare
Direct tokenThe issued token's accessorresponse.auth.accessor
Wrapped tokenThe inner token's accessorresponse.wrap_info.wrapped_accessor
Wrapped personal-credential readThe wrapping token's accessor; Bouncer can revoke it while unusedresponse.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:

AreaKinds
Requestsrequest_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
Grantsgrant_expired, grant_revoked, grant_suspended, review_due, review_confirmed
Devicesdevice_paired, device_revoked
Requestersrequester_created, requester_key_issued, requester_disabled
Admin and configkill_switch, config_loaded, policy_loosened
Valuessecret_written, secret_write_failed, secret_viewed, secret_view_refused
Downstream credentialsdownstream_rotation_due, downstream_rotated
Personal credentialssharing_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_:

KindWhat the device said
reported_screenshotA screenshot was taken
reported_capture_started, reported_capture_stoppedThe 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_copyThe 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_failedWindows 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:

PlatformScreenshotRecording or mirroringCopy
Android 14 and laterReportedReported on Android 15 and laterReported
Android 9 to 13Not detectedNot detectedReported
iPhoneReportedReportedReported
WindowsNot detectedNot detectedReported

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:

FieldMeaning
event_idAn ID the app made for the event. The same event sent twice is recorded once
observed_atWhen the device saw it. The entry's own at is when the server received it
screenstored_value (a saved secret was showing; the entry names the resource) or draft (a form; no resource)
protectionblocked: 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_idThe 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.

OptionMeaning
--since, --untilA 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.

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

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:

  1. On every host, remove Bouncer's CA trust (Retire a host).

  2. From the same role-kit folder, run:

    ./ssh/setup-ssh.sh --teardown
    

    It needs the matching kit.env, ssh/ssh-resources, the bao CLI 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.

  3. 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.

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

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 saysWhat 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 failedThe 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 ignoredRemove 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 deniedThe 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 installPostgreSQL'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 migrationsYou 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 mentionsWhat to do
isn't valid and a settingFix that setting. The message names it, for example defaults.durations: min (2h) is more than max (1h)
duplicate mapping keyA key appears twice in the same block
The resource ... is new or The openbao settings changedThese need a recreate and health check: docker compose up -d --force-recreate --wait --wait-timeout 120 bouncer

Requesters get errors

The requester seesLikely cause
Exit code 6, the key isn't acceptedThe requester was disabled, or its key was replaced. Check bouncer-admin requester list
Exit code 6, not_requestableThe requester isn't in the resource's requesters list, or the resource doesn't exist
Exit code 6, duration_not_permittedThe 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_failedBouncer 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 4Nobody 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 sent lines 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 list shows the device's status.
  • The phone can't approve, only deny: the resource has require_hardware_uv: true and 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 ps and the last 100 lines of docker 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.

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

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

ProtectionWhat it doesWhere it's enforced
Signed approvalsOnly a signature from a paired device's approval key approves. A requester key or device token can never approveThe server checks every signature, challenge and policy rule in one transaction
Exact scopeThe 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 requestThe device recomputes the hash and refuses to sign if it differs; the server checks it again
Short tokensEach OpenBao token lasts minutes (5 by default), can read only that resource's paths, and never outlives its grantOpenBao, through the role kit's policies and token roles
Scoped OpenBao authorityThe 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 approvalsOpenBao policies; the role kit's check.sh checks their scope
RevocationA 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 metadataPostgreSQL 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 credentialThe server's storage and API paths; this is not end-to-end encryption against the server operator
Admin off the networkAdmin commands go over a local Unix socket, never the networkFile permissions on the server's machine

Pages in this section

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

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

TimeWhat it limitsDefaultSet by
Time to answer (request_wait)How long a request waits for a decision. After it, the request expires and nothing is granted15 minutes (1 minute to 24 hours)The config file
Access durationHow long the grant lasts, from the moment of approvalWhat 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 lasts5 minutes (30 seconds to 1 hour), and never past the grant's endThe 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 MCP revoke_grant tool);
  • 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.

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

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

PlatformWhere the approval key livesWhat it needs before signingLabel
Android, standard keyThe 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 signatureplatform-hw-unlocked
Android, biometric keyThe same, with the key bound to biometricsA strong biometric check for every signature. Adding a new fingerprint or face makes the key unusable, so it has to be replacedplatform-hw-uv
iOSThe Secure EnclaveFace ID or Touch ID for every signature, with no passcode fallback. Changing enrolled biometrics makes the key unusableplatform-hw-uv
WindowsA Windows Hello passkey, through Windows' WebAuthn APIWindows Hello (PIN or biometric) for every signatureplatform-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: true to 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-uv in 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 meet require_hardware_key, but no real PC has passed that check yet, and keys enrolled before it stay unattested. These keys need pairing.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:

ClaimCan the server prove it?
The signature was made by the enrolled keyYes, always
An Android key is in secure hardwareOnly with key attestation (below)
An Android or iOS key requires biometricsAndroid: only with key attestation. iOS: no; it's the app's word
A Windows Hello key is in a TPM0.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_attestationEffect
prefer (default)A chain that verifies marks the key as attested. A phone without one still pairs, unattested
requiredA 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
offThe 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.

StatusWhat it means for the current key
verifiedThe server verified Android-key or TPM evidence for this enrolled key and enrollment challenge
unverifiedEvidence is absent or deliberately unchecked; this includes ordinary iOS and macOS claims
unsupportedThe evidence has no verifier, or there is no approval-key proof path
failedSupported 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.

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

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 exec with 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.

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

Self-approval and separation of duties

Who can do what

RoleCanCan't
Requester (a key)Ask, follow its own requests, use its own grants, end its own grantsApprove 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 logApprove 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 grantsApprove 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 allowedApprove 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_loosened and 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.

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

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

ThreatHow Bouncer handles it
A requester approves its own requestA requester key can't approve. Only a device's signature does
A replayed approvalEach approval signs a single-use challenge, valid for one request and revision. A second use is refused
An approval moved to another requestThe 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 anotherThe instance ID is inside every signature
Approval by someone who isn't an approverThe server checks the approver list from the config on every decision
Access outliving its approvalEvery check compares the server's clock with the grant's end. Tokens never outlive the grant
A restart bringing access backExpiry and revocation are stored and computed, so they survive restarts. Used challenges and pairing codes stay used
A slow or failing revokeBouncer 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 quietlyA reload that loosens policy is logged and announced. Standing grants are suspended when their policy changes
Secrets in push notificationsPushes carry only an event ID. Details are fetched from your server
Secret values in Bouncer's databasePostgreSQL 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 codesCodes 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 elsewhereThe 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 phoneRevoke the device; it can't approve or see anything afterwards (Recovery)
Bouncer itself compromisedThe 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

ThreatWhy
A value already readCan't be recalled. Rotate it (Copied secrets)
An unlocked, paired phone in the wrong handsWith 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 keyAndroid 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 resourceOpenBao 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 tokensAnyone holding a token can use it until it expires (minutes)
Which machine is askingThe 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 machineWhoever 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 accessA 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 bindingA grant can't yet be tied to one requesting machine
Revocation timing under loadRevokes 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.

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

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; keep ceilings.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 resources file.
  • 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 --file and self-update are Linux only. exec --stdin works on Linux and Windows.
  • There's no public package repository for the Linux .deb and .rpm yet, 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.sh for 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.

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

Reference

Complete lists, for looking things up. The task pages in Integrate and Operate explain how to use them.

Everything here describes Bouncer 0.5.7. The page footer identifies the source commit.

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

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-admin calls 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 is 409 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=N and GET /v1/events?wait=N wait up to N seconds (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) and POST /v1/pair (the new device token). Three admin responses carry one too: POST /admin/v1/requesters and POST /admin/v1/requesters/{requester_id}/key (the requester's new key), and POST /admin/v1/pairing-codes (a one-time pairing code). These don't set no-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) and POST /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.

CodeHTTPMeaning
unauthenticated401No credential, or not a valid one
forbidden403Valid credential, but not allowed to do this
not_found404No such object, or not visible to this caller
invalid_body400The body doesn't match the schema
idempotency_conflict409Same idempotency key, different body
rate_limited429Too many requests; see Retry-After
requester_disabled403This requester is disabled
device_revoked403This device is revoked
not_requestable403This requester may not ask for this resource
duration_not_permitted422The duration isn't allowed for this resource. Never clamped
reason_invalid422The reason is empty, too long, or has control characters
not_an_approver403This person doesn't approve this resource
self_approval_not_allowed403This resource needs a different approver
channel_not_permitted422Notification approval isn't allowed here, isn't opted in on this device, or the duration differs from the requested one
confirmation_missing422Longer 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_pending409The request was already decided, expired or cancelled
revision_mismatch409The request changed since the device fetched it
scope_mismatch422The statement's scope hash doesn't match the request
audience_mismatch422The statement is for another Bouncer
challenge_invalid422The challenge is unknown, used, expired, or for another device or request
statement_not_canonical422The statement bytes aren't canonical JSON
statement_invalid422The statement isn't base64url, isn't the right kind, or has fields the contract doesn't define
signature_invalid422The signature doesn't verify against this device's key
unsupported_signature_format422A signature format the server doesn't accept yet
key_mismatch422The 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_accepted422The key's assurance or user verification doesn't meet the resource's policy
grant_not_active409The grant has expired, been revoked or been suspended
issuance_failed502Bouncer couldn't release a credential. The detail says whether a token may have been issued
write_failed502OpenBao didn't save a store request's values. The grant is used up anyway; file a new request
view_off403The resource doesn't allow viewing its value on a device
no_grant403A device view needs an active read grant held by one of this person's own human requesters; an agent's grant never counts
grant_expired403The person's grant for this resource has ended or been suspended
grant_revoked403The person's grant for this resource was revoked
store_only_grant403The person's only grant is a store request's, which saves values and never reads them
wrong_person403The active grant for this resource is another person's
not_found_in_backend404OpenBao has no value at the resource's path yet
credential_expired409The 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_conflict409The lifecycle operation named a version that is no longer current; nothing was changed
prune_not_confirmed409A 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_off403The credential has no version history (lifecycle is off)
pairing_code_invalid422The pairing code is unknown, used or expired
proof_required422This platform pairs with an approval key, so a pairing proof is required
config_invalid422The config file was refused; the old one stays loaded
backend_sealed503The 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_unreachable503The server is running, but can't reach OpenBao. An outage, not a refusal. Comes with Retry-After
backend_auth_failed503The 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_unavailable503The 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_provisioned503This 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.
internal500Something went wrong on the server

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

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, h or d (90s, 15m, 6h, 7d).
  • Booleans are only true or false.
  • The file holds no secrets: only the paths of files that do.

Top level

KeyRequiredMeaning
versionyesMust be 1
instanceyesSee below
peopleyesAt least one person
defaultsnoPolicy defaults for every resource
openbaoyesHow Bouncer reaches OpenBao
pairingnoWhich approval keys may pair
pushnoFirebase push, or null for none
resourcesyesAt least one resource
groupsnoNamed groups of people, for personal credential sharing
personal_credentialsnoStorage areas for people's own credentials

instance

KeyMeaning
idLower-case letters, digits and hyphens. Goes into every signed statement. Never change it once devices are paired
nameDisplay name
urlhttps://host[:port], the address apps and requesters use. Carried in pairing codes

people

A list of:

KeyMeaning
idLower-case ID, used in approvers, --person and --owner. Each person gets a human requester of the same name
nameDisplay name

defaults

Each of these can also be set on a single resource, which then overrides the default.

KeyDefaultAllowedMeaning
request_wait15m1m to 24hHow long a request waits for a decision
credential_ttl5m30s to 1hHow 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 repeatsThe quick choices on the approval screen
durations.min1m1m to 365dThe shortest custom duration
durations.max365d1m to 365d, at least minThe longest custom duration
durations.alwaystrueWhether standing grants may be approved. The Bouncer project hasn't decided the policy for standing grants yet. Set this to false
durations.always_review90d1d to 365dHow often a standing grant must be re-confirmed
self_approvaltrueWhether people may approve their own requests and their own agents'
notification_approvaltrueWhether approving from a notification is allowed (each device must also opt in)
require_hardware_uvfalseWhether only biometric hardware keys (platform-hw-uv) may approve
require_hardware_keyfalseIntroduced 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

KeyMeaning
addresshttp(s)://host[:port], as both the server and requesters reach OpenBao
ca_fileA PEM CA bundle for OpenBao's certificate, or null
kit_prefixThe 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.mountThe role kit's AppRole mount. Must start with the kit prefix and a dash (bouncer-approle)
approle.role_id_fileThe file holding the role_id (/run/secrets/bouncer-role-id in the compose kit)
approle.secret_id_fileThe file holding the secret_id
ssh.approle.mount, .role_id_file, .secret_id_fileThe 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

KeyDefaultMeaning
allow_software_keysfalseAllow approval keys kept in software. For test setups only
allow_user_verified_keysfalseAllow phone keys that need biometrics for every signature (platform-hw-uv). Needed for iPhones
allow_webauthn_keysfalseAllow Windows Hello keys
require_verified_approval_keysfalseIn 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_attestationpreferrequired, prefer or off (Device keys)
android_packagecom.s6studios.bouncerThe Android app an attestation must name
android_signing_cert_sha256the official upload certificate'sThe 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:

KeyMeaning
fcm.project_idThe Firebase project ID
fcm.service_account_fileThe service-account key file, such as /run/secrets/fcm-service-account.json
fcm_alsoNeeds 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:

KeyRequiredDefaultMeaning
idyesLower-case letters, digits and single dashes, up to 40 characters. Unique. Not starting with pc-
nameyesDisplay name
kindyesstored_secret, stored_api_key or ssh_host
descriptionnononeShown to requesters and approvers
foldernoUnfiledFolder names joined by /
credential_typenononeOne 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
kvyes, except for ssh_hostA list of mount and path (without data/). An ssh_host has none
fieldsnononeField names shown to requesters. Names only
approversyesPerson IDs
requestersnoany active requesterRequester names, or ["*"] for any
request_wait, credential_ttl, durations, self_approval, notification_approval, require_hardware_uv, require_hardware_key (from 0.5.7)nofrom defaultsAs in defaults
allow_writenofalseAccept store requests. Needs exactly one kv entry and write in the role kit's line
lifecyclenofalseKeep 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
viewnooffoff, 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_viewnofalseOlder form of view: approver. Give one or the other, not both
downstream.systemwith downstreamThe other system's name
downstream.kindwith downstreamstatic_token
downstream.expires_atnononeWhen the credential expires at its system, as an RFC 3339 time
ssh.principalfor ssh_hostThe one account on the host: lower-case letters, digits, _, - and ., up to 32 characters, and not root
ssh.bind_source_addressnotrueBind 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:

KeyDefaultMeaning
idThe namespace's ID
labelfrom the ID, such as "Personal storage"The name the apps show. Must differ from every other namespace's, ignoring case
kv.mount, kv.prefixWhere 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
creatorseveryonePeople or groups who may create here
fields.namesanyThe only field names allowed
fields.max8Fields per credential, 1 to 32
per_owner50Credentials per person, 1 to 1000
lifecyclefalseEnable 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
ceilingsrequiredThe block must be present, even if empty (ceilings: {})
ceilings.credential_ttl, ceilings.durationsfrom defaultsThe most a credential in this area may allow
ceilings.revealfalseWhether values may be viewed in the apps
ceilings.always_approvedfalseWhether an owner may set a credential to be approved automatically. Keep it false: this mode has two open problems (Approvals and access duration)

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

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.

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

Environment variables

bouncer (the CLI)

VariableMeaning
BOUNCER_URLThe Bouncer server's address. --server overrides it. Without either, the first line of ~/.config/bouncer/server is used
BOUNCER_KEY_FILEThe file holding the requester key. --key-file overrides it
BOUNCER_KEYThe requester key itself, used when no key file is given. A file is safer
BOUNCER_CA_FILEA PEM file of extra CA certificates, trusted for both Bouncer and OpenBao
HTTPS_PROXY, ALL_PROXY, NO_PROXYProxy for HTTPS calls and hosts that bypass it. Lower-case names work too. HTTP_PROXY is never used
XDG_CONFIG_HOMEWhen 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_FILEWhere the system's CA certificates are, if not in the usual places
BOUNCER_UPDATE_FEEDThe 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

VariableMeaning
BOUNCER_URLRequired. The Bouncer server's address: https://, or http:// to this machine only. Unlike bouncer, it does not read ~/.config/bouncer/server
BOUNCER_KEY_FILERequired. The agent's key file. The key itself is never read from the environment
BOUNCER_CA_FILEExtra CA certificates, as for bouncer
HTTPS_PROXY, ALL_PROXY, NO_PROXYProxy settings as for bouncer, including lower-case names

bouncer-admin

VariableMeaning
BOUNCER_ADMIN_SOCKETThe admin socket. --socket overrides it. Default /run/bouncer/admin.sock
NO_COLORSet to stop device pair forcing white-on-black colours for the QR code

bouncer-server

VariableMeaning
DATABASE_URLThe PostgreSQL connection URL. Never logged. The compose kit leaves the password out of it and supplies it separately
PGPASSWORDThe database password, when DATABASE_URL has none. The compose kit's entrypoint sets it from the password file
BOUNCER_ADMIN_SOCKETWhere to create the admin socket. --admin-socket overrides it
RUST_LOGLog filter, including full EnvFilter directives. Default info; levels include error, warn and debug
BOUNCER_TEST_FCM_ENDPOINT, BOUNCER_TEST_FCM_TOKEN_URITests 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.

VariableDefaultMeaning
BOUNCER_CONFIG/etc/bouncer/bouncer.yamlThe config file inside the container
BOUNCER_LISTEN127.0.0.1:8080The address the server listens on. From BOUNCER_PORT in .env
BOUNCER_DB_PASSWORD_FILE/run/secrets/bouncer-db-passwordThe database password file
BOUNCER_WAIT_FOR_OPENBAOemptyIgnored 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.

VariableDefaultMeaning
BOUNCER_PORT8080The port on 127.0.0.1
BOUNCER_CONFIG_DIR/etc/bouncer/configThe folder holding bouncer.yaml, mounted read-only at /etc/bouncer
BOUNCER_SECRETS_DIR/etc/bouncer/secretsThe folder holding the secret files
BOUNCER_IMAGElocalhost/bouncer-server:localThe server image
BOUNCER_VERSION, BOUNCER_REVISIONlocal, unknownLabels for a local build
BUILD_JOBSemptyParallel compile jobs, for a small machine
BOUNCER_WAIT_FOR_OPENBAOemptySee above
RUST_LOGinfoThe server's log level
COMPOSE_FILEcompose.yamlAdd compose.push.yaml, compose.push2.yaml or compose.ssh.yaml, separated by :

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

Ports and files

Ports

PortWhereWhat
443Your HTTPS front endWhat apps and requesters connect to (instance.url)
8080127.0.0.1 on the serverThe Bouncer server's plain HTTP listener. Change with BOUNCER_PORT
8200OpenBaoOpenBao's API. The deploy/openbao kit listens on 127.0.0.1:8200 and puts HTTPS in front, on 8443 in its README
nonePostgreSQL has no network; the server uses its Unix socket
noneThe 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.

PathMode and ownerWhat
~/bouncerThe 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.yaml0644The config file
/etc/bouncer/config/openbao-ca.pem0644OpenBao's CA, if needed
/etc/bouncer/secrets/0700, user 10001The secret files
/etc/bouncer/secrets/bouncer-role-id0400, user 10001OpenBao AppRole role_id
/etc/bouncer/secrets/bouncer-secret-id0400, user 10001OpenBao AppRole secret_id
/etc/bouncer/secrets/bouncer-db-password0400, user 10001The database password
/etc/bouncer/secrets/bouncer-ssh-role-id0400, user 10001SSH signer AppRole role_id, if SSH is on (compose.ssh.yaml)
/etc/bouncer/secrets/bouncer-ssh-secret-id0400, user 10001SSH signer AppRole secret_id, if SSH is on
/etc/bouncer/secrets/fcm-service-account-2.json0400, user 10001Second Firebase key while moving projects (compose.push2.yaml)
/etc/bouncer/secrets/fcm-service-account.json0400, user 10001Firebase key, if push is on
/var/backups/bouncer/0700Daily backups from the timer
/usr/local/libexec/bouncer-backup0755backup.sh, installed for the timer
/etc/systemd/system/bouncer-logical-backup.{service,timer}0644The backup timer

Inside the server container

PathWhat
/etc/bouncer/The config folder, read-only
/run/secrets/<name>The secret files, read-only
/run/bouncer/admin.sockThe 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

VolumeWhat
bouncer_pgdataPostgreSQL's data. docker compose down -v deletes it
bouncer_pg-socketPostgreSQL's socket, a small in-memory volume
bouncer_bouncer-runThe admin socket

On a requester's machine

PathModeWhat
~/.local/bin/bouncer, ~/.local/bin/bouncer-mcp0755The binaries (or /usr/local/bin, or /usr/bin from a package)
~/.config/bouncer/0700Settings folder
~/.config/bouncer/serverThe server's address
~/.config/bouncer/key0600The requester key
%LOCALAPPDATA%\bouncer\server, %LOCALAPPDATA%\bouncer\keyprivate to the Windows accountWindows CLI settings and encrypted key

The role kit

PathWhat
deploy/openbao-role-kit/resourcesYour list of secrets. Keep it, in your own repository; the emergency stop needs it
deploy/openbao-role-kit/kit.envYour 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.

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

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.

PartRelease files
Androidbouncer-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 appbouncer-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 MCPinstall.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 MCPinstall-windows-cli.ps1 and bouncer-cli-0.5.7+34-x86_64-windows.zip
Serverbouncer-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 releaseSHA256SUMS

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 wantThe filesHow to install
The Android appbouncer-android-0.5.5+32.apkInstall on Android
The Android internal test build (testers only)bouncer-android-0.5.5+32-internal.apkThis 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 appbouncer-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.zipInstall on Windows
The CLI and MCP server on Linuxinstall.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.rpmInstall the CLI
The CLI and MCP server on Windowsinstall-windows-cli.ps1 with bouncer-cli-0.5.5+32-x86_64-windows.zipInstall the CLI
The serverbouncer-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 serverInstall the server
The iPhone and Mac appsNoneiPhone 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 with docker 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.

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

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

PlatformStatusWhat you can installNotes
Android 9 or laterBetaAn 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 11BetaA test-signed installer (MSIX), or a portable ZIP, from the private GitLab releaseRequests 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 testingNothing yet. iOS 0.5.7 is in internal TestFlight for S6 Studios' own testing (see above)iPhone and Mac
MacIn developmentNothing yet
Linux desktopNot plannedUse the command-line tools on Linux.

Tools for requesters and administrators

ToolStatusWhat you can install
bouncer and bouncer-mcp on Linux (x86_64)BetaA 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.1A zip with a per-user installer. Not code-signed yet. Install the CLI
bouncer-adminBetaRuns on the Bouncer server's own machine

The server

PartStatusNotes
Bouncer server, with OpenBaoBetaThe 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.

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

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

VersionMain changes for app users
0.5.7Reconnecting 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.6Android, 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.5Android 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.4Android 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.3Windows 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.2Android 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.1Requests 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.0Redesigned 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.7Longer access with its end date shown. Personal credentials, shared with people and groups.
0.3.6A simpler New request form, with a single resource picker.
0.3.5Show value appears only where the server will show the value. Clearer wording when a save or view takes too long.
0.3.4A fix: Show value shows the value again.
0.3.3The credential Library. Grants of up to 7 days with short-lived tokens. Saving and editing a secret from the app.
0.3.2Viewing a secret on a phone or PC where a resource allows it. Android pairings survive app updates.
0.3.1SSH access with short-lived certificates.
0.3.0The 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.

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

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

ComponentVersion in this sourceDistribution status
Server, Linux and Windows CLI, admin and MCP0.5.7Private GitLab release; production remains on build 0.3.8+25
AndroidversionName 0.5.7, versionCode 34; internal versionName 0.5.7-internalPrivate GitLab release; the internal build is on Firebase App Distribution for S6 Studios' own testing; no Play submission
iOSshort version 0.5.7, build 34Internal TestFlight for S6 Studios' own testing; no App Review submission
Windows app0.5.7; beta MSIX 0.5.34.0, internal 0.5.34.1, Store 1.0.34.0MSIX 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-config exits 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_ttl plus 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_changed approval-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-admin from 0.5.6 or earlier stops at the first token_issued, backend_revoke, resource_provisioning_changed or ssh_ca_changed entry. 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 by id. 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/health is 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: required applies 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 set pairing.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

  1. 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.
  2. Upgrade the role kit first. Use this release's kit for the P1 to P6 procedure, preserving the existing resources, kit.env and 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 to bouncer-server. Investigate unrelated policy drift.
  3. Run the candidate server's --check-config next, 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.
  4. 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_unavailable with Retry-After and recovers without a restart; CLI/MCP use outage exit 16. A resource provisioning gap can leave health 200 while that resource is refused.
  5. 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 sets require_hardware_key requires 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.
MigrationWhat it adds
0017_token_audit.sqlToken audit metadata for issuance and backend revoke export records.
0018_event_resource.sqlThe resource association for provisioning events.
0019_ssh_ca_keys.sqlRetained 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: required applies only to devices that declare Android, and require_hardware_uv and require_hardware_key can't by themselves prove hardware on every platform. This affects existing servers and earlier versions too, wherever pairing.allow_user_verified_keys is true. 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, reports STALE and 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.

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

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/health sees 503 with one of those codes, not 502.
  • The container shows unhealthy meanwhile, and Docker doesn't restart it.
  • BOUNCER_WAIT_FOR_OPENBAO is now ignored. Remove it from .env.
  • The bouncer command 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.

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

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.md says sha256sum -c SHA256SUMS, but that file lists every release file. If you downloaded only the server files, run sha256sum -c SHA256SUMS --ignore-missing instead. Every downloaded file must say OK (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.

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

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.

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

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.

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

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.

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

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).

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

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_type to bouncer.yaml. Servers older than 0.5.0 refuse it: reload is refused and restart fails.
  • To roll back, remove credential_type from 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: false and ceilings.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.

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

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.

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

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.

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

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

  1. Ask your administrator to run bouncer-admin device pair for 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.
  2. 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.
  3. Check the server and your name, name the device, and tap Pair.
  4. 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>.

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

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>.

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