Architecture

Mentat is a Cargo workspace with 4 crates, each with a single responsibility. The system runs on a single GCP VM with nested KVM enabled.

Crates

mentat-types

Shared domain types: JobSpec, Task, Driver, Resources, Constraint, NodeInfo, Allocation, DeployConfig, ServiceSpec, MentatFile. Error handling with thiserror. YAML parsing with serde_yml.

mentat-agent

Runs on each host. Executes workloads via three drivers: FirecrackerDriver, DockerDriver, ExecDriver. Exposes HTTP API for task start/stop/status. Auto-registers with server on startup.

mentat-server

Control plane. REST API with axum, bin-packing scheduler, deploy orchestrator (rolling/blue-green/canary), sled-backed state persistence.

mentat-cli

The mt binary. Clap-based CLI with subcommands: run, status, scale, logs, nodes, deploy, rollback, canary. Parses YAML locally and communicates with mentat-server via HTTP.

Data Flow

1. User runs: mt run dune-stack.yaml
2. CLI parses YAML, validates, sends POST /v1/jobs to server
3. Server stores job + services in sled
4. Scheduler filters nodes by constraints, picks node with most RAM
5. Server creates Allocations, dispatches to agent
6. Agent starts workloads via appropriate driver
7. User queries: mt status → server returns allocation states

Key Types

mentat-types/src/types.rs

pub enum Driver { Firecracker, Exec, Docker }

pub enum DeployStrategy { Rolling, BlueGreen, Canary }

pub enum DriverConfig {
    Firecracker(FirecrackerConfig),  // image, memory, vcpus, volumes
    Docker(DockerConfig),            // image, env, ports, volumes
    Exec(ExecConfig),                // command, args, env
}

pub struct ServiceSpec {
    pub name: String,
    pub replicas: u32,
    pub config: DriverConfig,
    pub resources: Resources,
    pub constraints: Vec<Constraint>,
    pub deploy: DeployConfig,
}

Tech Stack

Runtime	tokio 1.x
HTTP API	axum 0.8
Serialization	serde + serde_json + serde_yml
State	sled 0.34
HTTP Client	reqwest (rustls)
Unix Sockets	hyperlocal + hyper
CLI	clap 4 (derive)
Error Handling	thiserror
IDs	uuid v4