How it works
Every piece holds only what it needs
Ambry is one server and the clients around it. What separates them is not what they can reach but which credential each one carries, and the server checks that credential on every request, whichever client sent it.
The pieces
Five components, and the one column that matters: what each is allowed to hold.
-
The server
Seals and opens values, keeps the audit chain, and decides every request. It listens on loopback only, behind nginx with TLS, on the LAN.
Holds: The KEK, in locked memory.
-
The dashboard
For people. Browse namespaces and versions, fulfil requests, manage tokens and grants, read the audit log.
Holds: A session in page memory only: 8 hours, never extended, gone after 30 idle minutes or a reload.
-
The
ambryCLIThe same, from a terminal. People log in on the terminal for each command that needs it, and
revealalways asks.Holds: Nothing that can reveal. There is no session file and no remember-me.
-
The MCP server
How an agent talks to Ambry: list and describe, create a generated secret, rotate, request an entry or a grant, compare fingerprints, and read the audit.
Holds: An agent token, which the server refuses on reveal and inject.
-
Deploy runners
Build runners and the Ansible lookup fetch a target’s secrets at deploy time and put them where the deploy needs them.
Holds: A runner token with inject on one namespace, one token per machine.
A secret, used by an agent
The agent asks for work to be done; it never asks for the value.
- Step 1
The agent
Needs a secret used. It triggers the deploy pipeline and names the target.
Holds: An agent token: list, create, rotate, ask. It cannot reveal.
- Step 2
The runner
Fetches the target’s namespace from Ambry and injects the values into the step.
Holds: A runner token granted inject on exactly one namespace.
- Step 3
The step
Runs with the value in its environment. The runner redacts known values from the log.
Holds: The value, for the length of the step, and nothing that can fetch another.
Namespaces name a role
A namespace is project/env, and the environment names the role it plays, never the machine it runs on. Moving a service between hosts never renames its secrets.
Each namespace gets one runner principal with inject on that namespace alone, and one token per machine under it. A credential that deploys staging cannot touch production, and retiring a machine is revoking its tokens.
namespaces and grants
billing/prod # project/env — env names the ROLE, not the host
billing/staging
shop/prod
# one runner principal per namespace, granted inject on exactly that one
billing-prod-deploy inject billing/prod
billing-staging-deploy inject billing/staging Values only a person has
Some values can’t be generated: a webhook secret from a payment provider, an API key someone pasted into a settings page. An agent that needs one files a request, and a person fulfils it from the terminal or the dashboard.
What comes back to the agent is a fingerprint, keyed and truncated, so it can tell two references apart and cannot guess a value from it.
request, then fulfil
# an agent, over MCP: asks for a value it cannot make
request_secret_entry billing/prod stripe/webhook_secret
→ request #17 filed
# a person, later, at a terminal: the value comes from stdin only
$ ambry fulfill 17 --stdin < webhook_secret.txt
# the agent, afterwards, sees a reference and a fingerprint
describe_secret billing/prod stripe/webhook_secret
→ v1 fp1-4b19d0e2 Deploys read by name
Playbooks swap vaulted variables for lookups one at a time. The lookup posts to Ambry with a runner token and refuses to return a value in a run that would print it: a real run with --diff, or -vvv. In check mode it contacts nothing and returns a placeholder.
Ambry is read at deploy time only. Services still get their configuration rendered onto the host, so nothing running depends on Ambry being up.
group_vars
# a playbook reads a secret by name — no vault file, no vault password
stripe_secret_key: "{{ lookup('ambry', 'billing/prod/stripe/secret_key') }}" Then read what it defends
The keys, the audit chain, the backups, and the things Ambry does not protect against, stated plainly.