cnix

nixvps

Summary

nixvps collects NixOS guest policy for tiny cloud VMs, down to a 256MB floor: conservative runtime profiles, provider-facing guest requirements, and lifelines for machines with very little RAM. It is the receiver side only; the producer side such as caches, signing, and publishing is intentionally left to the adopter.

The repository is explicit about scope: boot policy belongs to the boot project and every delivery path belongs to the deploy project. Its older pull-update, deploy-target, and image-bake implementations remain present but are marked as deprecated ownership overlaps to remove as consumers move, rather than described as already migrated.

What it is

  • tiny-vm.nix: baseline profile for the roughly 1 vCPU and 1 GB RAM class (bounded journald, clamped daemon parallelism, automatic GC, capped boot generations).
  • nano.nix: tighter profile for the 256MB to 512MB floor (serial builds, aggressive limits, minimal units, constant-memory monitoring).
  • lifeline.nix: four independently toggleable headless-survival mechanisms (connectivity watchdog, SSH lifeline, serial console flight recorder, external heartbeat).
  • pull-update.nix, deploy-target.nix, image-bake.nix: earlier autonomous update, deploy-target, and cloud-image implementations, retained as deprecated overlaps.
  • Declared checks (checks/image-bake-module-eval.nix, checks/pull-update-module-eval.nix, checks/pull-update-generation-guard.nix, checks/lifeline-host-health*.nix), examples/, studies/, and BUILD-CONTRACT.md.

It is not a boot loader, image publisher, or deployment orchestrator.

How it works

Every profile setting uses lib.mkDefault, so adoption is an overlay of conservative defaults the operator can narrow. The tiny-VM profile tunes mounts, journals, daemon concurrency, and generation counts for the 1GB class; the nano profile tightens further for the absolute floor.

Lifelines compose independently under nixvps.lifeline.*: the watchdog guards connectivity on an interface, the SSH lifeline preserves admin access, the console leg records flight data over serial, and the heartbeat reports outward. The pull-update timer path fetches a signed closure pointer for unreachable nodes behind NAT, while image-bake parameterizes a systemd-repart cloud image with systemd-boot and a btrfs root as a starting point rather than a turnkey per-provider image.

How to configure it

Compose the wanted NixOS modules, then enable profiles and lifelines under the observed nixvps.* surface:

  • nixvps.tinyVm.enable or nixvps.nano.enable — the RAM-class baseline, never both as primary. At the pinned revision neither profile evaluates cleanly (tiny-vm.nix sets retired services.journald.extraConfig); see Evidence and limits before enabling either.
  • nixvps.lifeline.watchdog.enable with iface — connectivity guard.
  • nixvps.lifeline.sshLifeline, console, heartbeat — remaining survival legs.
  • nixvps.pullUpdate, nixvps.deployTarget, nixvps.imageBake — deprecated overlaps; prefer their owning projects for new use.

Review BUILD-CONTRACT.md, examples/configuration.nix, and studies/lifeline-escalation-ladder.md before enabling lifelines on a host without console access.

Tutorial

This example uses invented values against the real option interface from the referenced revision. The interface shape below was evaluated with the actual nixosModules.lifeline module at the pinned revision using synthetic values only; nothing was deployed.

# Synthetic example: invented host and interface choices.
{
  imports = [ inputs.nixvps.nixosModules.lifeline ];
 
  nixvps.lifeline.watchdog = {
    enable = true;
    iface = "demo0";
    probeTargets = [ "192.0.2.1" ];
  };
}

This example deliberately enables only the lifeline survival leg and leaves the tiny-vm and nano profiles disabled: at the pinned revision tiny-vm.nix still sets the retired services.journald.extraConfig option, which the pinned nixpkgs rejects at evaluation, so no executable example can honestly enable tiny-VM policy until the upstream source is fixed (see Evidence and limits). The watchdog requires at least one probe target, asserted at evaluation time, and documentation addresses stand in for real ones.

Building the parameterized image target uses the host configuration:

# Synthetic example: public placeholder only.
nix build .#nixosConfigurations.demo-host.config.system.build.image

Treat every setting as an overridable default to review against the provider’s actual RAM class and console availability.

Evidence and limits

This page is bound to public revision fa60fe2106e3fae85cb4aa19b23857faee86d2ba. That tree contains the flake outputs, modules/ implementations, checks/ evaluations, examples/, studies/, lib/pull-update-generation-guard.sh, and BUILD-CONTRACT.md discussed above.

CNIX has not independently established a successful evaluation, build, boot, deployment, or workload result for that revision. The tutorial interface above was evaluated against the real lifeline module at that revision with synthetic values and no residual assertions. The tiny-vm and nano profiles are not demonstrated anywhere on this page: enabling them fails evaluation at the pinned revision because tiny-vm.nix sets the retired services.journald.extraConfig option, and disabled profiles are not validated tiny-VM policy. Memory-floor claims, lifeline behavior, and delivery-module deprecation state are described from source structure, not from reproduced runs.

nixvps owns tiny-VM guest policy and headless survival only. Host-memory tuning, boot policy, delivery orchestration, share mounting, and notification dispatch are sibling concerns with their own revision-addressed concepts. Its relationship to other Corbet Nix projects is currently a shared design direction, not evidence of runtime integration.