Manual for Bouncer 0.5.7. Chapters state version and distribution limits. Source cdd3b59, site build 20 November 2026. Your server or app may run an earlier version.
On this page
When Bouncer is unavailable
This page is for the person who runs a Bouncer server. It explains what people and agents see when Bouncer can't serve, what each message means, and who has to act.
These are outages, not attacks. When a trusted internal client (an agent, the CLI, the app) reports one of the errors below, look for an operational fault first: a sealed vault, a stopped container, a reboot. Nothing here means a key was rejected or someone was refused. Real refusals look different and haven't changed: HTTP 401 or 403, exit code 6, and in the app "This phone was removed" or "Your Bouncer server didn't accept that".
What changes in 0.5.6
The OpenBao readiness changes in this section start in 0.5.6.
The database check described next is from 0.5.7.
Check the server and client builds before expecting the new database message
and exit code. An unreleased source build can still report 0.5.6+33, so
identify it by its source revision as well as its version.
For example, a reboot can leave OpenBao initialised but sealed. Up to 0.5.5, bouncer-server checked OpenBao at start-up and exited when it couldn't log in, so Docker restarted it again and again. With nothing listening, tailscale serve answered every client with a bare 502. Agents saw "The server answered HTTP 502", and a sealed vault was indistinguishable from a broken server.
From 0.5.6 the server stays up when OpenBao is sealed, out of reach, or refuses the server's own login (or, with SSH hosts, the SSH signer's login). Until OpenBao is ready, it answers almost every public call, GET /v1/health included, with HTTP 503 and a problem code that says which of the three it is, plus a Retry-After header. It issues and signs nothing meanwhile. The calls that only take access away, revokes and cancels, still work while PostgreSQL is available (see below). Once OpenBao is ready again it notices by itself, on the next call (at most every 5 seconds) or within a minute. It never unseals OpenBao, and it doesn't retry an unseal. Unsealing stays an operator's job. Automatic unsealing with the VM's TPM is described in OpenBao for Bouncer, but hasn't been verified for this manual.
Some login problems are setup mistakes, not outages, and they still stop start-up with a message saying what to fix: a Bouncer login, or an SSH signer login, with wider powers than the role kit gives (the root policy, for example). In 0.5.6 and earlier, a missing token role for one resource also stops the whole server; from 0.5.7, only that resource is refused (see One resource is not provisioned). If the server started while OpenBao was sealed or out of reach, it can only find out that a login has too much power once OpenBao answers. It then answers 503 backend_auth_failed, and issues and signs nothing, until you fix the login and restart the server.
Database outages from 0.5.7
From 0.5.7, a running server also checks PostgreSQL.
A failed database readiness probe returns 503 database_unavailable
with Retry-After: 5. The server stays up and recovers on a later check
without a restart. Starting the server still needs the database to apply
migrations and load state.
When both PostgreSQL and OpenBao are down, the database error comes first.
Once the database recovers, a remaining OpenBao problem appears as
backend_sealed, backend_unreachable or backend_auth_failed. Work through
both faults; fixing PostgreSQL alone does not unseal or repair OpenBao.
The health checks page
explains the probe and its cache.
In 0.5.6 and earlier, health does not check PostgreSQL and can remain 200 during a database outage. Keep using the database diagnostic route for those versions, and to find the cause on newer versions.
One resource is not provisioned
From 0.5.7, HTTP 503 resource_not_provisioned means that one resource's OpenBao token role or policy is missing or wrong. It comes with Retry-After: 5. Other resources can still work, and health can stay 200 while showing an unprovisioned count. Apply and check the current role kit, then run the configuration check until it exits 0. If the fix adds a new token role, restart the server. The CLI and MCP make one call, without retrying, and report resource_not_provisioned with a message telling the operator to repair the role kit. The CLI exits 7; an MCP tool returns an error to the agent. Exit 7 now includes a server-side setup problem, as well as local configuration problems (Exit codes).
If the kit's permissions are older, or an older kit wrote a policy, the configuration check reports upgrade_needed and exits 4 instead, and the server keeps issuing tokens as before. Upgrade the kit so the check can finish. A sealed OpenBao, a network fault or a refused server login is still reported as an outage (backend_*), never as an unprovisioned resource. This was checked against the source for 0.5.7. The full recovery sequence hasn't been run end to end.
What each message means
| Server answer | bouncer CLI (exit code) | MCP tool error | Apps | What's wrong | Who acts, and how |
|---|---|---|---|---|---|
503 database_unavailable (from 0.5.7) | "The Bouncer server is running, but it can't reach its database (PostgreSQL) …" (16) | The same, plus "… the Bouncer operator needs to check PostgreSQL. Don't retry in a loop" | "Your Bouncer server can't reach its database" | PostgreSQL is stopped, unreachable, or cannot answer Bouncer's readiness probe | The operator follows Diagnose a database outage. The apps, including the Windows check before pairing, ask for the server's database to be fixed |
503 backend_sealed | "The Bouncer server is running, but its vault (OpenBao) is sealed, so it can't issue anything. This is an outage, not a refusal: the operator must unseal OpenBao." (12) | The same, plus "This isn't a denial … Tell the human that the Bouncer operator needs to unseal OpenBao. Don't retry in a loop" | "Your Bouncer server's vault is sealed" | OpenBao restarted (a reboot, a container restart) and is sealed | The operator unseals OpenBao: OpenBao for Bouncer, step 3, or the deployment's own unseal procedure. Nothing to do on the clients |
503 backend_unreachable | "The Bouncer server is running, but it can't reach its vault (OpenBao) …" (13) | The same, plus "… needs to check OpenBao. You can try again in a few minutes" | "Your Bouncer server can't reach its vault" | OpenBao is stopped, crashing, or not reachable from the Bouncer server (network, DNS, TLS, or a proxy in front of OpenBao) | The operator checks that OpenBao is running and reachable at the config's openbao.address |
503 backend_auth_failed | "The Bouncer server is running, but its vault (OpenBao) refused the server's own login … not a refusal of your key" (14) | The same, plus "… needs to fix the server's OpenBao login" | "Your Bouncer server can't sign in to its vault" | OpenBao is unsealed, but refused the server's AppRole login: the secret_id expired or was destroyed (for example by the role kit's emergency stop), or the role_id or secret_id file is missing. The same for the SSH signer's own AppRole, with SSH hosts configured. Or, after OpenBao came back, a login with the wrong powers (see above) | The operator replaces the secret_id, or fixes the file. The server reads the file only when it logs in to OpenBao again; with the Compose kit, recreate the container as the maintenance procedure shows, to remount a replaced file and verify the new login. A login with the wrong powers needs the role kit's setup.sh --verify and a restart |
| A bare 502, 503 or 504 (no Bouncer error in the body) | "Can't reach the Bouncer server: the proxy in front of it got no answer (HTTP 502). The server may be down or restarting." (15) | The same, plus "… needs to check that the server is running. You can try again in a minute" | "Your Bouncer server isn't answering" | tailscale serve (or another proxy) is up, but bouncer-server isn't answering behind it: stopped, restarting, or failed at start-up | The operator checks the container: docker compose ps, then docker compose logs bouncer |
| No connection at all | "Can't reach the Bouncer server (…). Check the address, and that Tailscale is on" (1, current CLI wording) | The same | "Can't reach your Bouncer server" | The client can't reach the address: network, DNS, a required VPN or the whole machine is down. The CLI mentions Tailscale even when your deployment uses another network | Check the configured address and your deployment's network path. Tailscale is needed only if the operator chose it. If others can't reach the server either, the operator checks the machine |
Bouncer's 503 answers are application/problem+json. The detail is the server's own sentence, without credentials or backend connection details. The database readiness log also omits the database address, credentials and driver error.
The CLI's HTTP client doesn't retry a backend_* answer, because it needs an operator. It does retry a bare 502, 503 or 504 a few times, since a restarting server may be back in seconds. The full exit-code table is in Exit codes and errors.
From 0.5.7, database_unavailable uses the CLI's bounded
503 retries, up to four attempts per HTTP call, respecting Retry-After. MCP
reports the outage to the agent and asks it to tell the human, rather than
keep calling the tool in a loop.
The readiness check
From 0.5.6, GET /v1/health needs no credential and checks the process and OpenBao readiness:
- 200 with
"status":"ok": the server is up and OpenBao is ready. From 0.5.7, the database probe has passed too. - 503 with
backend_sealed,backend_unreachableorbackend_auth_failed: the server is up, OpenBao isn't ready. - 503 with
database_unavailable, from 0.5.7: the server is up, PostgreSQL isn't ready. This takes precedence over an OpenBao outage. - 502 with an empty body, or no answer: the server isn't running behind the proxy, or the machine is unreachable.
In 0.5.6 and earlier, health does not check PostgreSQL. It can stay 200 and the Bouncer container can stay healthy while a database outage makes requester calls fail with HTTP 500. Follow Diagnose a database outage to inspect both containers and logs, recover PostgreSQL and verify a real operation. From 0.5.7, the cached readiness probe also needs to pass; a 200 still does not prove every resource can issue a credential.
For example, on the server while OpenBao is sealed (some headers left out):
curl -si http://127.0.0.1:8080/v1/health
HTTP/1.1 503 Service Unavailable
content-type: application/problem+json
retry-after: 30
{"type":"https://contracts.bouncer.invalid/errors/backend_sealed","title":"Bouncer is running, but its vault is sealed","status":503,"detail":"Bouncer is running, but OpenBao, the vault it issues credentials from, is sealed. Nothing can be issued until an operator unseals it. This is an outage, not a refusal.","code":"backend_sealed"}
The container's health check uses the same address, so the bouncer container shows unhealthy while OpenBao isn't ready and, from 0.5.7, while PostgreSQL isn't ready. Docker doesn't restart a container for being unhealthy. A seal, network or database outage recovers on later checks once the dependency is ready. A refused login needs repair; unsafe powers need a restart, and a replaced secret_id file needs the container recreated (Maintenance).
A monitor that calls /v1/health through the proxy can distinguish a healthy answer, a 503 with a Bouncer dependency code, and a bare gateway error or no answer. Inspect the problem code to distinguish OpenBao from PostgreSQL on builds from 0.5.7. Keep monitoring PostgreSQL separately and OpenBao's own /v1/sys/health as well. The latter doesn't depend on Bouncer, and tells "sealed" (503) from "not initialised" (501). Health checks has the full list.
bouncer-admin still works while OpenBao isn't ready, because calls through the admin socket don't wait for OpenBao. You can list requesters and devices, and run the kill switch. These operations still need the database.
Revokes are accepted during an OpenBao outage while the database is available. Besides the admin socket, these public calls still work while OpenBao isn't ready, because they only take access away:
POST /v1/grants/{id}/revoke(bouncer revoke, the MCP revoke tool, and the app);POST /v1/devices/self/revoke, a device signing itself out;POST /v1/requests/{id}/cancel, cancelling a request that's still pending.
The cutoff is recorded at once, so nothing more is issued for that grant. OpenBao can't revoke a token while it's sealed, so the answer lists each such token as revoke_failed, and bouncer revoke says Bouncer keeps trying. The server revokes them at OpenBao once OpenBao is ready again: it tries after 5 seconds, then less and less often, at least every minute, until each token is revoked or has expired. Each token still ends on its own at the time shown. In 0.5.6 every other public call answers 503. From 0.5.7, authenticated host fetches of GET /v1/ssh/krl also work once Bouncer has stored its SSH CA public key. The remaining public calls answer 503, including the ones that could give access back (a decision, sharing, enabling) and disabling or deleting a personal credential, which needs a fresh challenge.
If PostgreSQL is unavailable, revokes and cancels cannot commit their cutoffs.
From 0.5.7, the database gate refuses these public calls
with 503 database_unavailable too. Do not assume a failed change was
recorded; check and repeat it once the database recovers. For an urgent stop
independent of Bouncer, follow Recovery.
SSH certificates are different. In 0.5.6 a revoke is recorded, but hosts cannot fetch the updated revocation list while OpenBao is unavailable: their fetches answer 503. From 0.5.7, Bouncer builds the list from its database and retained CA public keys, including after a server restart while OpenBao is down. An installation that has never read its CA, including one just upgraded from 0.5.6, needs one successful OpenBao read before it can serve the list. PostgreSQL and Bouncer must still be available; new signing always needs OpenBao. Until a host fetches the list, or the certificate expires, a previously issued certificate can still start new logins. Existing sessions are unchanged. See SSH revocation, or Retire a host for an urgent host-side cutoff.
In the server's log
| The log says | Meaning |
|---|---|
the database isn't ready; answering 503 database_unavailable until it is | From 0.5.7: the PostgreSQL probe failed. Check the database; Bouncer stays up |
the database is ready again | From 0.5.7: the probe passed after an outage. A remaining OpenBao outage can still prevent issuance |
the credential backend isn't ready. The server is starting anyway, and answers 503 backend_sealed until it is | Started while OpenBao was sealed. The reason follows, for example Bouncer's "OpenBao is sealed" |
the credential backend isn't ready. Answering 503 backend_unreachable until it is | OpenBao stopped answering while the server ran |
the credential backend is ready again | OpenBao is back, and the server issues again |
the credential backend answers again, but fails the start-up check | OpenBao came back, but Bouncer's login now has the wrong powers. Nothing is issued. Fix it (setup.sh --verify in the role kit) and restart the server. Logged once |
the SSH signer answers again, but fails the start-up check | The same for the SSH signer's login, for example the root policy. Nothing is issued or signed. Fix it (the SSH role kit) and restart the server |
the SSH signer isn't ready. Answering 503 backend_auth_failed until it is | OpenBao refused the SSH signer's own AppRole login. Replace its secret_id and recreate the Compose container, as in Replace the OpenBao secret_id |
bouncer-entrypoint: BOUNCER_WAIT_FOR_OPENBAO is ignored | Remove that line from deploy/compose/.env. It used to hold the server back until OpenBao was unsealed, which meant clients saw a bare 502 |
BOUNCER_WAIT_FOR_OPENBAO
Up to 0.5.5, setting BOUNCER_WAIT_FOR_OPENBAO=127.0.0.1:8200 made the container's entrypoint wait for OpenBao before starting the server. That avoided the restart loop, but nothing listened while it waited, so clients still got a bare 502. From 0.5.6 the setting is ignored, and the entrypoint logs that it is. Remove it from .env. If you run an older server, it's still better than the restart loop.
How this was checked
- The server's behaviour is from
server/src/readiness.rs, and is tested inserver/tests/availability.rs: starting while OpenBao is sealed, unreachable, or refusing the login (the server's or the SSH signer's); nothing issued while sealed; recovering after unseal; a login with too much power still stopping start-up, and an SSH signer with too much power found after an unseal staying refused until a restart; revokes, a device's own revoke and a cancel accepted while sealed and completed at OpenBao after; OpenBao asked at most once every 5 seconds; each problem logged once; and a 401 still being a 401. - The CLI's and MCP's words and exit codes are from
cli/src/http.rsandmcp/src/tools.rs, with their tests. The apps' are fromapp/lib/ui/copy.dart, tested inapp/test/screens/inbox_test.dartandapp/test/desktop/desktop_screens_test.dart. - The OpenBao and proxy cases in the table were also run end to end on a throwaway stack with fake data only (OpenBao 2.7.2 and PostgreSQL 18.6 in containers, the server, and a stand-in for
tailscale serve), before and after the 0.5.6 change. The transcripts aren't published. - The database case was checked against the source, including the server check and client messages. Automated availability tests cover failure, recovery and an exhausted connection pool; the Compose smoke test stops and restarts PostgreSQL and checks that Bouncer did not restart. We haven't run this case ourselves.
- On 17 November, our test run with fake data also revoked an outstanding token while OpenBao was sealed. After the unseal, the revoke reached
revoke_confirmedbefore the token expired.