§08 · Deploy & operate

What is Exo Operator

The in-cluster operator that reconciles the autonomic.sh CRDs into running workloads and connects your deployment to the Exo control plane over one outbound WebSocket.

Exo Operator is the connector for a self-hosted deployment. It runs inside your Kubernetes cluster, authenticates with a deployment-scoped token, and opens one long-lived outbound WebSocket. Discovery, status streaming, I/O, and session audit all flow over that connection.

What Exo Operator is

Exo Operator is a control-plane client, not a server. It does five things on your side of the wire.

Discover. It watches the autonomic.sh CRDs with controller-runtime informers and pushes a full snapshot on first connect.
Stream changes. When an object changes (pod ready, resource crashed), a Delta frame reaches the control plane within a second.
Heartbeat. Keep-alives flow on the same connection. If they stop, the dashboard marks the deployment degraded, then offline.
Host I/O. When a user attaches to an agent shell, the operator opens a remote-exec PTY into the agent's container and proxies bytes both ways.
Reconcile resources. It's a full Kubernetes operator. It turns custom resources into running pods, Services, and Secrets, and reports status back over the wire. See Resources & CRDs.

One agent, one deployment

A deployment is one cluster installation. A deployment token binds 1:1 to a deployment. The control plane refuses a second active connection on the same token, using a last-writer-wins grace window. Two consequences follow.

Scaling out means running multiple operator replicas with leader election, not two unrelated tokens against the same cluster.
Multi-cluster tenants mint one token per cluster and see two deployments in the dashboard. That keeps staging separate from prod, and eu-west separate from us-east.

Resource discovery

The operator watches the autonomic.sh CRDs with controller-runtime informers. It reconciles each object into cluster workloads and streams four wire-form resource kinds the dashboard renders.

Kind	Short	Reconciles into	Status surfaces
`Agent`	`ag`	agent pod (agentlet + runtime)	`Pending` \| `Active` \| `Paused` \| `Error` \| `Terminating` \| `Succeeded` \| `Failed`
`Tool`	`tl`	on-demand pod	`Pending` \| `Ready` \| `Error` \| `Disabled`

Add and Update emit delta frames with op upsert; Delete emits op remove. A periodic Snapshot frame (cadence set per tenant) backstops the stream, so a dropped Delta is reconciled on the next tick.

Connection lifecycle

The connection states map to dashboard colour.

Bootstrap. The manager starts and, when AUTONOMIC_MANAGED=true, reads AUTONOMIC_BASE_URL and its token from AUTONOMIC_AUTH_TOKEN. See Connecting.
Handshake. A Hello frame carries the autonomic version, host metadata, and a boot_id.
Registration. The control plane binds the connection to the deployment. If another connection already holds it, the older one is evicted (last-writer-wins, closed with reason evicted by newer connection).
Discovery. The initial Snapshot lands in the dashboard.
Steady state. Deltas, heartbeats, audit, I/O, and pod-control frames flow both ways.
Disconnect and reconnect. Capped exponential backoff. The deployment goes degraded after the 90s grace window and offline after the 5m eviction window of heartbeat silence.