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
-internalin the version and "Internal test build: screenshots allowed", with how to send feedback.
For operators
Upgrade order and migrations
- 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.
- Check your requesters' owners against
people:. On its first start, 0.5.9 pauses every active requester whose owner is no longer inpeople:. Scripts and agents using those keys stop until you reassign or disable them. - 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. - Upgrade the server. Its first start applies migrations 0021 to 0028.
Run
bouncer-admin log verifyand checkbouncer-admin status. Then take the chain's head withbouncer-admin log headand keep it off the server. Reviewbouncer-admin requester pausedbefore you turn automation back on. - Update other copies of the CLI, the MCP server and
bouncer-admin, then the apps. Update clients before configuringidentity:on a server people use. An older client cannot enrol on a server that requires browser sign-in.
| Migration | Database change |
|---|---|
0021 | Hash chain over the approval log, including existing entries |
0022 | A saved delivery cursor for each audit-export destination |
0023 | Audit delivery follows the chain's commit order |
0024 | Records which entries written straight into the database have been reported |
0025 | Short-lived, one-use browser sign-in transactions |
0026 | A digest identifies changes to entries written straight into the database |
0027 | Device enrolment transactions and verified sign-in identity and method |
0028 | Paused 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 driftcompares the running config, the file on disk and the file in an optionalconfig_repoGit 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).