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

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