> ## Documentation Index
> Fetch the complete documentation index at: https://ventstream.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent enrollment

> Bootstrap a managed engine with a one-time grant, then use renewable mTLS workload identity.

Enrollment converts a short-lived, one-time grant into a deployment-bound X.509
workload identity. The grant is only for bootstrap. Restarts use persisted identity
state, and the supervisor renews certificates before expiry.

## Flow

1. Create a pipeline and deployment in the selected environment.
2. Request an enrollment grant for that deployment.
3. Put the returned token in a short-lived Kubernetes Secret or equivalent secret
   injection mechanism.
4. Start the managed-agent enrollment init container using the trust mode in the
   Cloud installation profile.
5. The init container verifies server TLS, redeems the grant, and persists identity
   state. The main engine container never mounts the enrollment token.
6. The supervisor opens an outbound mTLS control stream and reports its instance.

```bash theme={null}
ventstreamctl agents create orders-primary --pipeline orders-cdc
ventstreamctl agents enroll-token create <deployment-id> --pipeline orders-cdc
```

<Warning>
  The grant is displayed once, expires after ten minutes, and is invalidated after
  successful redemption. Do not place it in a configuration revision, shell history,
  log, image, or GitOps file.
</Warning>

Cloud gateways use public WebPKI trust by default. Private gateway deployments
use a customer-provided CA Secret. After the first successful enrollment, the
chart detects persisted identity before reading the bootstrap files, so the
consumed grant Secret and optional private CA Secret can be removed.

The agent persists its private key and management state on its own volume. If the
pod restarts, it reconnects with the existing identity. If the workload identity is
revoked, reconnects are rejected and re-enrollment requires a new deployment grant.

Managed first boot fails closed: without a trusted desired-state snapshot, the
supervisor does not start CDC. A temporary Fleet outage does not stop an engine
that already has trusted running state.

One enrollment grant bootstraps one credential state. Do not use one grant Secret
to start multiple new replicas. Automatic chart enrollment currently supports one
replica; replicated realtime requires separately provisioned managed identities
or the standalone realtime gateway chart.