Transport

The Keeper-to-agent connection is built on a single long-lived gRPC bidirectional stream over mTLS. This section covers how the channel is protected and why the agent needs no inbound ports.

gRPC bidirectional stream over mTLS

The main channel between the Keeper and the agent is a bidirectional gRPC stream wrapped in mutual TLS (mTLS):

• Mutual authentication. The TLS handshake verifies both sides: the agent confirms it is talking to its own Keeper, and the Keeper confirms that the peer on the wire is a host it knows with a valid SoulSeed. The channel accepts no anonymous peers.
• The certificate itself is the authority on identity. Who has connected is determined by the agent’s mTLS certificate (its fingerprint is checked against the registry), not by an identifier the agent reports in the payload. You cannot impersonate another identity by sending someone else’s SID in a message — a SID is not proof.
• One active stream. At any moment the agent holds exactly one stream to one Keeper; switching between Keeper instances is seamless (a new stream opens before the old one closes).

Over this stream the Keeper delivers tasks and the agent returns events and run reports — all in one protected connection.

The agent initiates the connection

The stream is always opened by the agent — the Keeper never connects to the managed host itself (in pull mode). This gives a key property for perimeter security:

• Managed hosts need no inbound ports. The agent needs no open port for anyone to reach from outside; it establishes an outbound connection to the Keeper itself.
• The only open port on the host is the local metrics listener, and even that listens on loopback by default and is not exposed externally.

This removes an entire class of risk: across the managed souls there are no listening services reachable from the network — nothing to scan and nothing to attack from outside.

Push mode — the opposite direction

In push mode (over SSH, with no agent installed) the direction is reversed: the Keeper itself initiates the SSH session to the host. There the channel is protected by SSH authentication rather than an mTLS stream. Pull mode (agent) and push mode (SSH) are two independent ways to manage hosts; what is described above about inbound ports applies to pull mode.

Bootstrap channel

Onboarding a new agent (exchanging the token and CSR for a SoulSeed) goes over a separate listener with server-only TLS — at this step the agent does not yet have its own certificate for mutual authentication. Once the agent has the SoulSeed, further communication moves to the main mTLS stream. Procedure details — Identity → CSR onboarding.

Shared PKI root

For mTLS to work, both sides must trust the same certificate authority.

• The Keeper’s server TLS and the agent certificates are issued from the same PKI root (Vault PKI, see Secrets). If the Keeper’s server certificate is signed by a different root, agents will not trust it — mutual trust breaks and the stream will not be established.
• A practical takeaway when configuring: the Keeper’s server certificate for the gRPC channel to agents cannot be taken from just anywhere (for example, a public ACME certificate for a web domain) — it must originate from the same root as the hosts’ SoulSeed certificates.

Vault handles this PKI (issuance, signing, rotation); the CA private key lives in Vault and never materializes on the cluster’s disks.