Fleet topology library — typed Pkl schema, Rust bindings, and Nix modules.
fleetix provides generic tooling for fleet-wide host, link, domain, and
service topology. A consuming flake owns the real topology data and generated
sidecars; Fleetix provides the Pkl schema shape, Rust bindings, export CLI, and
Nix modules that expose a generated topology to NixOS and Home Manager.
For paired full-stack dev/prod deployments and exact-output promotion, see
service surfaces. The opt-in NixOS modules and
fleetix-surfaces CLI keep each surface's data and credentials separate.
Cargo.toml— Cargo workspace containing the Fleetix and sidecar products.src/— Rust crate (fleetix) with topology types, accessors, and a CLI.crates/fleetix-sidecar/— standalone Pkl-to-Nix library and Rust executable.examples/Topology.pkl— self-contained synthetic topology example.lib/topology/— generic Pkl schema material; no production fleet data.modules/nixos.nixandmodules/home-manager.nix— consumer modules.
For shared MCP server declarations and client configuration, see
MCP adapters: fleetix.lib.mcp, fleetix.homeModules.mcp, and the
fleetix mcp managed-entry reconciler.
The separate, opt-in mcp-server Cargo feature provides a composable Rust MCP
server. fleetix mcp-serve PATH serves a selected topology snapshot over stdio;
downstream applications can register typed handlers with their own authorization.
See MCP server for the API and trust boundary.
fleetix.lib exposes pure helper functions for downstream flakes that need to
derive runtime data from a generated topology sidecar:
hosts.resolveHostAddressresolves a host through an explicit ordered address policy such as[ "lan" "direct-link" "wg-home" ].hosts.vpnProfileresolves a host-local VPN profile by host and profile name.services.resolveEndpointdeterministically resolves a local endpoint or its declared LANremoteViaendpoint for an ingress host.services.resolveProxyEndpointsresolves a proxy action'sendpointfollowed by its orderedfallbackEndpointsthe same way, for upstream failover. Validation requires every fallback to be a reachable HTTP endpoint sharing the primary'stransportandtlsServerName, without repeats.services.endpointsForHost,services.serviceHosts, andservices.managedDnsCnameIntentsderive host, HTTP-site, and DNS views. Likevpn,lansites (served by alan-scope ingress group) are private: they never get managed CNAMEs or public probes, and validation rejectsdnsPublication = "managed"for them; consumers publish explicit records.domains.publicationAddressIntentsrenders explicit static destinations and directly published apexes as A/AAAA ownership intents.adapters.infernix.mkFleetNodesconverts fleet host topology plus consumer-owned node overlays into Infernix node definitions.
Adapters stay intentionally thin: Fleetix provides network and service derivation, while consumers such as Infernix keep workload semantics, model inventory, scheduling policy, and application-specific defaults.
Host rebuild.buildCache is backend-neutral fleet policy. It records whether a
host should use a fleet build cache for selected package attributes, while the
consuming flake chooses the concrete cache implementation.
Host.management keeps installed-system SSH facts separate from LAN and public
service DNS. Its optional publicAddress is a literal unicast recovery IP,
sshPort overrides the caller's fleet default, and link selects a declared
host binding. Explicit routes require an enrolled hostPubkey; installer keys
and bootstrap ports remain installer-owned. Topology::management_routes
returns a shared-link candidate followed by independent public recovery. The
caller supplies source/target names and its default port, then probes candidates
and integrates them into its own routing policy.
Domains.publicationTargets maps names to PublicationTarget values containing
hostname, targetHost, ipv4, and optional ipv6. These are desired,
non-secret facts promoted into topology, never live provider state. An HTTP site
selects a destination through optional publicationTarget; selection requires
managed DNS-only public access and that host in the site's ingress group. Its
CNAME targets the destination hostname; an apex or destination-hostname site
gets address records instead. A null selector preserves legacy zone-apex CNAME
synthesis, and Pages destinations stay independent.
Validation rejects unknown destinations/hosts, duplicate destination names, invalid addresses, and competing DDNS, Pages or explicit/excluded A/AAAA/CNAME ownership. IPv4-only publication still owns absent AAAA, so reconciliation can remove stale IPv6. Consumers must validate topology before rendering or applying DNS. The Nix helper exposes address intents; consumers render absent IPv6 by omitting AAAA while retaining management of that record type.
These contracts require Fleetix 0.4 or later. Verify registry publication
before adding production callers. Existing serialized topology remains
compatible; Rust struct literals for Host, Domains, and HttpSite need the
new fields (or their available defaults) when adopting that release.
An optional gpu.render = new S.GpuRender { renderNode = "/dev/dri/by-path/pci-0000:03:00.0-render" }
declares a default game/3D device. This is independent of the video-decoding
gpu.media route and the compute request below. Use a stable PCI alias rather
than a probe-order renderD128 name. Runtime consumers must verify accessibility,
PCI identity and driver support; topology is desired configuration, not proof
that an application rendered on that device.
lib/topology/GpuContract.pkl exports the schema's stable-node pattern, vendor
and backend vocabulary, and shared conformance fixtures. Regenerate its Rust/Nix
consumer with pkl eval --format json lib/topology/GpuContract.pkl -o lib/generated/gpu-contract.json. Fleetix tests check producer drift and compare
official Pkl constraint enforcement with Rust parsing. Official pkl must be on
PATH for those tests; the Nix Cargo checks supply it.
fleetix.lib.gpu.routes projects a host GPU record to independent rendering,
media and compute defaults; fleetix.lib.gpu.forHost also retains inventory and
legacy aliases. Absent routes stay disabled. Consumers translate these roles to
their own framework controls and perform live device validation.
Rust applications can reuse fleetix::gpu::pci_selector with
default-features = false, which excludes the Pkl evaluator and Tokio. Enable
the pkl feature for loading/exporting Pkl and trust-source patching, and
health for live probes. The default CLI enables both features.
Hosts may declare gpu.compute = new S.GpuCompute { backend = "oneapi" }.
The optional request targets the dGPU when present, otherwise the iGPU.
Validation requires oneapi on Intel, rocm on AMD, or cuda on NVIDIA.
Omitting compute preserves existing consumer policy. This is a requested
stack, not proof of runtime device availability; package selection and hardware
verification belong to the consuming application/configuration.
Rust consumers can add fleetix = { version = "0.6", default-features = false, features = ["pkl"] }
to their Cargo dependencies and
call fleetix::pkl_to_nix::write_with_cache_sync or its async counterpart.
The library evaluates Pkl through the published pklx crate; a Fleetix Nix
flake input is not needed to run the Rust generator. The Fleetix flake remains
available for NixOS/Home Manager modules and Nix helper functions.
Enable mcp for the harness adapter APIs, or cli for the standalone executable.
Simit generates verification and crates.io publication workflows:
simit init ci --platform github --runtime nix --workspace --publish-crates.
Release tags are signed package versions; member publishing is generated by
Simit. The workspace policy is recorded in simit.toml. Regenerate its workflows
with the command above and verify with simit init ci --workspace --check --diff.
Generate these workflows with Simit 0.20.0. The aggregate verification workflow
is .github/workflows/ci.yaml; .github/workflows/nix-builds.yaml retains
revision/tree-bound evidence for the production packages and Nix checks. The
signed-tag .github/workflows/publish-workspace.yaml builds credential-free
archives for both members at the same version. The independent
.github/workflows/trusted-publish-workspace.yaml admits those archives and
publishes fleetix-sidecar before Fleetix, with exact registry resolution between
them.
Before enrolling publication, configure SIMIT_PUBLISHER_REVISION to an
independently qualified immutable Simit revision and place CRATES_IO_API_TOKEN
only in the simit-crates-io environment restricted to protected trunk.
Repository and organization credentials must not be exposed to the tag-controlled
workflow. Retry the original signed-tag run for release recovery. Canix consumers
need Fleetix 0.6.1 or later for Train::dispatch_where; verify publication
before upgrading their Cargo dependency.
The CI environment retains the repository's Nix module checks; Rust consumers
still resolve and build the published library entirely through Cargo.
See product boundaries for the deployment extraction contract.
See shared native construction for the optional build-train
library, standalone request lifecycle and builder-local NixOS service.
fleetix::pkl exposes generic Rust helpers for downstream crates that keep
their canonical config in Pkl:
load(path).awaitevaluates a Pkl file and deserializes it into any serde model.load_sync(path)provides the same behavior for synchronous command-line code.string_literal(value)renders strings safely for generated Pkl files.
Generate Nix files directly with the standalone Rust CLI. From this workspace:
cargo install fleetix-sidecar --path crates/fleetix-sidecar --locked
fleetix-sidecar generate examples/Topology.pkl topology.nix
fleetix-sidecar check examples/Topology.pkl topology.nix
# Existing Fleetix command remains compatible:
fleetix pkl-to-nix examples/Topology.pkl topology.nixThe sidecar crate owns the evaluator, renderer,
dependency cache and atomic writer. It has no Fleetix topology, Canix, Nix or
external Pkl executable dependency. Its standalone check compares exact bytes
without writing output or cache and exits 2 for drift. Consumers may compare
evaluated Nix values to allow formatting changes, as Canix does.
fleetix::pkl_to_nix re-exports this library, preserving existing callers such
as canix config generate, canix config check, and canix config render.
Direct library-only consumers can depend on fleetix-sidecar with default
features disabled after verifying publication. Publish the sidecar prerequisite
before a Fleetix release that depends on it. Nix packages/apps remain available
for installation and qualification, but generation does not evaluate a flake.
fleetix::pkl_to_nix::{render, write, write_sync} provides the same generator
to Rust consumers. Writes preserve unchanged files and reuse a private,
dependency-checked cache under $XDG_CACHE_HOME/fleetix/pkl-to-nix (or
~/.cache/fleetix/pkl-to-nix). Imported files and the modular topology's
flattened sources invalidate the cache by content. Evaluations that read
environment or remote resources are never cached. Pass --no-cache to force
reevaluation, for example in a reproducibility check.
Topology-specific consumers should keep using export-nix when they need
Fleetix's normalized topology rendering.
Validate a topology before consuming it. Human diagnostics are the default;
automation can request a stable JSON report containing severity, code,
path, value, and message for every issue:
fleetix validate examples/Topology.pkl --format jsonThe NixOS module is disabled when fleetix.source = null (the default). Set
fleetix.source to a generated Nix sidecar to populate fleetix.topology:
{ config, ... }:
{
imports = [ fleetix.nixosModules.topology ];
fleetix.source = ./lib/generated/topology.nix;
}The Home Manager module has one integration mode: when imported by Home
Manager with an osConfig, it mirrors osConfig.fleetix.topology; when used
standalone it remains an empty, opt-in surface. Fleetix does not own a
consumer's machine data or deployment policy.
The declared Rust MSRV is 1.88, required by the resolved pklr dependency.
CI also checks the pinned current stable Rust 1.96.1 toolchain so the minimum
compatibility promise and modern compiler behavior are tested separately.
nixosModules.boot-operations runs one-shot host maintenance during boot,
while no user session or user service holds the affected state: renaming a
tree that live processes reference by path, retiring a compatibility symlink,
rewriting state a user service keeps open. Each operation is a oneshot unit
ordered before systemd-user-sessions.service and guarded by
ConditionPathExists=/run/nologin, which systemd creates only at boot. A live
switch therefore leaves a newly declared operation pending until the next
reboot instead of running it under active sessions.
{ pkgs, ... }:
{
imports = [ fleetix.nixosModules.boot-operations ];
fleetix.bootOperations.rename-data = {
user = "alice";
commands = [ [ "${pkgs.coreutils}/bin/mv" "-T" "/srv/old" "/srv/new" ] ];
requiresMountsFor = [ "/srv" ];
};
}An operation runs once per definition: success records a marker under
/var/lib/fleetix/boot-operations/ keyed by a hash of its user, commands,
environment and path, so changing any of them schedules it again (once = false runs it on every boot). A failure leaves no marker and is retried on the
next boot; it never delays logins beyond timeoutSeconds. Inspect an operation
with systemctl status fleetix-boot-op-<name>.
fleetix::supply merges producer facts (fleetix.supply-facts.v1), such as
Simit's usage facts and an operator's enrollment overlay, into one graph. It
reports which usages no upgrade path covers, and why. See
Supply facts.
fleetix supply gaps --facts facts.json --topology Topology.pkl --by repo
fleetix supply path rev:github.com/example/tool@<sha> --reverse --facts facts.json
fleetix supply graph --facts facts.json --facts overlay.json
fleetix supply budget --facts facts.json --facts overlay.json --topology Topology.pklDual-licensed under MIT or Apache-2.0, at your option.