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

People, requesters and devices

Bouncer has three kinds of identity. This page explains each one and the bouncer-admin commands that manage them.

IdentityWhat it isCredential
PersonSomeone who approves. Listed in the config fileThe devices paired as them
RequesterWhoever asks for access: a person at the command line, an AI agent, or a host such as a build serverA requester key, a random string starting brk_, kept in a file
DeviceA phone or PC paired to a person, which shows requests and signs approvalsA 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
  • --kind is agent (an AI agent or other automation acting for a person), host (a machine, such as a build server) or human.

  • --owner links 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

  1. 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.
  2. Revoke each of their devices (device list, then device revoke).
  3. Disable each requester they own, including their human requester (requester disable).
  4. Remove them from people, from every resource's approvers and from any groups, then reload and check that it succeeded. Their name stays in old log entries.
  5. If they could read static secrets, rotate those secrets at their source (Copied secrets).

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