Secrets
Secrets are stored per tenant, sealed with AES-GCM under the cluster's master key. The value never comes back out of the admin API; only the edge unseals it, when it needs it.
Set, list and delete
The value comes from stdin, an environment variable or a file, never from the command line, so it does not end up in your shell history:
printf %s "$ANTHROPIC_API_KEY" | orchestrator-zero secret set ANTHROPIC_API_KEY
orchestrator-zero secret set OPENAI_API_KEY --from-env OPENAI_API_KEY
orchestrator-zero secret set GITHUB_TOKEN --from-file ~/.secrets/github-token --tenant acme
orchestrator-zero secret list # names only, never values
orchestrator-zero secret delete GITHUB_TOKEN
Every change is recorded in the audit log, without the value.
What uses them today
| Secret | Used by |
|---|---|
ANTHROPIC_API_KEY | The LLM gateway, for models named anthropic/... |
OPENAI_API_KEY | The LLM gateway, for models named openai/... and OpenAI-compatible APIs |
| Any name you choose | The token for a private plugin repository, named with plugin install --secret; see Install and update |
Any name a plugin lists in requires.secrets | That plugin's tools, hooks and harnesses, as environment variables; see below |
| Any name a flow's webhook names | The edge, to check calls to the webhook; see Flows |
When a model call needs a key the tenant does not have, the gateway answers 412 with the command that sets it. An agent with a fallback model on another provider falls back to it; when no model has a key, the job fails at once with MissingKey and that command. See Troubleshooting.
Secrets for plugins
A plugin lists the tenant secrets its processes need in its manifest:
requires:
secrets: [JEV_API_KEY]
orchestrator-zero secret set JEV_API_KEY --from-file ~/.secrets/jev-api-key
When the edge sends a node its plugins, it unseals the secrets each one declares and sends them along, over the node's mTLS connection, to the nodes that run that plugin and to no others. The node keeps them in memory, never on disk, and starts the plugin's tools, hooks and harnesses with each one as an environment variable of the same name. Other plugins' processes do not get them.
- A missing secret:
plugin installwarns, and nodes report the pluginfailedwith the command that sets it, keeping a previous version running if they had one. - Rotation: after
secret set, every node that runs a plugin declaring the secret gets the new value within seconds and restarts its runtime, as for a new version. Running jobs carry on. - Trust: a secret is in the environment of the plugin's processes on every node that runs it. Install plugins that declare secrets as carefully as the secrets themselves.
plugin lint warns when a plugin asks for ANTHROPIC_API_KEY or OPENAI_API_KEY: with the gateway's key, a plugin could call the provider directly, unmetered and outside every budget. Agents and harnesses reach models through the gateway without it.