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.

Fleetmesh Logo

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 .service and .timer units. - 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 meshnode-control/1 protocol. Zero exposed network admin ports.

Network Dependencies

Uses tungstenite and rustls with webpki-roots for relay querying. No heavy async runtime (zero Tokio overhead), keeping binary size minimal.

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

meshctl CLI Reference

Complete reference for commands, flags, subcommands, and exit codes.

Non-Destructive Hot-Reconciliation

Non-destructive hot-reconciliation mechanism, Unix domain socket control protocol, and zero-drop updates.

Multi-Target Deployment Compiler

Multi-target deployment compiler for Kubernetes, Podman Quadlet, systemd, and Docker Compose.

Fleet Monitoring & Supervision (meshctl watch)

Fleet observation over SSH, systemd timer integration, and protocol digest drift detection.

Independent Rust Conformance Engine

Clean-room Rust conformance engine, wire protocol specification, and test vector coverage.