Downloads

OS images, Linux agent builds, and operator tools. Every version stays listed. Release notes included.

All downloads require a free VelaOS account

VelaOS Linux

● Live now

AlmaLinux 10.1 bootc for UEFI x86-64-v2 thin clients, mini-PCs, and POS terminals. Pull the signed OCI image or boot the ISO and enter your VelaOS code.

v26.04.1stable

2026-04-19 · x86-64-v2 + aarch64 · ~1.8 GB

ghcr.io/vela-hq/velaos-linux:26.04.1

AlmaLinux 10.1 bootc base, kernel 6.12 LTS (security-supported to May 2035)
GNOME Kiosk on Wayland; Greenboot + Podman
Signed VelaApp support (cosign-keyless, OCI 1.1 referrers, SBOM + VEX)
Vela agent (Go) pre-installed with MQTT command bus
5 signed VelaApps promoted — velaos-linux, chromium, vela-agent, citrix-workspace, horizon-client

Install on bare metal — 3 steps

Boot the target device from any AlmaLinux 10 / Fedora / RHEL live USB (any recent Linux live ISO works).

Open a terminal and run:

sudo podman run --privileged --pid=host \
  -v /dev:/dev -v /var/lib/containers:/var/lib/containers \
  ghcr.io/vela-hq/velaos-linux:26.04.1 \
  bootc install to-disk /dev/sda

Replace /dev/sda with your target disk. This wipes the disk.

Reboot. First boot shows the VelaOS enrollment screen.

Prefer a single-file USB installer? See Method C in the guide below — a cosign-signed .raw.zst image that you decompress and flash to USB. No live-Linux intermediate. The direct bootc install path works on any UEFI x86-64-v2 device with ≥ 4 GB RAM and ≥ 32 GB storage.

Install VelaOS — full guide

Pick the path that matches your starting point. All three land you at the same place: a fully-signed VelaOS device on first boot showing the 6-digit enrolment code.

What you need

Hardware: any UEFI x86-64-v2 device — thin client, mini-PC, NUC, Minisforum, Lenovo M75q, HP t640, etc. Minimum 4 GB RAM and 32 GB storage. UEFI must be enabled (Legacy/CSM off).
Network: Ethernet or Wi-Fi with internet access during install (to pull the bootc image).
Tooling: a USB stick (≥ 4 GB) and a flasher that works on your laptop — balenaEtcher, Rufus, Ventoy (drop-in ISO without rewriting the stick), or dd on Linux/macOS.
Account: a free VelaOS tenant at console.velaos.ch. First five devices are free, no card.

Fresh bare-metal install (recommended)

You have a thin client or PC you want to turn into a VelaOS device. Wipes the target disk completely and lays down VelaOS as the new OS.

Download any AlmaLinux 10, Fedora, or RHEL 10 live ISO from upstream. Any recent Linux live image works — we only need a working terminal and podman.
Write the ISO to a USB stick with balenaEtcher (click pick-image, pick-drive, flash) or with dd:
```
sudo dd if=AlmaLinux-10.1-live.iso of=/dev/sdX bs=4M status=progress oflag=sync
```
Boot the target device from USB (usually F12/F10/Esc at power-on to pick the boot drive). Pick Start live session, open a terminal.
Confirm the target disk name with lsblk. It's usually /dev/sda (SATA) or /dev/nvme0n1 (NVMe).
Install VelaOS:
```
sudo podman run --privileged --pid=host \
  -v /dev:/dev -v /var/lib/containers:/var/lib/containers \
  ghcr.io/twittermail/velaos-linux:stable \
  bootc install to-disk /dev/sda
```
This pulls the signed bootc image (~1.8 GB), verifies its cosign signature, wipes the target disk, writes the VelaOS rootfs, and installs a bootloader. Takes 4–8 minutes on a gigabit link.
Shut down, unplug the USB, power on. First boot lands on the VelaOS enrolment screen showing a 6-digit code. Enter that code in console.velaos.ch → Devices → Pending and click Approve. The device is live within 5 seconds.

Switch an existing AlmaLinux / RHEL / Fedora to VelaOS

The device is already running a bootc-compatible host (AlmaLinux 10 bootc, Fedora bootc, RHEL 10 image-mode, etc.). One command rebases to VelaOS in place. No USB, no reinstall — the next reboot switches OS.

Log in to the running device (ssh or console).
Rebase to the VelaOS bootc image:
```
sudo bootc switch ghcr.io/twittermail/velaos-linux:stable
```
This only works on a bootc host. On a traditional package-mode AlmaLinux install, use Method A instead.
Reboot. The device boots into VelaOS with enrolment waiting. Tenant data from the previous OS on /var and /home is preserved — only / is replaced.

Prebuilt raw installer (fastest)

A single velaos-installer-<sha>.raw.zst you decompress and flash to USB. Skips the live-Linux step entirely. Cosign-signed, SHA-256 checksummed.

Grab the newest .raw.zst + its .sig, .pem, and .sha256 sidecars from GitHub Releases.

Verify the signature before you trust the file (keyless OIDC, sigstore transparency log):

cosign verify-blob \
  --certificate velaos-installer-*.raw.zst.pem \
  --signature velaos-installer-*.raw.zst.sig \
  --certificate-identity-regexp 'https://github.com/twittermail/vela/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  velaos-installer-*.raw.zst

Decompress and flash in one pipe (saves ~3 GB of disk):
```
zstd -dc velaos-installer-*.raw.zst | \
  sudo dd of=/dev/sdX bs=4M status=progress oflag=sync
```
Replace /dev/sdX with your USB device (lsblk to list). On Windows, decompress with zstd.exe then flash the resulting .raw with Rufus in DD mode.
Boot the USB on the target device. First boot lays down the bootc image to the internal disk, reboots once, and shows the 6-digit enrolment code.

Pre-injecting an enrolment code (optional)

For zero-touch fleet rollouts, inject the tenant enrolment code so the device auto-enrols on first boot instead of waiting for a manual entry. The agent checks these sources in order:

VELA_ORG_CODE env var (dev / systemd override)
Kernel cmdline argument: vela.org_code=ACME-1234 — add via GRUB, PXE, or a one-shot USB with an edited /boot/loader/entries/*.conf
/etc/vela/enrollment-code.txt — baked into a per-tenant bootc image
/boot/vela-enrollment.txt — written by a USB installer helper

Verify what you're installing

Every VelaOS image is cosign-signed (keyless OIDC, sigstore transparency log), carries an SPDX SBOM, and an OpenVEX statement. Before running bootc install you can verify the chain end-to-end.

1. Verify the signature

cosign verify \
  --certificate-identity-regexp 'https://github.com/twittermail/vela/.github/workflows/velaos-linux.yml@' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  ghcr.io/twittermail/velaos-linux:stable

2. Inspect the SBOM

cosign verify-attestation --type spdxjson \
  --certificate-identity-regexp 'https://github.com/twittermail/vela/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  ghcr.io/twittermail/velaos-linux:stable | jq '.payload | @base64d | fromjson'

3. Inspect the OpenVEX

cosign verify-attestation --type openvex \
  --certificate-identity-regexp 'https://github.com/twittermail/vela/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  ghcr.io/twittermail/velaos-linux:stable | jq '.payload | @base64d | fromjson'

Troubleshooting

▸ Device boots from USB but falls back to internal disk

UEFI boot priority. Enter firmware setup (F2 / Del / Esc at power-on), put the USB device above the internal disk in the boot order, and disable Legacy/CSM. VelaOS requires UEFI — it won't install on BIOS-only firmware.

▸ bootc installfails with "cannot pull image"

Live USB has no network. Bring the interface up before running bootc install: sudo nmcli device wifi connect "SSID" password "PASSWORD" for Wi-Fi, or plug in Ethernet and run sudo dhclient. GHCR is a public container registry; no auth needed for the VelaOS image on a public channel.

▸ First boot after install shows a black screen, no enrolment code

GNOME Kiosk didn't start. Switch to a TTY (Ctrl+Alt+F2), log in as root (no password — locked), and run systemctl status gdm. Most common cause is a missing GPU driver on exotic hardware. Open a ticket at /support with the output of lspci -v | grep -A 3 VGA.

▸ Enrolment code shows but device never connects

VelaOS uses MQTT on TCP port 8883 (TLS). Outbound 8883 must be open. Check firewall / corporate proxy. On the device, switch to a TTY and run journalctl -u vela-agent -f to see connection attempts and the specific error.

Management tools

CLI, imaging tool, and provisioning config generator.

Provisioning config

Generate a bootstrap JSON + QR code for bulk device enrolment. Available in the console dashboard.

Open in console

REST API

96 endpoints. OpenAPI 3.1 spec. Automate your fleet from CI/CD or AI assistants.

View OpenAPI spec

Need help getting started?

The getting started guide walks through flash, boot, enrol, and first policy push.

Read the docs Talk to a human