Build NAS containers on TrueNAS libvirt-LXC, not Incus

Date: 2026-06-27 Status: Accepted Decision: hl-hghu Deciders: sean

Context

TrueNAS’s virtualization backend has churned: Incus-backed Instances (VMs + LXC) arrived experimental in 25.04, VMs reverted to libvirt/KVM in 25.04.2, and TrueNAS 26 makes LXC containers fully supported while switching their backend from Incus to libvirt (“incus has been removed”). On the nas box the Incus daemon is already gone; a hand-rolled Incus tree and the apps/incus-pool storage are orphaned.

Decision

Build the NAS tooling sandbox (and any future NAS containers) on the supported container.* middleware namespace — libvirt-backed LXC on TrueNAS 26 — rather than on Incus (raw incus CLI or middleware-as-Incus).

Rationale

• iX is removing Incus; building on it is building on a deprecated backend.
• container.* is UI-visible, upgrade-safe, and is the supported CORE-Jails migration path.
• container.create returns a libvirt UUID on 26, confirming the libvirt backend.

Alternatives Considered

• libvirt-LXC via container.* (chosen): supported, upgrade-safe, UI-visible.
• Raw incus CLI / community.general incus connection plugin (rejected): the backend is being removed; already orphaned on the current box.
• Docker custom app (partial): retained for service-shaped workloads (e.g. telemetry), but a poor fit for an interactive shell sandbox.
• libvirt KVM VM (rejected for the sandbox): full-OS isolation is overkill for tooling.

Consequences

• Positive: future-proof, supported path; the original “container with dataset access” design survives the backend swap intact.
• Negative: container.* is a moving BETA API (schema verified by spike); LXC is always unprivileged (see the idmap ADR).
• Neutral: orphaned Incus storage (apps/incus-pool, .ix-virt) becomes cleanup/migration work (epic phases P2/P3).