Patterns for workloads and agents
These patterns keep values out of arguments, shell history and files on disk. The command you run still gets the value, so check what it prints or logs with fake data first.
Never put a secret in a command's arguments
Every user on a Linux machine can read every process's arguments (ps, /proc/<pid>/cmdline). So this leaks the password even though Bouncer handed it over safely:
# Don't: the shell puts the value into mysql's arguments.
bouncer exec prod-db-password -- sh -c 'mysql --password="$PASSWORD" billing'
Use whatever the tool offers instead, in this order of preference:
- Standard input, if the tool can read a secret there:
bouncer exec ... --stdin password -- tool --password-stdin. - A file, if the tool takes a path:
bouncer exec ... --file DB_PASSWORD_FILE=password -- sh -c 'tool --password-file "$DB_PASSWORD_FILE"'. The single quotes matter: the variable only exists inside the commandbouncerstarts, so your own shell must not expand it. The path is not secret, so it's fine in the arguments. The file exists only in memory and disappears when the command exits. - An environment variable the tool reads itself:
bouncer exec ... --env MYSQL_PWD=password -- mysql billing.
exec does not put a value in the child's arguments itself. It passes through the child's standard output and standard error without redaction. Disable shell tracing and credential logging, and avoid commands such as env that print their environment. An agent that can choose arbitrary commands can also choose one that reveals the value.
Give each workload its own requester
One requester per agent, host or pipeline means:
- the approver sees exactly who is asking;
- you can disable one without affecting the others;
bouncer-admin requester listshows when each was last used.
Anyone who can read a key file can ask as that requester, so keep key files chmod 600, owned by the user that runs the workload.
Scheduled jobs and CI
Unattended jobs shouldn't file requests nobody will see. Approve a grant ahead of time, then let the job use it. File the request with the job's own requester key: only the requester that asked for a grant can use it. Both commands below run as the job's user, who owns the key file:
# Beforehand, with the job's key. An approver approves it on their phone or PC.
BOUNCER_KEY_FILE=/etc/nightly-export/bouncer-key bouncer request nightly-export --for 7d --reason "Nightly export, week of 16 November"
# The job, from cron, with the same key:
BOUNCER_KEY_FILE=/etc/nightly-export/bouncer-key bouncer exec nightly-export --no-request --env API_TOKEN=token -- /opt/export/run.sh
With --no-request, a job without an active grant exits 8 at once instead of waiting. Alert on that exit code.
Grants of a week or more are a trade-off: anyone holding the key can use the secret for that long. Keep them as short as the schedule allows, and scope each resource to one job.
Long-running services
bouncer exec reads the values once, when it starts the command. The command keeps them for as long as it runs, but the OpenBao token behind them expires within minutes, so the service can't read anything new later. A service that runs for weeks with a copied value has the same exposure as any static secret (Copied secrets).
Agents
- Use the MCP server with an agent requester, not your own key (Connect an AI agent).
- Prefer the
bouncer execcommand the MCP tools suggest overget_secretto avoid returning the value directly to the model. Check the command's output as described above. - Ask the agent to give the grant up with
revoke_grantwhen it finishes. - Give agents only secrets you'd be willing to rotate.
Ending access early
When a job finishes early, end its grant:
bouncer revoke "$(bouncer grants --resource nightly-export --id-only | head -n 1)"
This stops new tokens at once. It can't take back a value the job already read.
Containers
The static binaries run in any Linux container that has CA certificates. Mount the key file read-only, owned by the container's user with mode 0600, and set BOUNCER_URL and BOUNCER_KEY_FILE. Don't bake the key into an image, and don't pass it with -e BOUNCER_KEY=..., which shows it in docker inspect.