---
title: "Coordinate Agent State"
url: "https://docs.caracal.run/services/coordinator/"
markdown_url: "https://docs.caracal.run/markdown/services/coordinator.md"
description: "Service reference for agent sessions, delegation edges, invocations, and lifecycle events."
page_type: "reference"
concepts: []
requires: []
---

# Coordinate Agent State

Canonical URL: https://docs.caracal.run/services/coordinator/
Markdown URL: https://docs.caracal.run/markdown/services/coordinator.md
Description: Service reference for agent sessions, delegation edges, invocations, and lifecycle events.
Page type: reference
Concepts: none
Requires: none

---

Coordinator owns agent and delegation runtime state. SDKs and Console use it to create, inspect, suspend, resume, terminate, traverse, and revoke agent/delegation state.

## Runtime

| Property | Value |
| --- | --- |
| Port | `4000` |
| Health | `GET /health` |
| Readiness | `GET /ready` |
| Metrics | `GET /metrics` |
| Auth scope | `AGENT_COORDINATOR_SCOPE`, default `agent:lifecycle` in deployment templates |

## Dependencies

| Dependency | Purpose |
| --- | --- |
| Postgres | Agent sessions, service leases, invocations, delegation edges, graph epochs, Coordinator outbox. |
| Redis | Lifecycle, invocation, delegation, and revocation streams. |
| STS/JWKS | Token validation and authority alignment. |
| Coordinator token | Console/operator access to agent and delegation views. |

## Jobs

| Job | Purpose |
| --- | --- |
| TTL sweeper | Expires stale sessions and delegation state. |
| Service lease sweeper | Marks stale service agents unhealthy. |
| Deadline enforcer | Handles invocation deadlines. |
| Retention cleaner | Removes expired historical coordination records. |
| Outbox publisher | Publishes Coordinator outbox messages to Redis. |
| Lifecycle relay | Observes `caracal.agents.lifecycle` delivery with HMAC origin verification and dedupe. |

## Event Topics

Coordinator publishes `caracal.agents.lifecycle`, `caracal.invocations.lifecycle`, `caracal.delegations.invalidate`, and session revocation events.

## Next Step

Use [Issue Mandates](/services/sts/) to understand how STS validates sessions and delegation edges during token exchange.

## Related Pages

- [Use Coordinator API](/api/coordinator/)
- [Coordinate Agents](/architecture/delegation-flow/)
- [Manage Agents and Delegation](/runtime-console/agents/)