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-mcpgives 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
- The program files a request: a resource, a duration and a reason. (
bouncer request, or the MCP toolrequest_access.) - 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.
- The server records a grant: permission to use that resource until a set time.
- 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 execand the MCP toolget_secretdo this for you. - 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
- Install the CLI.
- Set up a requester with the key your admin gives you.
- Use the CLI, or connect an AI agent through MCP.
- 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
| Client | Status 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 CLI | Not 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.