Operator directives: an authenticated channel to a running agent

Agents authenticate machines (mTLS, capability tokens, the host-side PAT) but not humans. lever msg, relayed email, and files arrive as unauthenticated text; the sender: "user:…" label on a message is stamped by the orchestration layer, not verified. A hardened manager therefore refuses out-of-band instructions from them. Operator directives are a signed, host-verified channel an agent can treat as authoritative without becoming a prompt-injection path.

A directive is not prose: it is a signed, host-verified artifact, delivered to the agent as an opaque pointer and fetched over the agent’s own authenticated channel. The model never checks a signature; all cryptography is host-side. The rationale and threat model are in security model §11.

How it works, end to end

Every failure mode — unknown id, wrong target, stale generation, already consumed, expired — returns the same byte-identical opaque {"error":"not found"}. There is no oracle for which failure occurred; a revoked caller gets 403, a rate-limited one 429. A read-only directive_check(id) exists too, target-gated with the same opaque miss.

Preview before consume

directive_consume is single use, so without a preview “read the request” and “commit to it” are the same step. directive_preview(id) separates them: the target agent reads the action, decides, and then consumes or leaves the directive.

The tool is in the agent image’s lever-agent binary: rebuild the agent image to get it.

Identity binding. A directive targets {cn, generation}, not a recyclable agent slug; consume requires the caller’s live CN and current generation to match (§11.4).

Directive state (active/consumed/revoked/invalidated/expired, plus tombstones for replay defence, plus per-CN generations) persists to .lever-state/directives.json with atomic writes, and consume/submit/preview fail closed on a persistence error rather than report a success that isn’t durable. invalidated is set on an active directive when its target CN re-enrols (generation bump).

This depends on per-agent network-namespace isolation; see worker isolation §4.3.

Directive kinds

Scope

The mechanism delivers authenticated, replay-proof delivery and verification of an operator-signed action bound to the target agent. It does not enforce the bound action at tool-call time: the agent makes the call through its ordinary capability path, under the existing grant checks, so a directive grants no new capability. For tool_call and approval, the execution boundary is model discipline, not a host-enforced gate. See §11.1.

Setup

The operator: config block

operator:
  allowed_signers: operator_allowed_signers   # ssh-keygen allowed_signers file; keep it OUT of tree:
  signing_key: /abs/path/to/operator          # default private key `lever directive send` signs with
  directive_expiry: 10m                        # optional; default 10m
  directive_expiry_max: 24h                    # optional; default 24h (hard cap — a larger value is rejected)

The whole block is optional. With allowed_signers unset, the channel is simply disabled — dormant, not a half-configured risk. allowed_signers is confined to the instance root (like manager.prompt_file); signing_key is a host path and deliberately not confined — the signing key must live outside the mounted tree, where a jailed agent can never read it. Put both at the host-only instance root, outside tree:, and gitignore the private key.

Generating a key

ssh-keygen -t ed25519 -f operator          # writes operator (private) + operator.pub

Add a line to the allowed_signers file naming the fixed principal operator@<instance-name>:

operator@myapp ssh-ed25519 AAAA...   # <type> <keydata> copied from operator.pub

Verify the wiring before you need it in anger:

lever directive selftest
# selftest OK: signing key verifies against the broker's allowed_signers

Key posture

Keep the key on the operator’s own machine or hardware-backed; never forward an SSH agent to the broker host; put two or more keys under the operator@<instance> principal so a lost key never locks you out. Editing allowed_signers takes effect immediately (the broker runs ssh-keygen -Y verify per call). Detail: §11.5.

Using it

# advisory instruction — no host enforcement, keep it rare
lever directive send manager --instruction "Hold all outbound email until I'm back online at 6pm."

# fully-bound tool call — args fixed at signing time
lever directive send worker-a --action '{"kind":"tool_call","tool":"db","op":"read","args":{"table":"orders"},"arg_binding":"exact","uses":1}'

# list what's outstanding
lever directive list --state active

# revoke one before it's consumed
lever directive revoke <directive-id>

send prints the exact statement bytes it’s about to sign, for operator review, before it sends anything. <agent> is the manager (manager or the app name) or a declared worker name; --expires defaults to operator.directive_expiry and is hard-capped at operator.directive_expiry_max (itself capped at 24h). The lifetime counts from the send time, not from --not-before. --key PATH overrides operator.signing_key (on send/list/revoke/selftest). --not-before RFC3339 sets the start of validity (default: now); a start more than 2 minutes in the future is refused by lever directive send before it contacts the broker (the broker enforces the same limit), so the flag only absorbs clock skew. --state on list accepts active|consumed|revoked|invalidated|expired. Every directive subcommand takes an optional trailing [CONFIG] path and otherwise reads ./lever.yaml, like the other lever commands.

The broker refuses a send, and stores nothing, when the target is not enrolled yet, when the target is not running (bring it up and send again), or when a tool_call/approval names a tool the broker does not know. If the notice does not reach the agent, the broker revokes the directive and send exits non-zero with the next step to take.

lever doctor reports an “operator directives” check: unconfigured is a pass (most instances never touch this), and once configured it verifies allowed_signers has at least one key, ssh-keygen is on PATH, and — if the broker is up — that the directive socket exists.

What this does NOT do

• It does not grant any capability the target did not already hold (see Scope).
• instruction directives authenticate only that the operator sent them; they never override a refusal of a sensitive or outbound action.
• It does not authenticate manager→worker messages. A directive for a worker is signed for that worker directly; authority does not launder through the manager.
• It does not hide directive ids from a compromised hub; ids are public. It protects the content and the single-use, target-bound consumption.

Threat model: security model §11. Config keys: config reference. Commands: CLI reference.