hive-runtime

Go binary — KAIROS event bus, resource governor, cascade engine, and health checker.

Status: Production on VPS (/root/hive/). This directory is the open-source scaffold — the full binary ships separately.

Architecture

hive-runtime/
├── cmd/hive/          Entry point (main.go)
├── internal/
│   ├── bus/           Event bus — envelope routing, fan-out
│   ├── governor/      Resource governor — RAM/CPU contracts
│   ├── cascade/       Cascade engine — BGP flap dampening, fallbacks
│   ├── health/        Health checker — 11 services, 5-second intervals
│   └── api/           WebSocket server (port 8765), HTTP health endpoint
└── cascade.toml       Service topology + cascade rules

Specs

• Binary size: ~9.4 MB
• Runtime RAM: ~4 MB
• WebSocket: 127.0.0.1:8765 (nginx proxy: /hive/ws)
• Envelope format (FROZEN): {id, from, to, type, priority, timestamp, payload}

Subsystems

Event Bus

Routes envelopes between subsystems. Fan-out to all WebSocket clients on every envelope. Typed channels per domain layer (see @kairos/hive-protocol).

Resource Governor

Reads /proc/meminfo, /proc/stat every 2 seconds. Tracks per-service RSS vs memory contracts. Emits metric envelopes when thresholds are crossed.

Cascade Engine

State machine with 5 states: nominal → degraded → cascade → recovering → recovered. BGP flap dampening per RFC 2439. Budget ceilings: $1/h, $5/d. Defined in cascade.toml.

Health Checker

Polls 11 services every 5 seconds. Emits heartbeat envelopes. Colors topology graph nodes in the dashboard.

cascade.toml

[service.groq_free]
priority = 1
budget_hourly_usd = 1.0

[service.ollama_local]
priority = 2
budget_hourly_usd = 0.0

[[cascade]]
name = "llm_inference"
primary = "groq_free"
fallback = "ollama_local"
trigger = "budget_exceeded"

Dashboard Integration

The dashboard connects via useHiveBus.ts (WebSocket auto-reconnect with exponential backoff). Pages that use it:

• Topologia — 3D force graph, 23 nodes (11 services + 12 agents), health coloring
• Presion — RAM treemap per service, contract bars, governor metrics
• Cascades — Service state log, transition history, flap dampening
• Timeline Hive — Live envelope stream (filterable, pauseable)
• Financiero — LiteLLM spend, daily budget bar ($5/d)
• Omniscient — Unified 3x2 grid of all Omniscient views

Building (Go 1.22+)

cd packages/hive-runtime
go build -o hive ./cmd/hive

Systemd

[Unit]
Description=KAIROS Hive Runtime
After=network.target

[Service]
ExecStart=/root/hive/hive
Restart=always
OOMScoreAdjust=-500

[Install]
WantedBy=multi-user.target

License

Apache-2.0 — see LICENSE