Bouncer Vaultby S6 Studios

Get started

Getting started with Bouncer Vault

A short setup outline for administrators, approvers and requesters. Before you install, get the full instructions for your release from S6 Studios.

The Bouncer manual

This manual covers Bouncer 0.5.7, built from source revision cdd3b5958d5be0b33e865b1b56b770f6bccffaf7. The manual's downloads, platforms and 0.5.7 release notes pages give distribution status and version limits. Site build 20 November 2026.

Set up a server

You need a Linux machine or VM with rootful Docker Engine 25 or later and the Compose plugin (rootless Docker isn't supported), or rootless Podman 5, about 1 GB of free memory to run it, OpenBao 2.7 or later, and HTTPS reachable from the approver devices and requesters. The private release includes a prebuilt server image; compiling from source needs extra memory and source access.

First get the files and instructions for your release: see how to get access and the files to ask for.

  1. Set up OpenBao, or check the one you have: running, unsealed, with a KV version 2 mount.
  2. List your secrets in the role kit's resources file. The server role can issue scoped tokens, revoke tokens by accessor, read paths enabled for app views, write enabled save paths, and read and write configured personal credential namespaces. Run ./setup.sh --dry-run, check those permissions, then run ./setup.sh.
  3. Write the server config: resources, approvers, durations and limits. Keep it in a Git repository you control.
  4. Load and verify the release image as its INSTALL-SERVER.md describes, start the server and PostgreSQL with Docker Compose, and put HTTPS in front of it. Your devices and requesters must trust its certificate and reach the server; requesters also need to reach OpenBao. Turn off standing grants (durations.always: false) and leave push off for now.
  5. Add people and requesters, and pair the first phone.
  6. Try a request end to end, then run the emergency stop once so you know it works. Schedule backups.

Use INSTALL-SERVER.md from the exact release and the kit's deploy/compose/README.md for installation, upgrade, backups and recovery. These come with the release. The administrator manual covers the same tasks in more detail. Where it differs from your release's files, follow the release's files.

Pair an approver app

  1. Your administrator runs bouncer-admin device pair. It shows a QR code and a pairing string. Both work once and expire after a few minutes.
  2. On a phone, tap Scan QR code, or Enter the code instead and paste the pairing string. On Windows, copy the pairing string and click Paste pairing string.
  3. Check the server and your name, name the device, and tap Pair.
  4. On a phone, allow notifications so they work once push is available for your server; until then, open the app to see waiting requests. On Windows, Bouncer Desktop waits in the notification area and can only tell you about requests while it is running.

If your server is on a private network such as Tailscale, connect the device to that network first.

Ask for access from the command line

bouncer resources
bouncer request prod-db-password --for 15m --reason "Run the March billing migration" --wait
bouncer exec prod-db-password -- ./migrate.sh

See the fake-data request-to-revoke walkthrough for captured results and their limits.

bouncer resources lists what you may ask for, never a value. exec runs the command with the secret in its environment, named after the field (for example PASSWORD), and tells you which variables it set without printing their values. The command and anything it starts can still read, print, log or transmit those values; check the command and what captures its output.

Connect an AI agent

Give the agent its own requester of kind agent and its own key file, then check the settings yourself:

BOUNCER_URL=https://bouncer.example.com BOUNCER_KEY_FILE=~/.config/bouncer/agent-key bouncer-mcp --check

Add bouncer-mcp to your MCP client with the same two settings. The agent can ask and wait; where approval is required, a person signs the decision. The get_secret tool returns the value to the agent, so it becomes part of the conversation. It may be retained in client or provider logs. Use bouncer exec for commands that do not need to return the value to the agent, and check their output and logs: the wrapper cannot prevent a command from exposing it.

Lost or replaced devices

  • New phone or PC: pair the new one first, then on the old one go to Settings and Sign out. Signing out asks the server to revoke the old device.
  • Lost or stolen: tell your administrator straight away. They revoke it with bouncer-admin device revoke, and it can't approve anything after that.
  • Approved something by mistake: open Grants and tap Revoke. If the value may have been read, change it at its source.

Read the manual offline

Download the manual for offline reading (ZIP, 1.9 MB) · SHA-256 checksum file

To check the download, put both files in one folder and run:

sha256sum -c bouncer-manual-0.5.7+34-cdd3b59.zip.sha256

It should print OK. The expected SHA-256 is d692bde9c39afe584c825bcec7bd1c18503b6e4b8b1f60e2cb68d6dc7daa3681.

Extract the ZIP and open bouncer-manual/index.html in a browser. bouncer-manual/print.html has the whole manual on one page for printing. Nothing in it needs an internet connection. Reading and search from disk were tested in Chromium and Firefox.

If search doesn't work when you open the files directly, run this from the folder you extracted the ZIP into, then open http://127.0.0.1:8000/:

python3 -m http.server --bind 127.0.0.1 --directory bouncer-manual 8000

Press Ctrl+C to stop it.

For help, see Support.