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

Connecting scripts, agents and hosts

These pages are for developers and operators who want a script, a build job, a server or an AI agent to use secrets that Bouncer guards. The program asks; a person approves on their phone or PC; then the program gets the secret for a limited time.

The pieces

  • bouncer, the command-line client. It lists what you may ask for, files requests, waits for the decision, and runs a command with the secret handed to it.
  • bouncer-mcp, a Model Context Protocol (MCP) server. MCP is the standard way AI agent clients (Claude Code, Claude Desktop and others) call external tools. bouncer-mcp gives an agent tools to ask for access and use secrets, but no tool that approves.
  • A requester key. Every program that asks needs its own requester and key, made by the server's administrator (admin for short). The key goes in a private file; it never goes on a command line.

How a request flows

  1. The program files a request: a resource, a duration and a reason. (bouncer request, or the MCP tool request_access.)
  2. The resource's approvers get a notification. One of them reviews the request on their phone or PC and approves, shortens or denies it. The device signs that decision with a key that never leaves it.
  3. The server records a grant: permission to use that resource until a set time.
  4. While the grant lasts, the program asks Bouncer for a short-lived OpenBao token (5 minutes by default), and reads the secret from OpenBao with it. bouncer exec and the MCP tool get_secret do this for you.
  5. The grant ends at its time, or earlier if someone revokes it. Tokens already issued are revoked too.

This is the flow for a fresh approval. Two experimental features give access without a new approval: an existing standing grant (Always) can be used again, and a personal credential set to Always approved lets the people it's shared with use it through their own requester key without asking. Keep both off, as Approvals and access duration describes.

If OpenBao is unavailable when a grant ends, revoking the tokens already issued can be delayed, so check what bouncer revoke reports. Ending a grant never affects a value that was already copied, or a session that's already open.

A program can never approve its own request. Only a signature from a paired device approves.

Setting up a program

  1. Install the CLI.
  2. Set up a requester with the key your admin gives you.
  3. Use the CLI, or connect an AI agent through MCP.
  4. Read Patterns for workloads and agents before you put this in a pipeline.

For SSH hosts, keep revocations up to date on every destination. Exit codes and errors and the CLI reference have the details.

Platform status

ClientStatus on 17 November 2026
Linux CLI and MCP server (x86_64)In the private release as a static tarball with an installer, and as .deb and .rpm package files. Not yet public, and there's no package repository yet
Windows CLI and MCP server (x86_64)Since 0.5.1, as a zip with a per-user installer, in the private release. Not yet public, and not code-signed yet
macOS CLINot available, and not tested

Some features are Linux-only: bouncer exec --file (it uses a Linux in-memory file) and bouncer self-update. bouncer exec --stdin works on Linux and Windows.

Platforms and status says which releases are published.

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