templates

a template is a git repo whose flake evaluates to a nixos system. there is no sdk, no required input, and no ix import: if it evaluates to a nixos system, ix boots it.

boot one

#name picks the configuration. the default is default.

the first build

the first ix new of a revision builds the configuration inside the machine that it creates. that machine is the build host, and you pay for its time like any machine. ix caches the result per region as a bootable template. every later ix new of the same revision boots the cached template in seconds, and every flag works.

ix templates rm frees a cache entry. --fresh ignores the cache and rebuilds.

the contract

expose your system under nixosConfigurations:

{
  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.05";

  outputs = { nixpkgs, ... }: {
    nixosConfigurations.default = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [ ./configuration.nix ];
    };
  };
}

ix adds a machine profile that sets the root device and console, configures platform networking, and disables the bootloader. your template controls everything else. when this profile changes, ix rebuilds the cached template.

a flake that exposes ix.<name> (the ix init scaffold shape) is used as-is. the platform profile is already implied there.

private repos

a private repo uses the github credentials that are already on your machine. ix uses them to pin the revision and to fetch inside the machine that builds it. the token is never stored and never logged. a template built from a private repo caches for you alone.

recommendations

• commit a flake.lock. ix pins your template’s revision, but your inputs are pinned only by your own lock file. without one, every fresh revision can rebuild a different world.
• write server-shaped configs. the machine does not exist yet: no hardware uuids, no laptop modules.