KVM quickstart

Run the Pixop Prime appliance on your own KVM host. Pixop supplies a QCOW2 image and a host installer archive; this guide covers install and day-one operation.

Deeper guides: KVM deployment guide (delivery verification, host packages, disk planning) · KVM troubleshooting guide · KVM commissioning sheet (one-page acceptance) · pixop-install (command reference).

AWS Marketplace AMIs and KVM QCOW2 builds follow independent publication schedules. Use pixop-version on the guest and your delivery record to see what is installed—do not assume feature parity with a Marketplace listing.

What you need

The guest is Amazon Linux 2023 with the same Pixop stack as AWS. EC2 IMDS and Marketplace activation are not used on KVM.

Prepare the host

Extract the installer archive on the KVM host so the top level includes a scripts/ directory (pixop-install, lib-install.sh, create-seed.sh, pixop-license-guest.py). Illustrative layout:

cd /path/to/extracted-installer
ls scripts/pixop-install

Verify SHA-256 for the QCOW2 and the installer archive using each delivered .sha256 file (full sha256sum -c workflow in the deployment guide). Stop if either check fails.

On Ubuntu 24.04, install six virtualization packages if they are not already present (see Host packages in the deployment guide), or add --install-packages on install only on Ubuntu 24.04 after you approve apt changes. With that flag, missing packages may be installed before the interactive domain-name confirmation. Never use --install-packages during --dry-run.

cd /path/to/extracted-installer
sudo ./scripts/pixop-install doctor

doctor is read-only (PASS / WARN / FAIL). Resolve every FAIL before installing. The installer does not enable IOMMU, create bridges, or change firmware.

Install on a LAN bridge (production)

br0 must already exist. The installer attaches virtio-net to that bridge and does not create bridges, start the VM, or enable autostart.

Preview with --dry-run (same flags as the real install):

cd /path/to/extracted-installer
sudo ./scripts/pixop-install install \
  --dry-run \
  --image /path/to/pixop-prime-kvm.qcow2 \
  --gpu all \
  --vcpus 8 \
  --memory 16G \
  --bridge br0 \
  --ssh-key ~/.ssh/id_ed25519.pub \
  --license /path/to/license.jwt

Then install without --dry-run:

cd /path/to/extracted-installer
sudo ./scripts/pixop-install install \
  --image /path/to/pixop-prime-kvm.qcow2 \
  --gpu all \
  --vcpus 8 \
  --memory 16G \
  --bridge br0 \
  --ssh-key ~/.ssh/id_ed25519.pub \
  --license /path/to/license.jwt

Use --gpu 0000:0a:00.0 instead of --gpu all for a single GPU. install is not a byte-for-byte copy: it runs qemu-img convert into the managed QCOW2 at /var/lib/pixop-kvm/images/<domain>.qcow2. The --image source file is never modified or deleted. The converted image can use more disk than the downloaded QCOW2—plan capacity on / and /var/lib (see deployment guide).

Defaults: domain pixop-prime, 16384 MiB RAM and 4 vCPUs if you omit --memory / --vcpus, autostart disabled, VM not started. The installer prompts for domain-name confirmation; use --yes only after a successful dry run.

While the VM runs, passthrough GPUs are not available on the host.

Start, SSH, and license

cd /path/to/extracted-installer
sudo ./scripts/pixop-install start

GUEST_IP="203.0.113.10"   # guest LAN address from DHCP or reservation
ssh -i ~/.ssh/id_ed25519 "ec2-user@${GUEST_IP}"

License from the host (VM running):

cd /path/to/extracted-installer
sudo ./scripts/pixop-install license status \
  --identity ~/.ssh/id_ed25519 \
  --guest-host "${GUEST_IP}"

sudo ./scripts/pixop-install license set /path/to/license.jwt \
  --identity ~/.ssh/id_ed25519 \
  --guest-host "${GUEST_IP}"

If no license existed at install, add --restart-if-needed on first license set when prompted. Renewal overwrites in place and does not restart the VM when a license was already present.

Inside the guest, use the same tools as on AWS. See Connect your first SRT stream.

Enable autostart (after acceptance)

Only after live pipeline acceptance (commissioning sheet):

cd /path/to/extracted-installer
sudo ./scripts/pixop-install autostart enable

Autostart does not start a stopped VM. Optional: planned host reboot to confirm the domain returns with autostart enabled.

Local test only — userspace SLIRP

For bench testing on the KVM host without a LAN bridge. Do not combine --bridge with --ssh-host-port, --forward, or --expose-pixop. Forwards bind 127.0.0.1 only.

cd /path/to/extracted-installer
sudo ./scripts/pixop-install install \
  --image /path/to/pixop-prime-kvm.qcow2 \
  --gpu all \
  --ssh-key ~/.ssh/id_ed25519.pub \
  --license /path/to/license.jwt \
  --ssh-host-port 2222 \
  --expose-pixop

ssh -p 2222 -i ~/.ssh/id_ed25519 [email protected]

Status and removal

cd /path/to/extracted-installer
sudo ./scripts/pixop-install status
sudo ./scripts/pixop-install stop
sudo ./scripts/pixop-install uninstall
sudo ./scripts/pixop-install uninstall --purge   # irreversible — approve and back up first

Guest troubleshooting

Host VFIO, licensing, cold-start SRT: KVM troubleshooting guide. Guest services: Monitoring and troubleshooting.

Next steps

• Connect your first SRT stream
• FAQ
• Configuration