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

Config file reference

Every setting in bouncer.yaml, as the config loader reads it in the source this site was built from. Settings that 0.5.6 and earlier refuse are marked "from 0.5.7". Configure the server explains how to use them. The repository's contracts/config/bouncer.example.yaml is a commented example with every section, and contracts/schemas/config.v1.json is the JSON Schema.

General rules:

  • Unknown keys are refused, and so are repeated keys. A typo is an error, not ignored.
  • Durations are a whole number and a unit: s, m, h or d (90s, 15m, 6h, 7d).
  • Booleans are only true or false.
  • The file holds no secrets: only the paths of files that do.

Top level

KeyRequiredMeaning
versionyesMust be 1
instanceyesSee below
peopleyesAt least one person
defaultsnoPolicy defaults for every resource
openbaoyesHow Bouncer reaches OpenBao
pairingnoWhich approval keys may pair
pushnoFirebase push, or null for none
resourcesyesAt least one resource
groupsnoNamed groups of people, for personal credential sharing
personal_credentialsnoStorage areas for people's own credentials

instance

KeyMeaning
idLower-case letters, digits and hyphens. Goes into every signed statement. Never change it once devices are paired
nameDisplay name
urlhttps://host[:port], the address apps and requesters use. Carried in pairing codes

people

A list of:

KeyMeaning
idLower-case ID, used in approvers, --person and --owner. Each person gets a human requester of the same name
nameDisplay name

defaults

Each of these can also be set on a single resource, which then overrides the default.

KeyDefaultAllowedMeaning
request_wait15m1m to 24hHow long a request waits for a decision
credential_ttl5m30s to 1hHow long each OpenBao token lasts (never past the grant's end)
durations.presets[5m, 15m, 1h, 6h, 24h, 7d, always]1 to 12 entries, each 1m to 365d or always, no repeatsThe quick choices on the approval screen
durations.min1m1m to 365dThe shortest custom duration
durations.max365d1m to 365d, at least minThe longest custom duration
durations.alwaystrueWhether standing grants may be approved. The Bouncer project hasn't decided the policy for standing grants yet. Set this to false
durations.always_review90d1d to 365dHow often a standing grant must be re-confirmed
self_approvaltrueWhether people may approve their own requests and their own agents'
notification_approvaltrueWhether approving from a notification is allowed (each device must also opt in)
require_hardware_uvfalseWhether only biometric hardware keys (platform-hw-uv) may approve
require_hardware_keyfalseIntroduced in 0.5.7; earlier servers refuse the key. In the current source (not yet released), requires verified Android-key or Windows TPM evidence for the current key plus per-use verification. A declared hardware-UV label alone fails. Independent of require_hardware_uv, whose UV-only claim rule is unchanged; both apply when both are set

openbao

KeyMeaning
addresshttp(s)://host[:port], as both the server and requesters reach OpenBao
ca_fileA PEM CA bundle for OpenBao's certificate, or null
kit_prefixThe role kit's prefix (KIT_PREFIX, bouncer by default). Lower-case letters and digits in dash-separated parts, starting with a letter, up to 20 characters. Each resource uses the token role <kit_prefix>-issue-<resource id>
approle.mountThe role kit's AppRole mount. Must start with the kit prefix and a dash (bouncer-approle)
approle.role_id_fileThe file holding the role_id (/run/secrets/bouncer-role-id in the compose kit)
approle.secret_id_fileThe file holding the secret_id
ssh.approle.mount, .role_id_file, .secret_id_fileThe SSH signer's own login, needed once any resource is an ssh_host. Its mount must start with the kit prefix and differ from the token login's

Any change to this section needs a server restart.

pairing

KeyDefaultMeaning
allow_software_keysfalseAllow approval keys kept in software. For test setups only
allow_user_verified_keysfalseAllow phone keys that need biometrics for every signature (platform-hw-uv). Needed for iPhones
allow_webauthn_keysfalseAllow Windows Hello keys
require_verified_approval_keysfalseIn the current source (not yet released): opt in to verified Android-key or Windows TPM evidence at key installation and every signing gate. Existing unverified keys also fail after reload. Keyless Windows bootstrap remains available. Incompatible with android_attestation: off
android_attestationpreferrequired, prefer or off (Device keys)
android_packagecom.s6studios.bouncerThe Android app an attestation must name
android_signing_cert_sha256the official upload certificate'sThe SHA-256 of each certificate the app may be signed with (64 hex digits each)

allow_software_keys, allow_user_verified_keys, allow_webauthn_keys and android_attestation: required are checked again whenever a device signs, so turning one off also stops keys that paired while it was on. android_package and android_signing_cert_sha256 apply only when a phone pairs. Turning on allow_software_keys or allow_user_verified_keys, weakening android_attestation, or changing android_package or the signing certificates counts as a loosening and is announced. Turning on allow_webauthn_keys is not announced. Turning off require_verified_approval_keys is a loosening and is announced; check-config and reload report its value. Dropping require_hardware_key also loosens proof requirements while require_hardware_uv remains set. With the new opt-in omitted, an existing UV-only rule still accepts declared claims; upgrading does not activate a policy. See key proof.

push

null turns push off. Otherwise:

KeyMeaning
fcm.project_idThe Firebase project ID
fcm.service_account_fileThe service-account key file, such as /run/secrets/fcm-service-account.json
fcm_alsoNeeds server build 0.3.8+25 or later. Only while moving to another project: up to 4 more project_id and service_account_file pairs, tried in order after fcm. Each project and key file may appear once

The key files are read at start-up and on every reload; a missing or broken one refuses the start or the reload.

resources

A list. Each resource:

KeyRequiredDefaultMeaning
idyesLower-case letters, digits and single dashes, up to 40 characters. Unique. Not starting with pc-
nameyesDisplay name
kindyesstored_secret, stored_api_key or ssh_host
descriptionnononeShown to requesters and approvers
foldernoUnfiledFolder names joined by /
credential_typenononeOne of api_key, password, access_token, certificate, certificate_with_private_key, ssh_private_key, secret_key, key_pair, recovery_codes, otp_seed, other. A label for the apps' icons only. Servers before 0.5.0 refuse it
kvyes, except for ssh_hostA list of mount and path (without data/). An ssh_host has none
fieldsnononeField names shown to requesters. Names only
approversyesPerson IDs
requestersnoany active requesterRequester names, or ["*"] for any
request_wait, credential_ttl, durations, self_approval, notification_approval, require_hardware_uv, require_hardware_key (from 0.5.7)nofrom defaultsAs in defaults
allow_writenofalseAccept store requests. Needs exactly one kv entry and write in the role kit's line
lifecyclenofalseKeep version history and allow expiry, scheduling and replacement from a paired app. Stored secrets and API keys only. Needs exactly one kv entry and lifecycle in the role kit's line. From 0.5.3; see setup, permissions and retention limits
viewnooffoff, grant_holder or approver: who may view the value in the apps. Needs exactly one kv entry and view in the role kit's line. Not for ssh_host
allow_device_viewnofalseOlder form of view: approver. Give one or the other, not both
downstream.systemwith downstreamThe other system's name
downstream.kindwith downstreamstatic_token
downstream.expires_atnononeWhen the credential expires at its system, as an RFC 3339 time
ssh.principalfor ssh_hostThe one account on the host: lower-case letters, digits, _, - and ., up to 32 characters, and not root
ssh.bind_source_addressnotrueBind each certificate to the address the requester called from

Adding a resource needs a restart. Removing one only needs a reload; its standing grants are suspended.

Check a candidate resource configuration

From 0.5.7, use bouncer-server --check-config with --config before installing a new resource. It checks the candidate file and OpenBao provisioning without applying it. Run it as the service user; require exit 0 after the kit upgrade. See Checking a file before you deploy it for the login/session-token limits and all exit codes, and Add a resource for the kit, preflight, config and restart order. A new entry inherits defaults, including its duration ceiling, unless it overrides them.

groups

A list of id and members (person IDs). Used only by personal credential sharing.

personal_credentials

A list of storage areas ("namespaces") where people create their own credentials from the apps. Each:

KeyDefaultMeaning
idThe namespace's ID
labelfrom the ID, such as "Personal storage"The name the apps show. Must differ from every other namespace's, ignoring case
kv.mount, kv.prefixWhere the values go in OpenBao. The prefix leaves out data/, and mustn't overlap a resource's secret or another namespace. The role kit needs a matching personal line
creatorseveryonePeople or groups who may create here
fields.namesanyThe only field names allowed
fields.max8Fields per credential, 1 to 32
per_owner50Credentials per person, 1 to 1000
lifecyclefalseEnable lifecycle for every credential in this namespace. The role kit's personal line for it needs lifecycle too (personal lifecycle). Turning it off later keeps recorded expiries, and saves that would prune an old version are still refused; see Credential expiry, replacement and history
ceilingsrequiredThe block must be present, even if empty (ceilings: {})
ceilings.credential_ttl, ceilings.durationsfrom defaultsThe most a credential in this area may allow
ceilings.revealfalseWhether values may be viewed in the apps
ceilings.always_approvedfalseWhether an owner may set a credential to be approved automatically. Keep it false: this mode has two open problems (Approvals and access duration)

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