Cloud API

Kerrigan's cloud API is an asynchronous control and reporting model built on AWS IoT Core. It lets an authorized cloud caller discover a paired Kerrigan system, submit a command, follow that command's lifecycle, and read the latest reported appliance and fleet state.

The cloud path does not expose the Kerrigan admin interface or its REST API. The appliance initiates its cloud connection, and cloud callers interact with AWS services using their own IAM identity. The local REST API is only for a controller with direct network access to the Kerrigan admin interface.

Control model

The model separates commands from reported state:

1. Discover. A cloud application or control plane finds paired Kerrigan systems in the environment's AWS IoT Thing Group and joins them with the latest state in DynamoDB. The optional Cloud Control CLI exercises this same path for validation and troubleshooting.
2. Command. The cloud integration publishes a cluster-scoped command through AWS IoT Core. The immutable cluster_id determines which Kerrigan system receives it.
3. Execute locally. Kerrigan validates and persists the command, then asks its local Fleet Manager to perform the operation. Fleet Manager remains the authority for appliance and DevKit state.
4. Track. Kerrigan publishes received, accepted, progress, and terminal events. Callers correlate them with command_id and correlation_id.
5. Observe. Independently of commands, Kerrigan publishes fleet snapshots, heartbeats, and host state. Cloud infrastructure maintains a latest-state read model for discovery and status queries.

AWS IoT MQTT uses QoS 1, so delivery is at least once. Callers and consumers must tolerate duplicates. Command execution is made idempotent with a stable, caller-supplied command_id; reporting consumers evaluate freshness using the cloud ingestion timestamp rather than MQTT arrival order alone.

Interfaces

Interface	Use it for	Contract
Cloud Control CLI	Validate discovery and control end to end, or troubleshoot an integration. This optional reference client is not required in a production cloud integration.	IAM-authenticated AWS APIs and MQTT over WebSockets.
MQTT Control API	Implement a command producer or consume command lifecycle events.	Cluster-scoped command and event topics with JSON envelopes.
MQTT State Reporting API	Consume fleet snapshots, liveness, and host state.	MQTT reports, a named Device Shadow, and the cloud latest-state model.

For the cloud-infrastructure-agnostic NAT-traversal integration, see ICE Peer Pairing.

Cloud pairing

Activation-code pairing is implemented in the local Admin Console, local CLI, and Ubuntu host onboarding. Kerrigan generates its private key locally and submits only a CSR to the selected cloud environment. An authorized backoffice workflow claims the short-lived code, after which Kerrigan validates and atomically installs its AWS IoT certificate.

Pairing can be changed at any time. The current cloud profile stays active until the replacement is approved, so a cancelled, expired, or failed request does not interrupt reporting or control. The optional Cloud Control CLI can approve codes during validation; it is not required in a production integration.

See Pair Kerrigan with a Cloud Environment for the complete UI and CLI procedure, protocol flow, security controls, re-pairing behavior, and troubleshooting guidance.

SDK connection

See SDK Connection for the public-key exchange, WireGuard handshake, and NFS workspace mount coordinated through the MQTT Control API.

Choosing a DevKit connection model

Kerrigan supports two complementary ways to create a private network path to a DevKit. Both use WireGuard for authenticated, encrypted application traffic; they differ in how the two WireGuard peers reach each other.

Use case	Choose	Why
Kerrigan connects a DevKit to a controlled cloud SDK endpoint, such as a managed EC2 instance with a known address, endpoint automation, and an NFS workspace.	SDK Connection	The cloud integration can configure both WireGuard peers directly. There is no candidate exchange, STUN/TURN infrastructure, or NAT-traversal negotiation to operate.
An authorized developer needs to connect from a machine on an arbitrary network, including home, office, or changing NAT conditions.	ICE Peer Pairing	ICE tries to find a direct UDP path and falls back to a TURN relay when required. It carries the same kind of encrypted WireGuard traffic after path selection.

SDK Connection is therefore not superseded by ICE. It is the simpler, controlled-endpoint path; ICE is the flexible, developer-network path.

Trust boundaries

• Cloud callers authenticate independently and must be authorized for the selected environment and cluster topics.
• Kerrigan uses its appliance identity only for its outbound AWS IoT connection. A second client must not reuse that certificate or MQTT client ID.
• Topic policies should restrict each Kerrigan system to its own commands, events, and reporting paths.
• Cloud command acceptance does not bypass local safety checks, target availability, or Fleet Manager state transitions.