opschain admin trust assign

packs:agents

opschain admin trust assign --scope <node-path> (--agent <code> --project <code> | --subject <principal-id>) [--note <text>]

Assigns assets under management to an agent (the v2 TrustService.CreateTrustAssignment verb): records that this agent is the subject matter expert for a node-path subtree. An assignment is three things at once:

• the agent's inventory — first-class and listable, per agent via opschain admin agent assignments or fleet-wide via opschain admin trust assignments;
• the scope of the configurable ADVISE floor: with no matching trust grant, an assignment covering the path lets the agent produce recommendations — unless the server runs the strict posture (agents.assignment_floor set to deny, where even recommendations require an explicit ADVISE grant);
• the natural scope to hang higher-tier grants on later (opschain admin trust grant).

The subject is one agent: --agent plus --project (resolved to the agent's service-account principal at write time), or --subject with the principal id directly. The scope must be an absolute node path; like grant scopes, it covers its whole subtree. Writes recompile the trust snapshot immediately and are audited.

Flags

Flag	Meaning
--scope <path>	Node-path subtree the agent manages. Required.
--agent <code>	Agent code (with --project).
--project <code>	The agent's project (with --agent).
--subject <id>	Service-account principal id (alternative to --agent).
--note <text>	Audit note stored on the assignment.
--server <url>	Server base URL. Default: the active context, then OPSCHAIN_SERVER.
--auth-token <token>	Admin bearer token override. Default: your opschain login session, then $OPSCHAIN_ADMIN_TOKEN, then the token stored by opschain admin login for that server.

Output

Always a machine document (JSON unless -o yaml): the stored assignment, including the ID that opschain admin trust unassign takes.

Exit codes

Code	Meaning
0	The assignment was stored.
1	The server refused the assignment (validation, unknown agent, rejected admin token).
2	Usage — the scope flag not set, or no server / admin token resolvable.

Named errors

Server-side (422, exit 1):

• no such agent in that project
• agent assignment subject is required
• agent assignment scope must be an absolute node path

CLI-side:

• required flag(s) "scope" not set — exit 2.
• a server is required — pass --server <url>, set OPSCHAIN_SERVER, or 'opschain context use <name>' — exit 2.
• this command needs a login or an admin token — run 'opschain login', pass --auth-token, set OPSCHAIN_ADMIN_TOKEN, or store one with 'opschain admin login' — exit 2.
• the server rejected the credential — run 'opschain login' again, or check the admin token — exit 1.

Example

opschain admin trust assign --agent sre --project demo \
  --scope /projects/demo/environments/prod --note "owns prod runbooks"

Related settings

• agents.assignment_floor — what the assignment confers with no matching grant: advise (default) or deny.

See also

• opschain docs cli/admin-trust-unassign — remove an assignment.
• opschain docs cli/admin-trust-assignments — list them all.
• opschain docs cli/admin-trust-grant — raise the agent above the floor.