mkHost API

Parameters

nixfleet.lib.mkHost {
  hostName    = "myhost";
  platform    = "x86_64-linux";
  stateVersion = "24.11";       # optional
  hostSpec    = { ... };         # optional
  modules     = [ ... ];         # optional
  isVm        = false;           # optional
}

Return type

• Linux platforms (x86_64-linux, aarch64-linux): Returns the result of nixpkgs.lib.nixosSystem.
• Darwin platforms (aarch64-darwin, x86_64-darwin): Returns the result of darwin.lib.darwinSystem.

Platform detection is automatic based on platform.

Injected modules

mkHost injects framework modules before user-provided modules. These are mechanism-only - no opinions about packages, services, or user environment.

NixOS (Linux)

1. system.stateVersion (mkDefault)
2. nixpkgs.hostPlatform set to platform
3. hostSpec module (option declarations)
4. hostSpec values set with lib.mkDefault (overridable by consumer modules)
5. hostSpec.hostName forced to match the hostName parameter
6. Impermanence scope from nixfleet-scopes (declares options only - inert unless nixfleet.impermanence.enable = true)
7. Core NixOS module (_nixos.nix)
8. Agent service module (disabled by default)
9. Control plane service module (disabled by default)
10. Cache server service module (disabled by default)
11. Cache client module (disabled by default)
12. MicroVM host module (disabled by default)
13. User-provided modules

When isVm = true, additionally injects:

• QEMU disk config and hardware configuration
• SPICE agent (services.spice-vdagentd.enable)
• Forced DHCP (networking.useDHCP = lib.mkForce true)
• Software GL (LIBGL_ALWAYS_SOFTWARE, mesa)

Why impermanence is auto-imported: NixFleet’s internal service modules (agent, control-plane, microvm-host) conditionally contribute to environment.persistence. The NixOS module system validates option paths even inside lib.mkIf false, so the impermanence scope must be present to declare those options. The scope is inert (zero cost) until explicitly enabled.

Darwin (macOS)

1. nixpkgs.hostPlatform set to platform
2. hostSpec module (option declarations)
3. hostSpec values set with lib.mkDefault (overridable by consumer modules)
4. hostSpec.hostName forced to match the hostName parameter
5. hostSpec.isDarwin = true
6. Core Darwin module (_darwin.nix)
7. Agent Darwin module (disabled by default)
8. User-provided modules

NOT auto-included

These are consumer responsibilities - import them via roles or explicitly in modules:

• disko - disk partitioning (import from nixfleet-scopes or use diskoTemplates)
• base scope - opinionated system defaults (import from nixfleet-scopes)
• home-manager - user environment management (import from nixfleet-scopes)
• operators scope - multi-user inventory (import from nixfleet-scopes)
• All other infrastructure scopes - firewall, secrets, backup, monitoring, etc.

The typical pattern is to import a role, which bundles the relevant scopes:

modules = [
  inputs.nixfleet.scopes.roles.workstation  # includes base, HM, operators, etc.
  ./hardware-configuration.nix
];

Framework inputs

Framework inputs are passed via specialArgs = {inherit inputs;}. Modules can access them as the inputs argument. These are NixFleet’s own inputs (nixpkgs, home-manager, disko, impermanence, etc.), not fleet-level inputs.

Home Manager

Home Manager is a scope from nixfleet-scopes. It is not auto-injected by mkHost.

Import it via a role (workstation and endpoint roles include it) or manually:

modules = [
  nixfleet.scopes.home-manager
  { nixfleet.home-manager.enable = true; }
];

The scope fans out profileImports to all operators with homeManager.enable = true.

Scope re-exports

NixFleet re-exports nixfleet-scopes so consumers do not need a separate flake input:

# These are equivalent:
inputs.nixfleet-scopes.scopes.roles.workstation
inputs.nixfleet.scopes.roles.workstation

Available under inputs.nixfleet.scopes:

• scopes.roles.* - workstation, server, endpoint, microvm-guest
• scopes.base - opinionated system defaults
• scopes.home-manager - HM integration
• scopes.impermanence - impermanence support
• scopes.disk-templates.* - disko disk layouts
• All other nixfleet-scopes exports

Exports

All exports from the NixFleet flake: