Skip to main content

Architecture

Kerrigan separates lab control from device execution.

GitHub Actions
  -> kerrigan-runner-bridge
  -> Fleet Manager API
  -> Device Agent on each DevKit
  -> test command, CTest, artifact install, or firmware workflow

Fleet Manager​

Fleet Manager owns:

  • target registration and heartbeat
  • pools and labels
  • session scheduling
  • boot and artifact resolution
  • firmware update state
  • system image download state
  • DHCP-driven bootstrap jobs
  • authentication and admin APIs

The service stores state in SQLite by default.

Dashboard​

Dashboard is the operator UI. It is intended for lab setup, pool and device management, firmware operations, and workflow visibility.

Device Agent​

The device agent runs on each DevKit. It discovers Fleet Manager, registers the device, sends heartbeats, polls for work, executes tasks, streams results, and performs cleanup.

Discovery priority is:

  1. explicit --server-url
  2. KERRIGAN_SERVER_URL
  3. /etc/kerrigan/agent.toml
  4. DHCP-provided URL through environment
  5. UDP multicast discovery
  6. DNS well-known names
  7. local default http://127.0.0.1:8000

Dispatcher​

The GitHub dispatcher and runner bridge connect GitHub Actions to Kerrigan sessions. A workflow checks out code, points KERRIGAN_MANIFEST at a YAML manifest, and runs kerrigan-runner-bridge.

Device bundle policy and maintenance​

Fleet Manager merges a system bundle policy with per-component pool overrides. Each bootstrap/post-flash job and pool upgrade records an immutable snapshot of agent, Sentinel, and P2P forwarder builds, the Sentinel playbook commit, and the sima-cli version with artifact checksums. The snapshot can also opt into Kerrigan-managed Developer Portal authorization; only the policy mode is immutable, while short-lived credentials are projected separately and never persisted in the snapshot. Retries reuse the snapshot. Saving a manual policy affects future setup without upgrading existing devices.

The shared installer stages separate Python environments plus the Sentinel and P2P forwarder binaries, then activates them with service configuration and validates the Sentinel API, native binary checksums, sima-cli version, and a fresh device-agent heartbeat. SQLite stores component progress, completed receipts, rollout history, and exclusive device reservations. Reservations exclude tasks, firmware updates, reboots, deletion, and pool moves. Failures pause a rollout; incomplete recovery retains the reservation. Interrupted updates attempt rollback before allowing an operator-requested retry.

Device address contract​

Device identity is independent of network address. The agent refreshes its controller-facing source IP on registration and heartbeat. The historical API field latest_ip carries this management address, with explicit management_ip/KERRIGAN_MANAGEMENT_IP and legacy latest_ip/KERRIGAN_LATEST_IP overrides. reported_ip separately stores the general/display address. HTTP peer addresses and forwarding headers are never used as management-address fallbacks. See device management address for precedence and proxy/NAT requirements.