We're excited to announce the 26.05 stable release of Clan!
Since the 25.11 release in December, 41 contributors landed 2,849 commits across 1,086 merged pull requests in clan-core — roughly six merged pull requests every day for five months.
Please read the Upgrade Steps and Breaking Changes before bumping clan-core.
As described in our branching policy, each stable release gets its own branch that receives backports for important bug fixes and security updates, but no breaking changes. Because this is a new stable release, it is the point at which breaking changes are allowed — and they are documented below with a clear migration path.
As always, users are expected to track the matching stable nixpkgs input branch.
clan machines update now registers the new generation in the bootloader before activating it live. This guarantees the update survives a reboot even when live activation fails.
Previously, a blocked activation failed twice with an opaque error. Now Clan reports a clear message and tells you to reboot to apply the already-registered configuration.
Pass --no-check to force past inhibitors when you know it is safe. See the nixos-rebuild guide.
clan machines update --specialisation <name> activates a specific NixOS specialisation instead of the default system. Use it to switch a machine between hardware or service variants. See the specialisations guide.
Interactive vars prompts now keep the previous value by default. Clan only asks you to enter a new value when you pass --regenerate. This prevents clearing a secret by pressing enter, and fixes several multiline input bugs.
Clan now detects ZeroTier machine IPs automatically. You no longer configure targetHost to reach a machine over the mesh.
ZeroTier also supports running more than one network per clan. This is a breaking change with a required migration — see Breaking Changes.
The new p2p-ssh-iroh service provides NAT-traversing SSH over encrypted QUIC, so clan machines update reaches a machine behind NAT or a firewall without port forwarding or a VPN. It ships commented out in the default templates.
This is the infra-management layer, separate from your service mesh: iroh carries operator traffic (clan machines update), while a mesh VPN connects machines so services can talk to each other. Our goal is to try iroh as the default management transport.
The new forwardAgent option forwards your SSH agent to managed machines. It is available on clan.core.networking and on inventory deploy, and is disabled by default.
- inputs.clan-core.url = "https://git.clan.lol/clan/clan-core/archive/25.11.tar.gz";
+ inputs.clan-core.url = "https://git.clan.lol/clan/clan-core/archive/26.05.tar.gz";
inputs.nixpkgs.follows = "clan-core/nixpkgs";If you use ZeroTier, follow the ZeroTier migration guide
clan-core versionZeroTier has been reworked to support multiple-instance setups, and network IDs and machine IPs are now coupled to the instance name. As a result, clan.core.networking.zerotier.* has been removed and existing setups require migration.
The full step-by-step procedure is documented in the ZeroTier migration guide. Follow it before upgrading.
The sshd service now enables CA-signed host certificates by default and always uses your clan's internal domain (meta.domain from clan.nix) as a certificate search domain. Previously, the CA was only set up when you explicitly configured certificate.searchDomains.
As a consequence, the openssh-ca generator now exists for every clan that uses sshd. On the first upgrade you will likely see:
File 'id_ed25519.pub' of generator 'openssh-ca' does not exist.Fix: Run clan vars generate, then deploy as usual.
clan flakes create got replaced by clan initYou can now create a new clan with clan init:
- clan flakes create my-clan
+ clan init my-clanThe cli guides you interactively through the most important steps.
clan vms removedclan vms run and clan vms inspect have been removed, and vm is no longer a valid value for clan machines build --format. The vm vars backend was removed as well (see Vars Backends).
Clan is based on NixOS, therefore we inherit breaking changes from upstream. We do our best to prevent breakages and provide automated migrations and improved error messages. In rare occasions, however, you need to deal with upstream breakages directly.
This is the highest-risk change for remote, headless machines: a mistake here can leave a machine that only fails after a reboot, when you can no longer reach it. NixOS 26.05 makes the systemd-based initrd the default and deprecates the scripted implementation (removed in 26.11).
Most incompatibilities surface as evaluation-time assertions, but the following cannot be detected automatically:
fileSystems."/".device must be /dev/mapper/<name>, where <name> matches your boot.initrd.luks.devices.<name> definition, or systemd times out waiting for the passphrase and the machine never boots. For LVM-on-LUKS and similar setups, add "x-systemd.device-timeout=infinity" to fileSystems."/".options instead.cryptsetup-askpass no longer exists. Use systemctl default, which prompts for passphrases as needed. If you pipe the passphrase over SSH, use ssh -o RequestTTY=force so systemctl default gets a TTY./dev/root is gone: the scripted initrd created it from the root= kernel parameter; the systemd initrd does not. Replace any /dev/root reference in fileSystems with a stable path such as /dev/disk/by-uuid/..., /dev/disk/by-label/..., or the matching /dev/mapper/....You can temporarily revert with boot.initrd.systemd.enable = false, but this is discouraged and the scripted implementation is removed in 26.11.
dbus-brokerNixOS switched the default D-Bus implementation from dbus to dbus-broker. Because restarting D-Bus mid-session is unsafe, this is a switch inhibitor — the same upstream mechanism behind Safer machine updates. The first clan machines update after upgrading is expected to fail during live activation. This is not a failed deployment: the new generation is already registered in the bootloader, so reboot the machine to apply it. If you want to keep the old daemon set: services.dbus.implementation = "dbus";.
Expect possible hardware, driver, and out-of-tree module regressions. reiserfs (removed in Linux 6.13) and ecryptfs are no longer available. ZFS users should note that Clan's installer already tracks the latest ZFS-compatible kernel.
fileSystems.<name>.fsType is now mandatoryThe option no longer has a default value. Disko-managed disks and Clan's templates already set it, so most setups are unaffected — but hand-written fileSystems entries must now specify fsType explicitly.
networking.resolvconf.enable now defaults to trueIt previously defaulted based on whether environment.etc."resolv.conf" was set. If you define environment.etc."resolv.conf" yourself, you must now also set networking.resolvconf.enable = false.
x86_64-darwin support droppedSupport for Intel-based macOS (x86_64-darwin) has been removed; its lifecycle ends after 26.05 in nixpkgs. Apple-silicon macOS (aarch64-darwin) remains supported. If you manage Intel Macs with Clan, pin to the 25.11 branch or migrate those hosts before upgrading.
Beyond the command removals in Breaking Changes, several commands gained new flags and behavior
Most notably:
clan machines build gained --no-secrets, --no-sandbox, and --systemclan vars check and clan vars fix now accept zero or more machines. With no machine argument they operate on every machine in the clan.Clan's architecture lets you write your own services, and the community services collection continues to grow.
Moved out of clan-core into clan-community:
corednsNew in clan-core:
dm-dns: Data-mesher based name resolution (dns)ncps: Nix binary cache proxy servicepki: static certificates for clan servicesp2p-ssh-iroh: Experimental iroh based ssh accessinstaller: Experimental turns a machine into an installation imageNew in clan-community:
authelia: authentication and authorization serverdesktop: desktop environment/wayland compositor setupdm-pull-deploy: pull-based deployment via data-mesherdm-wireguard-star: data-mesher WireGuard star topologylocalsend: share files on the local networkmosquito: MQTT brokerpunchcard: time tracking servicewebapps: web application hosting servicewireguard-star: WireGuard VPN in star topologyThe set of vars backends has changed:
age (experimental)fs, vmNote: All
clan.core.varschanges in this release — including the newrecipientssettings andage.secretLocation— are experimental and subject to change without a guaranteed migration.
The new vars.settings.recipients options (available on both clan.core and the flake) let you declare who is able to decrypt your generated secrets, giving you direct control over secret access across the clan. Like the rest of the clan.core.vars changes above, this is experimental and very likely to be refactored in the next release — expect the interface to change, with no guaranteed migration.
Exports have been refactored. Services now declare what they export under manifest.out. Exports remain experimental — we're still collecting real-world feedback before stabilizing them. The available modules are:
| Module | Status |
|---|---|
peer | Refactored (since 25.11) |
networking | Refactored (since 25.11) |
dataMesher | New |
endpoints | New |
generators | New |
auth | New |
The table below lists every service shipped in clan-core for 26.05: its stability, whether it changed since 25.11, and a summary of the change. Services marked Experimental may change without a guaranteed migration. See the Clan Community section for services that moved out of clan-core.
| Service | Status | Changed | What changed |
|---|---|---|---|
| admin | Deprecated | No | |
| borgbackup | Stable | No | |
| certificates | Experimental | No | |
| data-mesher | Experimental | Yes | New roles bootstrap, default |
| dm-dns | Experimental | New | New service: data-mesher based DNS zone propagation |
| dyndns | Stable | Yes | extraSettings now accepts string, integer, or boolean |
| emergency-access | Stable | No | |
| garage | Stable | No | |
| hello-world | Experimental | No | |
| importer | Stable | No | |
| installer | Experimental | New | New service: turns a machine into an installation image |
| internet | Experimental | Yes | Added port, user settings; exports networking, peer |
| kde | Stable | No | |
| localbackup | Stable | No | |
| matrix-synapse | Stable | No | |
| monitoring | Experimental | Yes | Added roles client, server; removed role telegraf |
| mycelium | Stable | Yes | Exports networking, peer |
| ncps | Stable | New | New service: Nix binary cache proxy |
| p2p-ssh-iroh | Experimental | New | New service: iroh-based NAT-traversing SSH |
| packages | Stable | No | |
| pki | Stable | New | New service: static certificates for clan endpoints |
| sshd | Stable | Yes | Added authorizedKeys, certificate.enable, generateRootKey (server role) |
| syncthing | Stable | No | |
| tor | Experimental | Yes | Exports networking, peer |
| trusted-nix-caches | Stable | No | |
| users | Stable | Yes | Added identity, openssh.authorizedKeys.*, systemUser; exports auth |
| wifi | Stable | No | |
| wireguard | Stable | Yes | Added mtu (controller and peer); exports networking, peer |
| yggdrasil | Experimental | Yes | Added ports.*, multicastInterfaces, extraYggdrasilIPs; removed extraMulticastInterfaces; exports networking, peer |
| zerotier | Stable | Yes | Reworked for multiple instances (breaking); added allowedIds, public; exports networking, peer |
| coredns | Moved | Yes | Moved to clan-community |
clan.core optionsAdded (7):
clan.core.image.iso.addFilesScriptclan.core.networking.forwardAgentclan.core.networking.internalListenAddressesclan.core.vars.age.secretLocationclan.core.vars.settings.recipientsclan.core.vars.settings.recipients.defaultclan.core.vars.settings.recipients.hostsRemoved (17):
clan.core.networking.zerotier.*clan.core.vars.globalSettings.*clan (flake) optionsAdded (6):
deprecatedModulesinventory.machines.<name>.deploy.forwardAgentvars.settings.recipientsvars.settings.recipients.defaultvars.settings.recipients.hostsvarsDirectoryRemoved (14):
outputs.moduleForMachineThe bundled flake templates (clan templates) changed as follows.
disko/single-disk was renamed to disko/ext4-single-disk, and three Btrfs-based
schemas were added.
Added (4):
disko/btrfs-single-disk-subvolumes: single disk schema with Btrfs subvolumes and automated btrbk snapshotsdisko/btrfs-single-disk-subvolumes-impermanance-rollback: Btrfs subvolumes with a Btrfs-based ephemeral root (rollback) and automated btrbk snapshotsdisko/btrfs-single-disk-subvolumes-impermanance-tmpfs: Btrfs subvolumes with an ephemeral tmpfs root and automated btrbk snapshotsdisko/ext4-single-disk: classic GPT layout with an ext4 root filesystem (renamed from disko/single-disk)Removed (1):
disko/single-disk: renamed to disko/ext4-single-diskRemoved (2):
machine/demo-templatemachine/test-morph-templateAll clan templates were modernized and better integrated into the quick-start and clan-cli:
sshd, users, p2p-ssh-iroh, and an installer service.admin, zerotier, and tor dropped.{{name}}/{{domain}}.x86_64-darwin was dropped from the default systems.clan.core.clanPkgsMost packages have been removed from clan.core.clanPkgs — they were never intended for downstream usage. What remains:
zerotier-memberszerotieroneclanPkgs itself will be removed in the next release.
This release is the work of everyone who reported issues, reviewed pull requests, wrote documentation, and shipped code. Thank you to all who made 26.05 happen — from the people who landed hundreds of commits to those who fixed a single typo. Every contribution counts.
Release managers: @hsjobeki, @enzime