—
type: article
name: article-s7-06
created: 2026-08-11
updated: 2026-08-11
status: drafted
series: “S7 (Security & Sovereignty)”
series_number: 6
series_name: “Security & Sovereignty”
grounding:
– “wiki/port-map-observability”
– “wiki/service-health-checks”
– “wiki/docker-swarm-stack”
tags:
– “security”
– “observability”
– “port-maps”
– “service-health”
– “monitoring”
– “docker-swarm”
– “agent-fleet”
– “sovereign-infrastructure”
– “health-checks”
– “prometheus”
– “grafana”
– “openfang”
– “council-system”
– “kanban-orchestrator”
– “ai-agents”
wiki_concepts:
– “port-map-observability”
– “service-health-checks”
– “docker-swarm-stack”
skills:
– “docker-crashloop-diagnosis”
—
# Port Maps and Service Health: The Observability Skeleton
## Introduction: the fleet that cannot see itself is the fleet that will fail
Every autonomous agent fleet runs on services. The Hermes gateway, the kanban board, the workspace dispatcher, the gateway tunnel, the MariaDB backing store — each one lives on a port, exposes an endpoint, and answers health checks. When a service fails silently, the fleet loses a limb without knowing which one. The observability skeleton is the system that makes those limbs visible: a port map that names every service and its port, health checks that confirm each service is alive, and a monitoring layer that watches for degradation before it becomes outage.
This is not about dashboards. It is about the minimum viable structure that lets a sovereign fleet detect its own failures, diagnose them without external tools, and recover without human intervention. The port map is the anatomy. The health checks are the pulse. The monitoring layer is the nervous system that connects them.
## The port map: anatomy of a sovereign stack
A sovereign stack runs everything locally. There is no cloud load balancer to abstract away the port assignments. Every service occupies a port on the host, and the port assignments are the physical topology of the fleet.
A minimal port map for a Council-class fleet:
| Service | Port | Protocol | Health Endpoint |
|———|——|———-|—————-|
| Hermes Gateway | 7077 | HTTP | /healthz |
| ZeroClaw | 7078 | HTTP | /status |
| OpenFang | 7076 | HTTP | /health |
| Lucid Hive WordPress | 8080 | HTTP | /wp-admin |
| MariaDB | 3306 | TCP | mysqladmin ping |
| ChromaDB | 4002 | HTTP | /api/v2/heartbeat |
| Hermes HUD | 3001 | HTTP | /api/health |
| OpenStation (Vite) | 3000 | HTTP | (static serve) |
This map is not documentation. It is a machine-readable artifact. The fleet’s orchestration layer loads it, binds health checks to it, and uses it to route traffic. When a new service joins the stack, it gets a port entry before it gets a container. The port map is the constitution of the fleet’s physical layer — the first thing you check when something breaks, and the last thing you change.
The critical property is sovereignty: every port is on localhost or the Tailscale network. No service is exposed to the public internet without an explicit tunnel. The port map is the internal nervous system; the gateway tunnel is the only nerve that reaches outside.
## Health checks: pulse points that tell the truth
A port map without health checks is a map of assumptions. A port that answers HTTP 200 does not mean the service is healthy — it means the port is open. Real health checks verify the service’s internal state.
There are three tiers of health checks, each more expensive than the last:
**Tier 1: liveness.** Is the process running? Can it accept a TCP connection? This is the cheapest check and the most common lie — a process can accept connections while its internal state is corrupted. Docker’s built-in HEALTHCHECK is tier 1. It tells you the container did not crash. It does not tell you the service is useful.
**Tier 2: readiness.** Can the service handle its expected workload? A database that answers pings but cannot write because its disk is full is not ready. A gateway that responds to /healthz but has lost its upstream connections is not ready. Tier 2 checks exercise the service’s actual capability: the gateway checks its upstream pool, the database tests a write-and-read cycle, the workspace dispatcher confirms it can reach the kanban board.
**Tier 3: correctness.** Is the service producing correct output? This is the most expensive check and the only one that truly verifies health. A Prometheus exporter that returns stale metrics is alive but not correct. A kanban board that serves cached data while its SQLite is corrupted is ready but not correct. Tier 3 checks compare expected output against actual output — they verify the service’s contract, not just its availability.
The Council runs tier 1 checks on every service, tier 2 checks on critical-path services (gateway, database, workspace dispatcher), and tier 3 checks on data-integrity services (kanban board, vault index). The tradeoff is explicit: tier 3 checks are expensive and can themselves cause outages if they compete for resources with the service they are checking.
## The monitoring layer: connecting pulse to nerve
Health checks produce data. The monitoring layer makes that data actionable. The architecture is deliberately simple:
1. **Health check probes** run on a schedule (every 30 seconds for tier 1, every 5 minutes for tier 2, every 15 minutes for tier 3). Each probe writes a timestamp, status, and latency to a health log.
2. **The health aggregator** reads the log and computes state: is each service in its expected state? How long has it been degraded? Is the degradation getting worse? The aggregator is not a separate process — it runs inside the gateway, which already knows about every service it routes to.
3. **The alert path** fires when a service exceeds its degradation threshold: three consecutive tier-1 failures, two tier-2 failures, or any tier-3 failure. Alerts go to the kanban board as comments on the affected service’s task, not to external notification systems. The fleet diagnoses itself.
4. **The recovery path** is automated for tier-1 failures (Docker restarts the container) and semi-automated for tier-2 failures (the workspace dispatcher re-routes traffic around the degraded service). Tier-3 failures are escalated to human review because they indicate data corruption that automated recovery might worsen.
This is the observability skeleton: not a full monitoring stack, but the minimum structure that lets the fleet detect, diagnose, and recover from its own failures. Prometheus and Grafana are optional layers on top — useful for dashboards and historical analysis, but not required for the fleet to function. The skeleton works without them.
## The sovereign advantage: why local-first observability matters
Cloud-native observability assumes you can ship logs to a central store, metrics to a time-series database, and traces to a distributed tracing system. Sovereign observability assumes none of that. The health data lives on the same machine as the services it monitors. The monitoring layer is a local process, not a SaaS subscription. The alert path is a local notification, not an email to a cloud service.
This constraint is a design advantage. It forces the health checks to be lightweight (no sidecar containers, no OpenTelemetry collectors), the monitoring layer to be self-contained (no external dependencies), and the recovery path to be local (no cloud API calls to restart a container). The fleet can diagnose itself while air-gapped, which is the only time sovereign infrastructure is actually sovereign.
The port map is the key. When you know every port, every service, and every health endpoint, you can build a monitoring system that fits in a shell script. The complexity of modern observability stacks comes from the assumption that you do not know your own topology. The port map removes that assumption.
## Why this matters for customers
For businesses deploying sovereign agent infrastructure, the observability skeleton is a trust signal. A fleet that can detect and diagnose its own failures is a fleet that does not require 24/7 human monitoring. The port map is verifiable — a customer can inspect it and confirm that every service is accounted for. The health checks are auditable — the logs prove that each service was checked and what the result was. The monitoring layer is transparent — there are no black boxes between a failure and its detection.
This is the practical expression of the security series: not just protection against external threats, but self-awareness of internal state. A fleet that knows itself is a fleet that can prove its own health to the people who depend on it.
—
*This article is S7.06 in the Security & Sovereignty series (S7). It continues the port-map observability framework introduced in the Council system and grounded in the docker-swarm-stack architecture. For the full series map, see [[CONTENT-ROADMAP-99]].*
## Semantic Relationships
– [[docker-swarm]] — provides memory for
– [[port-map-observability]] — provides memory for
– [[service-health-checks]] — provides memory for
– [[openfang]] — provides memory for
– [[kanban-orchestrator]] — provides memory for
– [[council-system]] — provides memory for
