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
Configure the server
All of Bouncer's policy comes from one YAML file, /etc/bouncer/config/bouncer.yaml in the compose kit. It says who the people are, which resources exist, who may ask for each one, who approves, and for how long. It holds no secrets, only the paths of the files that do.
Keep your real file in a Git repository you control and review changes to it. Whoever can change the file controls Bouncer's policy.
This page explains the sections and how changes take effect. The config file reference lists every setting with its default and range.
A small complete example
version: 1
instance:
id: example-home # never change this once devices are paired
name: Example home
url: https://bouncer.example.com # the address apps and requesters use
people:
- id: alice
name: Alice
- id: bob
name: Bob
defaults:
request_wait: 15m # how long a request waits for a decision
credential_ttl: 5m # how long each OpenBao token lasts
durations:
presets: [5m, 15m, 1h, 6h, 24h]
min: 1m
max: 24h
always: false
self_approval: true
notification_approval: true
openbao:
address: https://openbao.example.com:8443
ca_file: null
kit_prefix: bouncer
approle:
mount: bouncer-approle
role_id_file: /run/secrets/bouncer-role-id
secret_id_file: /run/secrets/bouncer-secret-id
pairing:
allow_software_keys: false
push: null
resources:
- id: prod-db-password
name: Production database password
kind: stored_secret
kv:
- mount: kv
path: apps/billing/db-password
fields: [password]
approvers: [alice]
requesters: [alice, build-agent]
The sections
| Section | What it holds |
|---|---|
version | Always 1 |
instance | The instance ID, a display name and the HTTPS address. The ID goes into every signed approval, so a signature made for one Bouncer can't be used on another |
people | Everyone who pairs a device and approves. Each person also gets a human requester with the same name, for requests they make themselves |
groups | Optional named groups of people, used by personal credential sharing |
defaults | The policy every resource gets unless it sets its own: waiting time, token lifetime, the duration choices, self-approval and approval from notifications |
openbao | Where OpenBao is, its CA file, the role kit's prefix, and the AppRole files |
pairing | Which kinds of approval key may pair (see Device keys) |
push | Firebase push settings, or null for no push (Push notifications) |
resources | One entry per secret Bouncer guards (Resources and policy) |
personal_credentials | Optional storage areas where people create their own credentials from the apps |
People are config entries. There is no single sign-on or directory integration in this version. A person exists because they are listed here, and they prove who they are by holding a device that was paired as them. Removing a person from the file stops them being an approver for any resource; revoke their devices as well (People, requesters and devices).
Durations
Durations are a whole number and a unit: s, m, h or d, for example 90s, 15m, 6h or 7d. A grant can last from 1 minute to 365 days.
The duration presets can also contain always, a standing grant: a grant with no end time. The Bouncer project hasn't decided the policy for standing grants yet. Keep them off. Set durations.always: false and leave always out of the presets, as in the example above. The example file in the repository turns them on. Approvals and access duration says what the source does with them.
How changes take effect
Most changes take effect with a reload, without restarting:
docker compose exec bouncer bouncer-admin config reload
The server reads the file again and checks it. If it isn't valid, the reload is refused with the reason, and the old file stays loaded. Expected result on success: the loaded time, resource and person counts, and new revision. From 0.5.7, the output also lists resources that need particular kinds of approval key. Policy-loosening warnings are in the approval log, not this output; read them in the affected person's app History or export the log.
Two kinds of change need a restart instead, because the server connects to OpenBao only at start-up:
- any change to the
openbaosection; - adding a new resource.
docker compose up -d --force-recreate --wait --wait-timeout 120 bouncer
docker compose logs bouncer # look for "bouncer-server is up"
This recreates the container and waits for its health check. If the wait
fails or times out, inspect the log before continuing. For Podman, run
podman-compose restart bouncer, then the bounded HTTP health retry in
Install, step 5.
A reload that tries one of these is refused with a message saying a restart is needed, and the old config stays loaded. Removing a resource, and changing people or policy, only need a reload.
Changes that loosen policy are announced. When a reload makes a resource's policy or the pairing settings less strict (a longer maximum duration, a new requester, self-approval turned on, a weaker pairing setting), the server writes a policy_loosened entry in the approval log naming each change, and tells the affected approvers' devices. Only a reload is compared. A restart or recreated container, including after an edit while stopped, logs only config_loaded, with no description or alert to approvers. To keep the alert, reload a policy loosening separately from changes that need a restart.
Changes to a resource's policy end its standing grants. Each resource has a revision computed from its policy. A standing grant approved under one revision is suspended when the revision changes, and the requester must ask again. A resource's name, description, folder and credential_type don't count towards the revision.
Checking a file before you deploy it
From 0.5.7, the new server can check a config file before you install it. These pages call this the configuration check, or preflight. Run it as the Bouncer service user, with access to the AppRole credential files and any CA files the new config names:
bouncer-server --config /path/to/candidate.yaml --check-config
With the Compose image, run it from the new release's Compose folder, whose .env names the new image. Save the new file as candidate.yaml next to the live config, in the config folder (/etc/bouncer/config on the host by default). This starts a temporary container as the image's service user; it doesn't replace the running server:
docker compose run --rm --no-deps --entrypoint /usr/local/bin/bouncer-server \
bouncer --config /etc/bouncer/candidate.yaml --check-config
The check needs no database, opens no port, applies nothing and runs no migrations. It logs in to OpenBao, which creates a server login token that expires (after one hour with the kit's defaults), and reads the settings of each resource's token role and policy. It creates no token for any resource. It prints a report on standard output. Read every line, and check the exit status:
| Exit | Meaning |
|---|---|
| 0 | All checks passed |
| 1 | Global setup or login failure |
| 2 | Command usage error |
| 3 | A definite resource gap, such as a missing or unsuitable role or policy |
| 4 | Kit upgrade needed, or a transient check that could not finish |
If a resource has a definite problem, the exit is 3 even when other checks couldn't finish. Before the role kit upgrade, exit 4 with upgrade_needed is expected for policies an older kit wrote: the resource still works, but the check hasn't passed. After upgrading the kit, the check must exit 0 before you install new resources and restart. A new resource takes its durations from defaults unless it sets its own; you don't need to shorten them because the resource is new.
These configuration-check instructions were checked against the source for 0.5.7 and its isolated OpenBao 2.7.2 checks. The full manual sequence, including the temporary Compose command, has not been run end to end.
On 0.5.6 and earlier there is no --check-config. Reload checks an edit
while keeping the old config if it is refused; bouncer-admin exits 6 and
says why. Newer servers also retain that reload behaviour. The server answers in this form:
bouncer-admin: The server said no: The config file was refused; the old one stays loaded
(config_invalid, HTTP 422). the config file isn't valid: - defaults.durations: min (2h) is more than max (1h)
bouncer-admin: The server said no: The config file was refused; the old one stays loaded
(config_invalid, HTTP 422). The resource example-new is new, which only takes effect when
the server starts. The old config is still loaded: restart the server to use the new one.
A reload that loosens policy succeeds and leaves an entry like this in the approval log:
policy_loosened config revision 263141bd3bd1 loosened resource llm-provider: durations.max went from 1d to 7d
The environment file
deploy/compose/.env sets how the containers run, not policy. See Environment variables.