Skip to the content

Give every agent an owner and an identity

Register each person and agent in Central Lite's identity registry, issue and revoke gateway keys, and see which identity every task belongs to.

Built, not yet claimed preview: this guide describes a package that has not passed its release gate.

Add a principal for each person in Central Lite's identity registry, bind their login names to it, give each agent its own identity with a human sponsor, issue and revoke gateway keys, and see on each machine and in Central Lite which identity every task, model call and delegation belongs to.

1. Add a principal for each person and agent

A principal is who work is attributed to: a human, a service or an agent. On the Central Lite host, garm-central identity principal add adds one, active, and prints its id, a UUID that every later command takes; garm-central identity show lists them all. --issuer and --subject name the person's identity at your identity provider; only a principal with one can delegate to an agent through an assertion, and one external identity names at most one principal.

Every change publishes the next version of the identity registry, signed by the org's policy key, valid 30 days and re-published by serve before half of that is left. That key is online on Central Lite's host, so whoever controls that host can change who is who. In the console, Identity shows the same registry, read-only: changes are made with garm-central identity.

People can instead come from your identity provider through SCIM: each user it sends becomes a human principal with their identity at the provider and, if you choose, a login name bound on every machine, so you add only agents and services by hand (Provision and remove people with SCIM). Seeing people in the console needs a role allowed to: viewer and finops are not.

garm-central identity principal add --kind human --name alice --issuer https://idp.example.com --subject alice
garm-central identity principal add --kind agent --name "Claude Code for alice"
garm-central identity show

Checked by the walk: this command ran as written on a Central Lite host.

2. Bind each login name to its principal

A machine learns whose a task is from its local account. garm-central identity bind binds a login name to a principal on every host of the org, or with --host on one host by its host id; on that host, a binding for it wins over one for every host. identity unbind takes the same flags. For an account no binding names, agentgarm identity says “bound to no principal (its work is unattributed)”.

garm-central identity bind --principal <alice's principal id> --username alice

3. Give the agent an identity and a sponsor

garm-central identity agent add gives an agent principal an agent identity: the agent kind it is for (an adapter name such as claude-code or codex), optionally a version and a policy name, and one to sixteen human sponsors, each --sponsor a principal id; add :owner to mark the owner. The human is accountable; the agent has an identity of its own.

When a task of that agent kind starts for an account bound to a sponsor, agentgarmd runs it as the active agent identity, set from the registry and never taken from the agent. The task's events and spend are then the agent principal's, and its sponsor is on record. identity agent state suspends or retires it; a retired identity stays retired.

garm-central identity agent add --principal <agent principal id> --agent-kind claude-code --sponsor <alice's principal id>:owner

4. Issue a gateway key

garm-central identity key issue mints a gateway key for an active principal and lists it as a credential issued by agentgarm, for 2,160 hours by default and at most 8,784. The key is never shown, not even once: Central Lite seals it in its keystore and prints only the credential's id. It goes over the control channel to each enrolled machine the principal is bound to, once that machine has applied a registry listing it, and the machine keeps it only for an active principal bound there.

On the machine, agentgarm identity api-key hands it to the bound account alone, for Claude Code's apiKeyHelper. AgentGarm passes the key on unchanged, so it works only through a route to your organisation's gateway. A key issued elsewhere, such as a provider key, is listed by its fingerprint with identity credential add, the key read on stdin, never kept.

garm-central identity key issue --principal <alice's principal id>

See also

Give Claude Code a per-developer gateway key

Give each developer their own gateway key from Central Lite and let Claude Code fetch it through apiKeyHelper; a claude.ai login is never routed.

5. Revoke a credential or retire a principal

garm-central identity credential revoke marks the credential revoked in the registry, puts its fingerprint on the signed revocation list and erases its sealed key if Central Lite issued it; a reason is required. If the erasure fails, the command exits 1 saying so, the revocation stands, an alert is raised and serve retries. key issue --rotates issues a new key and revokes the old one in the same action.

On each machine, a revoked credential stops counting as anyone's (fail_open_alert). A key AgentGarm issued also stops working (fail_closed): agentgarmd erases its copy and the proxy refuses it within a minute. The same happens when its principal is suspended or retired with identity principal state. A key issued elsewhere keeps working at its issuer: end it there too.

For a person provisioned by SCIM, deactivating them at your identity provider suspends their principal in the same way and publishes the registry at once, so their AgentGarm-issued gateway keys stop on every machine without a command here; Entra ID's deletion 30 days later retires them (offboard someone).

garm-central identity credential revoke <credential id> --reason "left the company"
garm-central identity principal state <principal id> retired

6. Check what each machine holds

While serve runs, Central Lite sends each enrolled machine the newest registry over its control channel, not at once: a connected machine gets it within seconds, one that is offline gets it when it next connects. The machine verifies its signature before reading it, and chains it in its own audit log. garm-central identity publish publishes the registry as it stands as a new version now, without waiting for a change.

On a machine, agentgarm identity shows where the registry comes from (central: with the org and its version; STALE once past its expiry, though it stays in force), the principal your account is bound to, its credentials and their state, the agent identities you are or sponsor, the gateway keys held for you and your spend over 30 days. Never a key or a fingerprint. The dashboard's Identity screen shows you the same. Root adds --all to see every identity. If it still shows the previous version, the delivery has not arrived yet: run it again.

garm-central identity publish
sudo agentgarm identity --all

Checked by the walk: these commands ran as written on a Central Lite host and a Linux node enrolled in Central Lite, and the output showed central:.

The dashboard's Identity screen: your principal and where the registry comes from, then your credentials and agent identities with their state

7. Read the delegations and export the inventory

When an agent presents your identity provider's assertion for a principal with an external identity, the machine's token endpoint issues it a short-lived access token and records a delegation from that principal to the task's own (the agent identity's, when it runs as one), scoped and expiring with the token. garm-central identity delegations lists the uploaded ones, newest first, with the principals Central Lite authored resolved; the console's Identity section shows them under Delegations, as keyed hashes.

garm-central identity export prints the newest published registry as an identity inventory document for an external agent registry: ids, names and subjects as your tenant's keyed hashes, never a fingerprint or a key.

garm-central identity delegations
garm-central identity export

Checked by the walk: this command ran as written on a Central Lite host.

See also

Attribute AI spend by machine and person

Read your enrolled machines' model spend by day, machine, provider and model, and reconcile it against your providers' own usage and cost reports.

8. List principals in a machine's own policy

Without Central Lite, or before a machine enrols, its default.yaml can carry an identity section, read once when agentgarmd starts: the principals, the local uids whose tasks are theirs, their external identity, and the keyed fingerprints of their gateway keys under credentials. trusted_issuers pins your identity provider's public keys for the token endpoint and needs a gateway_issuer; on_invalid_assertion is alert or deny, and deny needs a trusted issuer. The proxy fingerprints each call's provider key and stamps the call with the matching credential and its principal.

sudo agentgarmd identity fingerprint reads a key on stdin, never as an argument, and prints fingerprint_key_id and fingerprint to paste into the list; never the key. The fingerprint key is the tenant's: enrolment replaces a machine's own with Central Lite's, so fingerprints computed before enrolment no longer match until you compute them again. sudo agentgarmd identity export prints the registry in force on that machine as the same inventory document as garm-central identity export; it is refused on a machine that never enrolled.

identity:
  on_invalid_assertion: alert
  gateway_issuer: https://ai-gateway.example.com
  trusted_issuers:
    - issuer: https://idp.example.com
      jwks: '{"keys":[{"kty":"EC","crv":"P-256","kid":"k1","x":"WbbiSIJZWAhTDtSnHd8w1JmZhHJpgSkwm4mlo0Nr0wY","y":"JYOH1Dv1UF9TaMm8FWLlLHGRp1xBTVdgVkvgiUP4b-4"}]}'
      algorithms: [ES256]
      client_ids: [claude-code]
  principals:
    - id: 01920000-0000-7000-8000-0000000000aa
      kind: human
      display_name: Alice
      uids: [501]
      external: { issuer: https://idp.example.com, subject: alice }
      credentials:
        - id: 01920000-0000-7000-8000-0000000000bb
          kind: gateway_api_key
          fingerprint: 3f1c0e0bb2a1f7c4a8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5
          fingerprint_key_id: fpk-0123456789abcdef
read -rs KEY && printf '%s' "$KEY" | sudo agentgarmd identity fingerprint; unset KEY
sudo agentgarmd identity export

See also

Give Claude Code a per-developer gateway key

Give each developer their own gateway key from Central Lite and let Claude Code fetch it through apiKeyHelper; a claude.ai login is never routed.