Skip to main content

Installing kixctl

kixctl runs two ways, and which one is yours depends on a single question: do you already run an Incus fabric?

  • You don't, or you want kixctl to own the box. Run the appliance — a prebuilt image that is the hypervisor and the control plane together. It brings its own Incus; you never install or configure Incus yourself.
  • You already run Incus. Bolt on — run the kixctl control plane and point it at the cluster you already have. kixctl enrolls with a restricted, project-scoped credential it cannot widen, and it never mutates infrastructure it doesn't own.

Both are first-class. The appliance is the turnkey path; the bolt-on is for operators who already have a fabric and want the control plane on top of it.

The appliance​

The appliance is a prebuilt image that powers on straight into a first-run wizard. It carries its own Incus, its own storage, its own networks and DNS and edge — Incus is invisible underneath, and there is no operating system to learn. Today it ships as a VM image you run on any hypervisor. (A bare-metal installer ISO — the "burn it, boot it, it installs to disk" flow — is next; see The bare-metal installer below.)

Your audience runs hypervisors already, so running the image as a VM is usually the most natural way in — the same motion you'd use to spin up any other guest.

Steps​

  1. Download the appliance image from the v0.1.0 release — the file named kixctl-0.1.0.qcow2.zst (a qcow2 disk compressed with zstd). Grab sha256sums.txt from the same release to verify it: run sha256sum -c sha256sums.txt in the download folder and you want kixctl-0.1.0.qcow2.zst: OK.

  2. Decompress it. The image was packed with a large window, so pass --long=27 on the way out:

    zstd -d --long=27 kixctl-0.1.0.qcow2.zst

  3. Create a UEFI virtual machine with that qcow2 as its disk. Sensible starting point: 64-bit UEFI firmware, ≥ 4 vCPU, ≥ 4 GB RAM, and a disk with room to grow — the appliance auto-expands its root filesystem to fill the disk on first boot, so give it more than the image's own size. Enable nested virtualization on the host only if you want the appliance to run nested VMs; system-container workloads don't require it.

  4. Boot it. It comes up on your network with an address from your DHCP. Find that address in your hypervisor's console or your DHCP leases.

  5. Open https://<address>/ in a browser. First contact is served with an internal-CA certificate, so your browser will show a trust warning — this is expected on a fresh appliance, and it's the same thing Proxmox shows you on install. Click through it.

  6. Run the first-run wizard. Set your domain, create the admin account, and choose Start fresh — the appliance drives its own Incus over its local socket. It stands up its bridge, DNS resolver, and edge, propagates your domain, and hands you the dashboard.

From here, Your first deploy takes an application from a git push to a live revision.

Notes for common hypervisors​

  • Proxmox — create a VM (UEFI/OVMF, q35), then import the qcow2 as its disk and attach it. Boot from it.
  • Incus — incus-migrate imports the qcow2 directly as a virtual machine: choose Virtual Machine, point it at the file, decline Secure Boot, and give it a NIC on your LAN bridge so it gets a routable address.
  • libvirt / QEMU — boot it as a UEFI (OVMF) guest with the qcow2 attached as a virtio disk.

Bolt-on: run the control plane against your own Incus​

If you already operate an Incus fabric and don't want the appliance to own a box, run the kixctl control plane yourself and enroll your existing cluster. Enrollment uses a restricted, project-scoped client certificate: kixctl gets exactly the access it needs and cannot raise its own scope, and registering existing networks or profiles records references to them without ever mutating what it doesn't own. This is the multi-cluster path — your clusters, and your clients', from one pane — that a general hypervisor structurally can't offer.

Today the bolt-on is the run-from-source path: kixctl isn't yet packaged for a one-command install, so you provide Postgres and Valkey and run the control plane and its workers directly. It's documented under Running from source. A packaged bolt-on — a container or an installable build you point at your cluster — is on the roadmap.

The bare-metal installer (roadmap)​

The Proxmox-style experience — insert the media, boot it, it installs to disk, you reboot into the running system — is the next distribution item.

Be aware of what the ISO in the current release actually does: it boots the appliance live, in RAM, with nothing persisted. It's a zero-commitment way to kick the tires, not an installer — reboot and it's gone. To actually run the appliance today, use the VM image above. A true install-to-disk ISO is being built and will land in a later release; until it does, the docs won't tell you to install from the ISO, because it can't yet.