Security model
Identity
- Every node has its own key, created on the machine when it joins. The private key never leaves the node, and the agent runtime never holds it: the supervisor keeps it and runs a local proxy that adds the node's certificate to outgoing calls.
- Joining is pinned. The join token, or the
--ca-hashflag, carries the hash of the cluster's CA. The node checks the server's certificate chain against it before it sends anything. - Certificates last 24 hours and renew themselves over the control stream. A node that was offline can renew a certificate that expired at most seven days ago.
- Operators have certificates too.
server initcreates the first operator and writes a CLI context with its certificate. - Servers keep no keys on disk. Each server issues itself certificates from the cluster's CAs at start, in memory, and renews them daily. Holding the master key is what makes a machine a server.
Two ways in
| Join token | Approval | |
|---|---|---|
| How | orchestrator-zero token create, then join --token | join --ca-hash, then node accept |
| Who decides | Whoever holds the token | An operator, after comparing the node's fingerprint |
| Good for | Automation and many machines | Machines you want to check one by one |
Tokens carry a tenant, labels, an expiry and a maximum number of uses. Revoking a token stops new joins; nodes that already joined stay.
Cutting access
The edge authorizes every call from a node against the registry, which every server reloads every two seconds. A node must be accepted, use its own tenant's namespace, call only the Temporal methods a worker needs and poll only its own queues.
orchestrator-zero node block takes effect within two seconds on every server: the control stream closes, Temporal calls are refused and the node stops its runtime. Jobs that were running there continue on other nodes. node unblock lets it back in; the node notices within ten seconds.
Purging a node, so that it uninstalls itself with a command signed by management, is planned.
Secrets
- Secrets are sealed with AES-GCM under the cluster's master key and bound to the cluster, the tenant and the name, so a sealed value copied to another tenant does not open.
- Values are never shown. The admin API seals on the way in and never returns a value;
secret listshows names only. Changes are recorded in the audit log, without the value;orchestrator-zero auditreads it. - Only the edge unseals. Provider keys are added to model calls in the edge's LLM gateway. Nodes get a local LLM proxy and a per-start token instead, so no provider key is ever on a node.
Plugins are trusted code
Plugins run as processes with the node's permissions; there is no sandbox. Install only plugins you trust, and run nodes as a user without root. The edge records who installed which repository at which commit.
Tool processes get a minimal environment, not the runtime's, so they cannot read the local proxies' tokens.