Control Channel
A single long-lived bidirectional gRPC stream carries everything that is not bulk telemetry:
identity, liveness, commands, and trust bundles. It runs between the agent’s channel::remotectl
and the gateway’s EndpointService (EndpointChannel RPC), and bridges to Kafka on the gateway
side.
Sequence
Frames
The first frame must be Hello, or the gateway rejects the stream with failed_precondition.
After identity is verified (see Enrollment), the gateway registers the live
downstream sender keyed by endpoint_id in its connection registry — this is what lets a Kafka
command find the right open stream.
| Direction | Frame | Meaning |
|---|---|---|
| up | Hello | Identity + host metadata; opens the stream. |
| up | Heartbeat | Liveness; the gateway “touches” the connection. |
| up | CommandResult | Outcome of a dispatched command → published to commands.response. |
| down | Command | Opaque backend-signed action (see Command Trust). |
| down | TrustBundle | Anchor-signed signing-key list; hot-swapped by the agent. |
Reconnect
The agent reconnects with exponential backoff on stream loss and re-sends Hello. The gateway drops
the stale registry entry when the stream ends, so downstream frames for a disconnected endpoint have
nowhere to route until it re-registers.