1. meshctl CLI & Orchestration
meshctl is the declarative fleet management and orchestration CLI for Fleetmesh. Written in Rust, it provides operators with a fast, dependency-light controller to manage, inspect, reconcile, and deploy Fleetmesh nodes and peer topologies.
1.1. Overview & Capabilities
While meshnode is the persistent runtime daemon that maintains peer connections, cryptographic stores, and message routing, meshctl acts as the administrative control plane. It consumes Kubernetes-style declarative manifests (apiVersion: fleetmesh.org/v1alpha1) and communicates directly with local or remote node instances:
Non-Destructive Hot-Reconciliation (
meshctl apply): Applies declarative changes to peerings, ingress/egress rules, budgets, and trust policies dynamically against a running daemon via Unix domain socket without dropping active QUIC connections or interrupting sessions.Manifest Diffing (
meshctl diff): Computes terminal diffs highlighting exact property divergences between desired manifest declarations and live daemon state.Multi-Target Deployment Compiler (
meshctl export): Translates declarative fleet manifests into production-ready infrastructure templates: - Kubernetes (--target=k8s): Deployments, Services, ConfigMaps. - Podman Quadlet (--target=quadlet): Rootless container systemd units. - Hardened systemd (--target=systemd): Sandboxed.serviceand.timerunits. - Docker Compose (--target=compose): Multi-node local clusters.Fleet Observation & Monitoring (
meshctl watch): Provides a single-pane status display across an entire fleet over SSH, tracking protocol digest consistency, relay connectivity, compartment faults, and CI status.Independent Rust Conformance Engine (
meshctl conform): A clean-room implementation of the Fleetmesh store and reconciliation mechanisms written solely from the specification and test vectors, providing independent protocol verification.Linked Data Projections (
meshctl linked): Extracts and inspects the node’s schema.org JSON-LD metadata for services, standing reports, and Blossom blobs.
1.2. Architecture & Design
meshctl is built with a minimalist, high-reliability design philosophy:
Aspect |
Architecture Decision |
|---|---|
Language & Toolchain |
Rust 2021 (MSRV 1.84). Compiled as a statically linked, standalone binary. |
Transport & Control |
Unix domain socket IPC using the |
Network Dependencies |
Uses |
Security Sandbox |
Rootless execution by default. Can administer remote nodes entirely over secure SSH transport without special remote daemon agents. |
1.3. Installation
Build and install from the workspace repository:
cd meshctl
cargo install --path .
Or verify the build directly:
cargo run -- version
1.4. Quick Start
# Check status of local node daemon
meshctl status --dir /var/lib/fleetmesh
# Dry-run reconciliation of a peering manifest
meshctl apply -f manifests/peering.yaml --dry-run
# Apply live hot-reconciliation
meshctl apply -f manifests/peering.yaml
# Export manifest to Podman Quadlet systemd container
meshctl export -f manifests/meshnode.yaml --target quadlet > ~/.config/containers/systemd/node.container
# Inspect JSON-LD schema.org service descriptor
meshctl linked service --dir /var/lib/fleetmesh | jq .
1.5. Subsystems & Documentation
Document |
Description |
|---|---|
Complete reference for commands, flags, subcommands, and exit codes. |
|
Non-destructive hot-reconciliation mechanism, Unix domain socket control protocol, and zero-drop updates. |
|
Multi-target deployment compiler for Kubernetes, Podman Quadlet, systemd, and Docker Compose. |
|
Fleet observation over SSH, systemd timer integration, and protocol digest drift detection. |
|
Clean-room Rust conformance engine, wire protocol specification, and test vector coverage. |