Fleet Provisioning via Typed RPC

Summary: Expanding the 0x40-0x5F RPC command range with typed provisioning operations instead of tunneling SSH/Ansible over the mesh. Idempotent, declarative operations over LXMF store-and-forward.

Status: Draft — research documented, implementation not started.

Overview

Traditional fleet provisioning tools (Ansible, Salt, Puppet) assume SSH connectivity to target hosts. Styrene’s mesh operates over LXMF, which is delay-tolerant and store-and-forward capable. This document proposes typed RPC commands for provisioning operations that leverage LXMF’s delivery guarantees rather than requiring persistent connections.

Proposed Command Types

Seven new message types in the 0x40-0x5F RPC range:

TypeNamePurpose
0x48CONFIG_PUSHPush NixOS configuration fragment
0x49PACKAGE_ENSUREEnsure Nix packages are installed
0x4ASERVICE_STATESet systemd service state (start/stop/enable/disable)
0x4BFILE_WRITEWrite file to device (small files only — LXMF size limits)
0x4CSCRIPT_EXECExecute a provisioning script
0x4DSYSTEM_UPDATETrigger nixos-rebuild switch
0x4EHEALTH_CHECKRun health check suite, return structured results

Design Principles

  • Idempotent — Every operation can be safely re-sent. PACKAGE_ENSURE checks before installing; SERVICE_STATE is a desired-state declaration.
  • Declarative — Commands describe what, not how. The device’s styrened daemon interprets them against its NixOS configuration.
  • Store-and-forward — Commands queued at the LXMF propagation node are delivered when the device comes online. An operator can provision a fleet of offline devices and walk away.
  • Per-type authorization — Each command type can require a different authorization tier (e.g., HEALTH_CHECK is read-only, SCRIPT_EXEC requires elevated identity).

Ansible Connection Plugin

An Ansible connection plugin could map standard modules to Styrene RPCs:

Ansible ModuleStyrene RPC
nix_envPACKAGE_ENSURE
systemdSERVICE_STATE
copy (small files)FILE_WRITE
commandSCRIPT_EXEC
nixos_rebuildSYSTEM_UPDATE

This allows operators familiar with Ansible to target Styrene mesh devices without SSH.

Open Questions

  1. LXMF size limits for FILE_WRITE — Large files need chunking or out-of-band transfer
  2. Nix-specific operation semantics — How to handle nixos-rebuild failures mid-operation
  3. Rollback strategy — NixOS has native rollback; how to expose this via RPC
  4. Fan-out progress tracking — Batch operations across many devices need aggregated status
  5. Dry-run mode — Preview what a command would do without executing

References

Graph

Backlinks