Tessera

A small control plane. Tessera schedules workloads (processes / containers) across a fleet of nodes, splitting a control plane from a data plane, and keeps the fleet converged through a reconciliation loop rather than imperative commands.

The name: a tessera is a single tile in a mosaic. Every node and every workload is one tile; the control plane assembles the whole picture.

Model

Tessera does not tell nodes what to do step by step. The user declares a desired state (which workloads should exist). Agents on each node report an observed state. A reconciler diffs the two and emits the actions that close the gap: schedule a pending workload, reschedule a workload off a dead node, stop a workload that was removed.

The loop is idempotent. Running it twice yields the same result as running it once.

            desired state  ──┐
                             ├──▶  reconciler  ──▶  actions
            observed state ──┘

Components

Three binaries, one Cargo workspace:

Crate	Role	Responsibility
tessera-control	control plane	HTTP API, SQLite store, reconciliation loop
tessera-agent	data plane	Runs on each node: heartbeat, executes workloads, reports
tesseractl	CLI	apply / get / describe / delete against the API
tessera-types	shared	Node and workload types, the workload state machine

Workload lifecycle

A workload moves through an explicit state machine. Invalid transitions are rejected, not silently applied.

Pending ─▶ Scheduled ─▶ Provisioning ─▶ Running
                             │             │
                             ▼             ▼
                          Failed ◀───▶  Stopping ─▶ Stopped

Design records

The reasoning behind each decision lives in docs/rfd/, in the Request for Discussion form Oxide uses:

• RFD 1: Tessera, a miniature control plane
• RFD 2: The workload state machine
• RFD 3: Reconciliation, declarative convergence and idempotence
• RFD 4: Node health and failure detection

Building

cargo build
cargo test          # unit tests plus the end-to-end HTTP test

Trying it out

Start the control plane:

cargo run --bin tessera-control

Bring up an agent. --simulated runs workloads without spawning real processes, which is enough to watch the control loop work:

cargo run --bin tessera-agent -- --simulated --name node-a

Declare a workload and watch it converge, using tesseractl:

echo '{"name":"web","spec":{"command":"/bin/sleep","args":["3600"]}}' > web.json
cargo run --bin tesseractl -- apply -f web.json
cargo run --bin tesseractl -- get workloads

The workload starts Pending, the reconciler places it on the node, and the agent reports it Running. No step was commanded; the loop converged.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Control Plane                           │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │   HTTP API   │  │  SQLite Store│  │  Reconciler Loop │  │
│  │  (Dropshot)  │  │              │  │   (2 s interval) │  │
│  └──────────────┘  └──────────────┘  └──────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│  Agent A     │      │  Agent B     │      │  Agent C     │
│  heartbeat   │      │  heartbeat   │      │  heartbeat   │
│  executor    │      │  executor    │      │  executor    │
└──────────────┘      └──────────────┘      └──────────────┘

Observability

Every component emits tracing spans:

• API handlers log request method, path, and status.
• Store operations log the query and duration.
• Reconciler passes log the number of nodes evaluated, workloads placed, and nodes marked offline.
• Agent loops log heartbeat results and workload sync outcomes.

Set RUST_LOG=tessera=debug to see the control loop converge in real time.

License

MPL-2.0.