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

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

SectionWhat it holds
versionAlways 1
instanceThe 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
peopleEveryone who pairs a device and approves. Each person also gets a human requester with the same name, for requests they make themselves
groupsOptional named groups of people, used by personal credential sharing
defaultsThe policy every resource gets unless it sets its own: waiting time, token lifetime, the duration choices, self-approval and approval from notifications
openbaoWhere OpenBao is, its CA file, the role kit's prefix, and the AppRole files
pairingWhich kinds of approval key may pair (see Device keys)
pushFirebase push settings, or null for no push (Push notifications)
resourcesOne entry per secret Bouncer guards (Resources and policy)
personal_credentialsOptional 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 openbao section;
  • 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:

ExitMeaning
0All checks passed
1Global setup or login failure
2Command usage error
3A definite resource gap, such as a missing or unsuitable role or policy
4Kit 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.

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