topology

Cortex Topology & Correlation

Answer "what's connected to what" and "what else was happening" questions across the fleet, backed by cortex's inventory graph and heartbeat state. This is distinct from incidents (error/alert triage) and troubleshoot (fixing a specific broken thing) — use this skill when the question is about structure or cross-host timing, not about diagnosing a failure.

Workflow

1. Inventory and dependency questions — map

cortex action=map [mode=...] [host=...] [domain=...] [service=...] [host_limit=N] [include_sections=[...]] [finding_types=[...]]

No CLI equivalent exists for this action — it's MCP/REST-only (POST /mcp action=map, or the /api surface). mode selects the answer shape:

• omitted or snapshot — full inventory dump: nodes, services, compose_projects, reverse_proxies, networks, storage, media_services, projects, plus a cortex_overlay summary. Use for "what's out there" broad surveys.
• host_services (needs host) — services running on one host.
• service_dependencies (needs service, as host:name or host + bare name) — what a service depends on / is depended on by.
• domain_routes (needs domain) — which reverse-proxy routes serve a public domain.
• findings — scans for potential_public_route, risky_mounts, and collector_health issues; narrow with finding_types.

Responses include a graph_answer field for graph-backed modes and a cache_status/freshness field — treat a stale cache as a caveat on the answer, not a hard error.

2. Single-host or fleet-wide heartbeat state

cortex action=host_state host=<name> [since=...] [limit=N] (CLI: cortex state host <name> [--since T] [--limit N])

cortex action=fleet_state [include_ok=false] [sort=pressure|freshness|hostname] (CLI: cortex state fleet [--sort ...])

Use host_state when the user names a specific host ("what's dookie's state"); use fleet_state for "what's unhealthy across the fleet" — include_ok=false (the default) already filters to hosts that aren't status == "ok", so you don't need to filter the response yourself.

3. Correlating events around a point in time

cortex action=correlate reference_time=<ISO> [window_minutes=N] [severity_min=...] [host=...] [source=...] [query=...] [limit=N] (CLI: cortex correlate events --reference-time <ISO> [--window-minutes N] ...)

Groups matching logs by hostname into CorrelatedHost buckets. limit is silently capped at 999, not 1000 — the implementation over-fetches by one row to detect truncation and search already hard-caps at 1000; don't be surprised if a limit=1000 request effectively returns 999.

cortex action=correlate_state reference_time=<ISO> [window_minutes=N] [host=...] [severity_min=...] [limit=N] (CLI: cortex correlate state ...)

Same idea as correlate, but joins in heartbeat summaries per host instead of just logs — use this when you need to know not just "what logs fired" but "what state was each host reporting" at that moment. There's also cortex correlate topic (backs the topic_correlate action) for resolving a topic to graph entities first and correlating everything related into one timeline — reach for that when the user names a concept/service rather than a bare time window.

4. Graph entity, neighborhood, and explanation queries

cortex action=graph mode=entity key=<name> entity_type=<type> [alias_type=...] [alias_key=...] [limit=N] (CLI: cortex entity <entity-type> <key> [--limit N], or the shorthand cortex entity <entity-type:key>, or cortex entity --alias-type T --alias-key K for alias lookups)

Look up one entity. Valid entity_type values: host, container, service, app, source_ip, ai_project, ai_session, error_signature, compose_project, reverse_proxy, domain, network, storage, config_artifact.

cortex action=graph mode=around entity_id=<id>|key=<name> [depth=1] [limit=N] [evidence_sample_limit=N] (CLI: cortex graph around <entity-type> <key> [--limit N], or cortex graph around --entity-id <id> [--limit N])

One-hop neighborhood of relationships around an entity (v1 supports depth 1 only) — use for "what's directly connected to X".

cortex action=graph mode=explain entity_id=<id>|key=<name> [depth<=3, default 2] [beam_width=N] [max_chains=N] (CLI: cortex graph explain <entity-type> <key> [--depth N] [--beam-width N] [--max-chains N], or cortex graph explain --entity-id <id> [--depth N])

Multi-hop narrative explanation chaining relationships out to depth hops — use when the user wants "how are X and Y connected" rather than just the immediate neighbors.

cortex action=graph mode=evidence ... (CLI: cortex graph evidence <evidence-id> [--payload-budget BYTES]) fetches the underlying evidence samples backing a specific relationship — use to back up a claim from around/explain with concrete log/event citations rather than asserting the graph edge exists.

All graph-backed responses report nodes: Vec<HomelabMapNode> (for map) or relationship/evidence lists bounded by payload_budget — treat a non-empty collection_errors or truncation flag as a caveat to surface, not something to silently drop.

Choosing between these four families

• Know the host/service, want what's on/around it → map.
• Know the host, want its live health → host_state/fleet_state.
• Know roughly when, want what happened everywhere → correlate / correlate_state.
• Know two named things, want how they relate (with citations) → graph (around for direct links, explain for multi-hop, evidence to back a specific edge).

These compose: e.g. map mode=service_dependencies can surface an entity key, which you then feed into graph mode=explain for a deeper multi-hop story with evidence, or into correlate at a specific time to see what else fired alongside it.

Guardrails

• Don't present map's snapshot or graph's neighborhood results as currently-true state without noting cache_status/freshness — the inventory is a periodically-refreshed projection, not a live poll.
• Don't claim a dependency or connection exists without it appearing in a map/graph response or its evidence — this skill is for evidence-backed topology, not inference from naming conventions.
• Respect the correlate 999-row cap; if a response looks truncated, narrow the window or host filter rather than assuming you saw everything.
• If map/graph responses report collection_errors or a stale freshness, surface that to the user rather than treating the rest of the response as complete.