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

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

Install the CLI

Linux (x86_64)

The Linux release contains bouncer, bouncer-mcp and bouncer-admin as static binaries. They run on any x86_64 Linux, including Debian, Ubuntu, Fedora and Alpine, with nothing else installed except the system's CA certificates. (A slim container image may lack them; install its ca-certificates package.)

Before you start: get these three files into one empty folder. There's no public download page or package repository yet. The files are in Bouncer's private release, so ask whoever gave you access to Bouncer for them (Get Bouncer):

  • SHA256SUMS
  • install.sh
  • bouncer-cli-<version>-x86_64-linux.tar.gz

Then:

grep ' install.sh$' SHA256SUMS | sha256sum -c -
sh install.sh
bouncer --version
  • The first line checks the installer before you run it.
  • install.sh checks the tarball against SHA256SUMS, checks every file inside it, and installs bouncer and bouncer-mcp. It installs to ~/.local/bin as a normal user, to /usr/local/bin when run as root (sudo sh install.sh), or to --prefix DIR. It downloads nothing and never touches your key.
  • If it says ~/.local/bin isn't on your PATH, add it as it shows.

Expected result: bouncer 0.5.0+27 (bouncer.v1), with your release's version.

bouncer-admin stays in the tarball. It only belongs on the Bouncer server.

Or install the .deb or .rpm

The release also has the packages, bouncer-cli_<version>-1_amd64.deb and bouncer-cli-<version>-1.x86_64.rpm. Download the one you need with SHA256SUMS, check it with sha256sum -c SHA256SUMS --ignore-missing, and install the file:

sudo apt install ./bouncer-cli_<version>-1_amd64.deb     # Debian or Ubuntu
sudo dnf install ./bouncer-cli-<version>-1.x86_64.rpm    # Fedora

There's no apt or dnf repository to add yet, so the package manager won't find updates by itself: install each new release's package the same way.

If a checksum doesn't match, the installer stops and installs nothing. Download the files again; if it still fails, don't use them, and tell whoever publishes your releases.

Updates

How you installedHow to update
install.shInstall the new release the same way. bouncer self-update exists, but only works with release builds that have an update key built in; current builds say "This build has no update key built in"
.deb or .rpmInstall the new release's package file the same way. Updates through apt or dnf need a package repository, and none is public yet

bouncer self-update checks a signed release manifest and each binary's checksum, keeps the old binaries for --rollback, and refuses to touch a copy that a package manager owns.

Build from source

If you have the Rust toolchain the repository pins:

cargo build --release -p bouncer-cli -p bouncer-mcp

The binaries are target/release/bouncer, target/release/bouncer-admin and target/release/bouncer-mcp.

Uninstall

rm -f ~/.local/bin/bouncer ~/.local/bin/bouncer-mcp ~/.local/bin/.bouncer.old ~/.local/bin/.bouncer-mcp.old
shred -u ~/.config/bouncer/key
rm -r ~/.config/bouncer

Use /usr/local/bin (with sudo) or your --prefix folder if you installed there. The .old files exist only after a self-update. Ask your Bouncer admin to disable the requester as well, so the key can't be used from a copy elsewhere.

Windows (x86_64)

From 0.5.1, bouncer.exe and bouncer-mcp.exe run natively on x86_64 Windows 10 and 11. They aren't code-signed yet, so Windows SmartScreen may warn about them.

Before you start: get these three files into one folder. As on Linux, they're in Bouncer's private release, so ask whoever gave you access to Bouncer for them:

  • SHA256SUMS
  • install-windows-cli.ps1
  • bouncer-cli-<version>-x86_64-windows.zip

Then, in PowerShell, as the user who'll run Bouncer (no administrator rights needed):

powershell -NoProfile -ExecutionPolicy Bypass -File .\install-windows-cli.ps1
  • The installer checks the zip against SHA256SUMS, and every file inside the zip against the zip's own sums. If one doesn't match, it installs nothing.
  • It installs both programs to %LOCALAPPDATA%\Programs\Bouncer CLI\bin and adds that folder to your own PATH (not the machine's). It never touches your key.

Then open a new PowerShell window, so it picks up the new PATH, and run bouncer --version.

Expected result: bouncer followed by your release's version, such as bouncer 0.5.2+29 (bouncer.v1).

bouncer-admin isn't in the zip: it only runs on the Bouncer server's own machine.

Saving your key on Windows

bouncer key save reads the key from standard input and saves it to %LOCALAPPDATA%\bouncer\key, readable only by your Windows account and encrypted with Windows' data protection (DPAPI) so that only your account can decrypt it:

Get-Content .\web01.key | bouncer key save
Remove-Item .\web01.key
Set-Content -Encoding ascii "$env:LOCALAPPDATA\bouncer\server" https://bouncer.example.com

bouncer refuses a key file that anyone other than you, SYSTEM or Administrators may open. DPAPI stops another Windows account opening a copy of the file; anything running as you, and administrators, can still open it.

What's different on Windows

  • exec gives a secret in an environment variable (--env) or on standard input (--stdin). --file is Linux only, and bouncer never writes a secret to a temporary file.
  • There's no bouncer self-update: run the next release's installer the same way.

How this was checked

The --version output is from the 0.5.0 binaries built from the source for this guide. The installer's behaviour is from scripts/release/install-linux-cli.sh and the project's release notes (docs/releases/linux-cli.md), which record it being checked on fresh Debian, Ubuntu, Fedora and Alpine containers. We didn't rerun the installer for this page.

The Windows section is from scripts/release/install-windows-cli.ps1, docs/releases/windows-cli.md and the CLI README's Windows notes in the source. On the project's Windows CI runner, the build script builds the zip and installs it into a temporary folder, without changing PATH, to check it; we didn't install it on a PC for this page.

This manual covers Bouncer 0.5.7. Built from source commit cdd3b5958d5be0b33e865b1b56b770f6bccffaf7 (workspace version 0.5.7+34).