Manage Agents and Delegation

Agent sessions and delegation operations are Console workflows backed by the Coordinator. They are not top-level runtime CLI commands.

Requirements

Input	Purpose
Coordinator endpoint	Automatic for local dev/stable; explicit only for cloud/custom deployments.
CARACAL_COORDINATOR_TOKEN or CARACAL_COORDINATOR_TOKEN_FILE	Coordinator authority for agent and delegation views.
Selected zone	Scope for agent session and delegation queries.

For the default local stack, Console prefers the Coordinator token generated by caracal up so a purge/up cycle does not leave an old exported token in use.

Agent Sessions

Open agent session with r to list agent sessions, inspect a session tree, suspend an active subtree, resume a suspended subtree, or terminate a session. Tree views show parent-child relationships so operators can understand inherited authority.

Delegation

Open delegation with g to inspect active, inbound, and outbound delegation edges. Detail views show source and target sessions, resources, scope bounds, expiry, and traversal state.

Revoking a delegation edge ends the delegated authority immediately. Review outbound edges before terminating an agent session so dependent work can be stopped cleanly.

Audit Correlation

Agent session IDs and delegation edge IDs appear in audit events. Use audit request tracing or request trace when you need the policy decision and diagnostic payload behind an allow or deny.

Troubleshooting

Symptom	Check
Agent session views are empty	Confirm the selected zone and that workloads are creating agent sessions through an SDK.
Coordinator token missing	Run caracal up locally or set CARACAL_COORDINATOR_TOKEN_FILE for a remote Coordinator.
Delegation revocation appears delayed	Confirm resource servers consume revocation state and reject revoked delegation anchors.