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

Manual for Bouncer 0.5.9. Chapters state version and distribution limits. Source d8dfc7c, site build 22 November 2026. Your server or app may run an earlier version.

On this page

Bouncer 0.5.9

Published as a private GitLab release, v0.5.9+36, from commit 02c2140b66e0b154e28d60bc2ad733ddb3550dcd. It has 21 files, all downloaded again after upload and checked against the originals. The source repository and release are private. The Android internal build is on Firebase App Distribution and iOS 0.5.9 is in internal TestFlight, both for S6 Studios' own testing. Updating a client doesn't upgrade its server. As of 22 November 2026, the Bouncer project's own production server runs build 0.5.8+35.

Bouncer 0.5.9 has changes for Android, iPhone, Windows, the command line and the server. The apps keep working while the connection is down, show decisions the server hasn't confirmed yet, and can sign in through your organisation on servers set up for it. The apps show 0.5.9+36 under Settings > About, and bouncer --version prints bouncer 0.5.9+36 (bouncer.v1).

Before you upgrade a server: it applies migrations 0021 to 0028, locks the approval log while it links the existing entries, and pauses requesters whose owner is no longer in people:. The only way back is to restore the backup you took before upgrading. Read For operators first.

Changes in the apps

  • Navigation keeps working while reconnecting (#311, #312). You can change tabs, search and edit local form fields while the server is unavailable. Actions that need the server stay disabled with a reason. The connection bar has a Details button. Settings stays usable while you're offline, and its server details show what happened the last time the app reached the server.
  • Clearer connection failures (#313, #314). The app now tells you which of these it is: the server doesn't recognise this device, the device was removed, or the secure connection (TLS) failed. Opening a notification for an unreachable request shows the reason and lets you move to another screen immediately. When the connection comes back, you keep what you'd typed and any decision the server had already confirmed.
  • Pending approvals and denials stay visible (#305). While the app is waiting for the server to confirm a decision, the request shows that pending state. If the reply is lost, it checks the result rather than presenting the decision as completed. Confirmed outcomes remain visible in open details after the inbox notice has gone.
  • Access and history are easier to follow (#271, #306). Grants now shows current access and history separately. Credential access history loads in pages, searches the complete history, and keeps loaded pages during a refresh. Suspended standing grants remain visible. Credential details include Copy ID, clearer sharing summaries and a recipient search. Recipient searches no longer put what you type in the web address, so it doesn't end up in server or proxy URL logs.
  • Sign in through your organisation (#142). If your server uses sign-in, enter its address and choose Sign in instead of scanning a code. You sign in with a passkey, security key or Windows Hello in the browser (a browser tab on Android, the system sign-in window on iPhone, your default browser on Windows), and the server adds your device. On Windows, turn on Windows Hello approvals afterwards if you want the PC to approve. Sign-in on iPhone hasn't been tried on a real iPhone yet; see Known limits. See Sign in with your organisation. Upgrading doesn't turn sign-in on. Servers that don't use it keep QR and code pairing.
  • Sign-in problems say what to do next. Cancelling, timing out, being refused, and another program using port 49321 each get their own message. Cancelling before the device is added never adds one. If the app can't confirm whether your device was added, ask your administrator to check your devices before you try again.
  • iPhone drafts survive brief app switches (#254). If you switch away for less than 30 seconds, an unsaved new or edited credential can still be there when you come back. It's cleared if you're away longer, if Bouncer sees the phone lock, or if it can't tell whether the phone locked. Secret values you'd shown are hidden again every time you leave or come back. iOS may miss a quick lock and unlock, so a short switch does not guarantee a fresh biometric check. The draft rules explain that limit.
  • Windows hides secret values when you minimise or hide the window. It also hides them when the window loses focus.
  • No more banner in internal test builds (#235). Settings > About shows -internal in the version and "Internal test build: screenshots allowed", with how to send feedback.

For operators

Upgrade order and migrations

  1. If upgrading from before 0.5.8, follow the earlier release notes first, including the role-kit upgrade and verified-key changes. This release does not change the role kit.
  2. Check your requesters' owners against people:. On its first start, 0.5.9 pauses every active requester whose owner is no longer in people:. Scripts and agents using those keys stop until you reassign or disable them.
  3. Keep the current release files and config, take a database backup, and save an audit export (bouncer-admin log export) somewhere off the server. Check the log's size and plan downtime: the first hash-chain migration locks the approval log while it links existing entries. See Upgrade and roll back.
  4. Upgrade the server. Its first start applies migrations 0021 to 0028. Run bouncer-admin log verify and check bouncer-admin status. Then take the chain's head with bouncer-admin log head and keep it off the server. Review bouncer-admin requester paused before you turn automation back on.
  5. Update other copies of the CLI, the MCP server and bouncer-admin, then the apps. Update clients before configuring identity: on a server people use. An older client cannot enrol on a server that requires browser sign-in.
MigrationDatabase change
0021Hash chain over the approval log, including existing entries
0022A saved delivery cursor for each audit-export destination
0023Audit delivery follows the chain's commit order
0024Records which entries written straight into the database have been reported
0025Short-lived, one-use browser sign-in transactions
0026A digest identifies changes to entries written straight into the database
0027Device enrolment transactions and verified sign-in identity and method
0028Paused requesters, owner reassignment prompts and enrolment cutoff markers

The only way back to 0.5.8 is to restore the backup. Before you restore, export the approval log, take its head and keep both off the server, because the restore removes every entry written since the backup. Then stop the 0.5.9 server, restore the backup you took before upgrading, and start 0.5.8 with its own config and release files. Do not edit migration records or reverse SQL changes by hand. A restore loses later enrolments, pauses, revocations and log entries. Keep the off-server audit copy and reconcile access and revocations as Backup and restore describes.

Sign-in settings and the access list

Adding the new identity: section turns on browser sign-in. From then on the server refuses pairing codes, including any you've already handed out. Without it, QR and code pairing work as before.

Sign-in uses Keycloak, an identity provider, to prove who signed in. Each person who signs in needs their own keycloak_subject in people:. Bouncer's access list and resource policies decide who may use Bouncer and who may approve. Directory membership alone never adds a person or grants approval rights.

identity.require_directory_group is off by default. Set it to a Keycloak group's full path, such as /company/platform, and only people in that group can sign in, as well as being in people:. It doesn't add anyone to people:. With it off, Bouncer ignores Keycloak groups.

Set identity.admin_api_url and the server will check with Keycloak that each person's account is still enabled. It checks when a device signs in, when an existing device or one of the person's requesters is used, and again just before it hands over a credential. Answers are cached for up to 60 seconds, and the cache is cleared by reload or restart. Set up the read-only Keycloak client, its secret in OpenBao and the HTTPS address first. If Keycloak says an account is disabled or deleted, or the person has left the required group, the server pauses their requesters and suspends their standing grants. Turning the account back on doesn't unpause them. If Keycloak can't be reached, the server refuses access but doesn't pause anything.

Without identity.admin_api_url, there is no account check: the server doesn't contact Keycloak to check accounts or read the reader secret, so disabling an account doesn't cut off devices that are already signed in. Offboard people explicitly. If people sign in to Keycloak through another provider, such as Entra ID or Google, disabling them there doesn't disable their Keycloak account. Disable that too. See Identity configuration for all settings.

Requester pause and offboarding

Removing a person from people: pauses their active requesters and suspends standing grants, preserving keys, bindings and history. The first start with migration 0028 also pauses requesters whose owners left under an older release. bouncer-admin requester paused lists them, one entry per person who left. A paused requester can't ask for access or fetch credentials, even one whose request was already in progress.

To offboard someone, follow When someone leaves: make sure each resource they approve has another eligible approver, disable their Keycloak account and remove shell and container-admin access, run bouncer-admin person offboard <person>, then remove them from people:, approvers and groups and reload. The command revokes their devices, cuts off pending enrolments, and lists the credentials they were given that you should change. Review bouncer-admin requester paused, then reassign agents and hosts or disable them. A human requester remains bound to its person. Changing owners ends the old access and requires fresh approval. Check that their tokens were revoked and that hosts have picked up the SSH revocations. Any static password or key they could have copied still has to be changed where it's issued.

Adding someone back to people: doesn't unpause their requesters. To give them back, the server must first have loaded a config without that person since the pause, then one with them again. Then run bouncer-admin requester reassign <requester> --owner <same-person> for each one. If you run offboard again, remove and reload the person again before adding them back. See When someone leaves.

Audit chain and export

The approval log gains a hash chain. bouncer-admin log verify checks it; bouncer-admin status reports the last hourly check. Keep a copy of the chain's head (its newest entry and hash, from bouncer-admin log head) off the server: someone able to rewrite the database could also rebuild the chain. log export --hash-input includes the data needed to recompute a copy's hashes, and log verify --against <file> compares that copy with the server.

The new audit_export settings send entries to syslog, a webhook or OpenTelemetry, in chain order, with a saved cursor for each destination. Failed delivery retries with a growing delay. Entries written straight into the database, around Bouncer, are reported separately. Optional hash input contains signed statements and device identifiers, so enable it only for a destination that should receive them. See Audit.

Configuration and availability

  • bouncer-admin config drift compares the running config, the file on disk and the file in an optional config_repo Git work tree. The server only reads that repository. The comparison has a time limit and never holds up a reload.
  • A busy database no longer shows as down straight away. Waits for a database connection have a time limit, and at startup the server says whether the database refused the connection, rejected the login, doesn't exist or didn't answer in time.
  • Revoking a device ends its held request-status poll instead of leaving it waiting for the normal timeout.
  • The server has groundwork for a future notification relay (#147). Nothing changes for users or operators yet.

Known limits

  • Signing in on iPhone hasn't been tried with a signed build on a real iPhone yet. Signing in, making the approval key, saving the enrolment and cleaning up on sign-out all still need checking. Updating an iPhone that's already paired doesn't test any of this.
  • The iPhone draft changes and the latest reconnect and notification changes have only been tested automatically and in the iPhone simulator. They still need checking with a signed build on a real iPhone.
  • As in 0.5.8, no real Windows PC has passed the TPM check yet, and other checks on real devices are still open (#293). The verified-key rules from 0.5.8 still apply.
  • A database restore can lower the SSH revocation-list version below the version hosts retain (#283). Follow the host reset and reconciliation steps in Upgrade and roll back. There is still no SSH gateway or session cutoff for an already open connection (#284).

This manual covers Bouncer 0.5.9. Built from source commit d8dfc7cd3265fd3a7cb58f78cbceb1ed6840d488 (workspace version 0.5.9+36).