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
TLS and networking
The Bouncer server speaks plain HTTP, on 127.0.0.1:8080 by default (--listen). Something on the same machine must put HTTPS in front of it. Apps and requesters always use HTTPS: the CLI refuses plain HTTP to any other machine.
What talks to what
| From | To | Port (defaults) | Notes |
|---|---|---|---|
| Phones, PCs, requesters | Your HTTPS front end | 443 | The address in instance.url |
| HTTPS front end | Bouncer server | 127.0.0.1:8080 | Plain HTTP, on the same machine |
| Bouncer server | PostgreSQL | none | A Unix socket on a shared volume. PostgreSQL has no network at all |
| Bouncer server | OpenBao | 8443 with deploy/openbao, or whatever your OpenBao uses | Use HTTPS. The config accepts plain HTTP too, but then tokens cross the network unencrypted; use it only when OpenBao is on the same machine |
| Requesters | OpenBao | the same | Requesters read secrets from OpenBao directly with the short tokens Bouncer gives them |
| Bouncer server | Firebase (Google) | 443, outbound | Only if push is on |
bouncer-admin | Bouncer server | none | A Unix socket, /run/bouncer/admin.sock in the container |
Nothing in the kit opens a port to the internet. Keep it that way: put Bouncer on a private network or VPN that only your people and machines reach.
What the apps need
The apps need a network path to the address in instance.url, and a certificate they trust for that name. They don't need any particular network product: a LAN, ordinary HTTPS on a private network, or a VPN all work, if your devices can reach the server over them. The apps don't detect, install or require a VPN. Whether people need one is your deployment's choice, so say so in your own instructions if they do.
Before pairing, the Windows app checks the address it's given (The server check on Windows). It asks GET /v1/health with no credential, and stops unless the certificate is trusted by the PC, in date and for the name typed, and the answer is a Bouncer API the app speaks. It never skips certificate checks, never falls back to plain HTTP, and never follows a redirect, so the address people type must be the server's own HTTPS address. A private CA has to be installed in each PC's certificate store (for example by Group Policy) before that PC can pair.
One option: tailscale serve
The kit's examples use tailscale serve, so it's described here. It's one way to put HTTPS in front of the server; your devices then need Tailscale connected to reach it. Any other front end that meets Other reverse proxies works the same for the apps.
Tailscale is a VPN that gives each machine an address on your private network (your "tailnet") and can issue HTTPS certificates for the machines' names. tailscale serve then terminates HTTPS and forwards to a local port.
-
In the Tailscale admin console, turn on MagicDNS and HTTPS certificates.
-
On the Bouncer server:
sudo tailscale serve --bg --https=443 http://127.0.0.1:8080 tailscale serve status -
tailscale serve statusshows the HTTPS address (it ends in.ts.net). Setinstance.urlin the config to exactly that address, then rundocker compose exec bouncer bouncer-admin config reload. -
From another machine on your tailnet:
curl -s https://<the address from step 3>/v1/healthExpected result: the same health answer as on the server itself, with
"status":"ok"and yourinstance.url, which is your.ts.netaddress (the example uses this guide's placeholder):{"status":"ok","instance":{"id":"example-home","name":"Example home","url":"https://bouncer.example.com", ...If
curlcomplains about the certificate, HTTPS certificates aren't on for your tailnet yet (step 1).
Use exactly the form --https=443 http://127.0.0.1:<port>. Never use tailscale funnel, which puts the service on the internet, and never use --tcp or --tls-terminated-tcp, which pass the caller's own headers through.
Why the server trusts 127.0.0.1 as a proxy
Behind a reverse proxy every caller seems to come from 127.0.0.1. The server uses the caller's real address for three things: the rate limit on wrong pairing codes, a device's "paired from" address, and the network address shown on the approval card. So the compose file starts the server with --trusted-proxy 127.0.0.1, and the server takes the address from the X-Forwarded-For header, but only on connections from 127.0.0.1.
The proxy must put the real client address last in X-Forwarded-For, either by replacing the header or appending that address. Bouncer takes the right-most address it does not trust. Tailscale's source code does replace it. The project's tests check the server side, not tailscale serve itself (see How this was checked). The repository's deploy/compose/README.md ("How it was tested") has a check you can run on your own machine.
Anything else on the machine that can reach 127.0.0.1:8080 can claim any address. That can change the address shown on approval cards and spread wrong pairing-code guesses across claimed addresses, though pairing codes have 60 bits of entropy. It cannot approve anything or get past a requester key. Keep the machine for Bouncer.
Other reverse proxies
Not tested. Any HTTPS reverse proxy on the same machine can work if it:
- forwards to
http://127.0.0.1:8080; - sets
X-Forwarded-Forto the real client address, or appends that address as the last hop. Bouncer uses the right-most hop it does not trust; - uses a certificate your devices trust, for the name in
instance.url.
The iOS, Android and Windows apps need a certificate their system trusts. A private CA works only if it's installed on every device.
Why not rootless Docker
Rootless Docker puts the container's "host" network in a namespace of its own, so the server's 127.0.0.1 isn't the machine's, and tailscale serve can't reach it. Don't work around it by publishing a port: the server would then see Docker's gateway as the caller, and --trusted-proxy 127.0.0.1 would stop matching. Use rootful Docker or rootless Podman.
OpenBao's certificate
If OpenBao's certificate isn't from a public CA, give its CA to both sides:
- the server: save the CA certificate as
/etc/bouncer/config/openbao-ca.pemand setopenbao.ca_file: /etc/bouncer/openbao-ca.pem, then restart; - each requester: set
BOUNCER_CA_FILEto the same PEM file (Environment variables).
How this was checked
The kit's examples use Tailscale because the kit was built around it, not because we tested it: Tailscale wasn't part of our test run. What we checked, on rootful Docker 29: the server listened on 127.0.0.1 only, PostgreSQL had no network, and X-Forwarded-For was believed only on connections from 127.0.0.1. The tailscale serve commands and the expected answer above come from the repository's deploy/compose/README.md and the health endpoint's own answer, not from a tailnet. No public certificate was used.