Skip to content
Ambry

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 ambry CLI

    The same, from a terminal. People log in on the terminal for each command that needs it, and reveal always 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.

  1. 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.

  2. 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.

  3. 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.