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
People, requesters and devices
Bouncer has three kinds of identity. This page explains each one and the bouncer-admin commands that manage them.
| Identity | What it is | Credential |
|---|---|---|
| Person | Someone who approves. Listed in the config file | The devices paired as them |
| Requester | Whoever asks for access: a person at the command line, an AI agent, or a host such as a build server | A requester key, a random string starting brk_, kept in a file |
| Device | A phone or PC paired to a person, which shows requests and signs approvals | A device token (starting bdt_) and, for approving, an approval key that stays on the device |
A requester key can ask, but can never approve. Only a signature from a paired device's approval key approves.
Running bouncer-admin
bouncer-admin runs on the server's own machine and talks to the server over a local Unix socket, never the network. With the compose kit, run it inside the container:
cd ~/bouncer/deploy/compose
docker compose exec bouncer bouncer-admin <command>
Whoever can run that command is the admin. There is no separate admin password. Limit who has a shell on this machine and who is in the docker group.
Use docker compose exec -T (with -T) whenever you redirect the output to a file, so that only the command's standard output lands in the file.
People
People are entries in the config file:
people:
- id: alice
name: Alice
Add or remove a person by editing the file and reloading (bouncer-admin config reload). When the server loads the file, it creates a human requester named after each new person, without a key. That's the requester the person uses when they ask for access themselves.
There is no single sign-on in this version. A person proves who they are only by holding a device paired as them, so pair devices in person or over a channel you trust.
Requesters
Create one
Give every person, agent and host its own requester, so the approver can tell them apart and you can disable one without affecting the others.
umask 077
docker compose exec -T bouncer bouncer-admin requester add build-agent --kind agent --owner alice > build-agent.key
-
--kindisagent(an AI agent or other automation acting for a person),host(a machine, such as a build server) orhuman. -
--ownerlinks it to a person. Their own agents' requests are then labelled "Your own agent" on their phone. -
The key alone goes to standard output, so the redirect captures just the key. The explanation goes to the screen. Expected result:
Created requester build-agent (rqr_01..., agent, owned by Alice). Its key is below. It's shown only this once: store it now.
The key is shown only once. Bouncer keeps only a hash of it. Move the file to the machine that will use it (Set up a requester), then delete this copy with shred -u build-agent.key.
A person's human requester already exists, without a key. Give it one the same way:
(umask 077; docker compose exec -T bouncer bouncer-admin requester rotate-key alice > alice.key)
List them
docker compose exec bouncer bouncer-admin requester list
From 0.5.7, the list has a KEY ID column after
LAST USED. Version 0.5.6 and earlier don't have that column. With
fake records, the command prints:
REQUESTER NAME KIND OWNER STATUS KEY ISSUED LAST USED KEY ID
rqr_01jbx1p2r4s6t8v0w2x4y6z8a0 alice human alice active 2026-11-15T06:31:02Z never 6a7b8c9d0e1f
rqr_01jbx1q3s5t7v9w1x3y5z7a9b1 build-agent agent alice active 2026-11-15T06:28:32Z 2026-11-15T06:29:04Z a1b2c3d4e5f6
KEY ID is the first 12 lower-case hexadecimal characters of the hash Bouncer stores for the key. It's a label for telling keys apart. It isn't secret, and it can't be used to make a request. Each new key gets a different KEY ID, even when two are issued in the same second and show the same KEY ISSUED time. A requester that hasn't been given a key shows -, and so does every requester if you run a newer bouncer-admin against an older server. Before you restore a backup, save a copy of this list so you can tell afterwards which keys changed: see Backup and restore, step 4.
Replace a key
If a key may have leaked, or a machine is rebuilt:
(umask 077; docker compose exec -T bouncer bouncer-admin requester rotate-key build-agent > build-agent.key)
The old key stops working at once. Replacing a key suspends the requester's standing grants: a suspended grant never becomes active again, so the requester asks again and someone approves afresh. Its time-limited grants carry on until they end.
Disable one
docker compose exec bouncer bouncer-admin requester disable build-agent
This stops its key, cancels its pending requests and revokes its grants and their tokens. requester revoke is another name for the same command. A disabled requester can't be turned back on, and its name stays taken: if you need it again, create a new requester with a different name.
Devices
Pair a device
See Pair a device.
List devices
docker compose exec bouncer bouncer-admin device list
DEVICE NAME PERSON PLATFORM STATUS APPROVES KEY MEETS PAIRED LAST SEEN
dev_01jbx2a7c9e1g3h5j7k9m1n3p5 Alice's phone alice Android active yes hardware_uv, hardware_key 2026-11-15T06:28:32Z 2026-11-15T06:29:30Z
APPROVES says whether the device has an approval key. A Windows PC shows no until its owner turns on Windows Hello approvals.
KEY MEETS is new in 0.5.7. Version 0.5.6 and earlier don't have that column. It says which key settings that key can satisfy: hardware_uv (require_hardware_uv), hardware_key (require_hardware_key), hardware_key (TPM attested) for a Windows Hello key whose TPM attestation the server verified, or neither. A key that meets neither can still approve resources that set neither, and any key can deny.
Revoke a device
docker compose exec bouncer bouncer-admin device revoke dev_01jbx2a7c9e1g3h5j7k9m1n3p5
From then on the device can't sign in, approve, deny or see anything. Standing grants it approved are ended. Time-limited grants it approved stay active until they end, and the command lists them so you can decide about them. Lost or stolen device has the full procedure.
People can also remove their own device from the app (signing out revokes it on the server). The apps can't revoke other devices; only the admin can.
When someone leaves
- Check which resources list them in
approvers. Where they are the only approver, add another with a paired device and reload before revoking anything. A resource must keep at least one approver or the reload is refused. - Revoke each of their devices (
device list, thendevice revoke). - Disable each requester they own, including their human requester (
requester disable). - Remove them from
people, from every resource'sapproversand from anygroups, then reload and check that it succeeded. Their name stays in old log entries. - If they could read static secrets, rotate those secrets at their source (Copied secrets).