velaOS

Install VelaOS Linux

Flash a UEFI thin client, switch to the signed bootc image, and enrol. 12 minutes end-to-end.

You'll need

  • A UEFI x86-64-v2 thin client — ≥ 4 GB RAM, ≥ 32 GB storage (Wyse 5070, HP t640, Lenovo M75q, Intel NUC all qualify)
  • An 8 GB+ USB stick for the provisioning media
  • HDMI / DisplayPort monitor + USB keyboard
  • A VelaOS cloud account — sign up at console.velaos.ch/signup

Why two steps?

VelaOS Linux is an image-mode OS — the running system is an OCI container, not a package install. We use AlmaLinux's minimal installer to put a small base on disk, then bootc switch to our signed image. From that point on every update is a bootc pull — no package manager, no drift, A/B rollback if a health check fails.
  1. 1

    Download the AlmaLinux 10.1 minimal ISO

    Grab AlmaLinux-10.1-x86_64-minimal.iso from the AlmaLinux mirrors. It's ~1.5 GB.

    Verify the checksum — AlmaLinux publishes CHECKSUM files GPG-signed by the release key:

    sha256sum -c CHECKSUM --ignore-missing 2>&1 | grep AlmaLinux-10.1
  2. 2

    Write the ISO to USB

    On Linux or macOS:

    # Find the USB device (will show as /dev/sdX or /dev/diskN)
lsblk

# Write (DESTRUCTIVE — double-check the target!)
sudo dd if=AlmaLinux-10.1-x86_64-minimal.iso of=/dev/sdX bs=4M status=progress oflag=sync

    On Windows, use Rufus in DD mode.

  3. 3

    Boot the thin client from USB

    Plug the USB in, power on, and tap the boot-menu key (F12 on Dell / HP, F11 on Lenovo). Pick the USB device. Choose Install AlmaLinux 10.

    At the installer: keep the defaults except for these three:

    • Software: pick Minimal Install (nothing more)
    • Disk: use the whole local disk; ext4 on /, no separate /home
    • Root password: set one temporarily — we lock it in the next step

    Install takes about 4 minutes. Reboot when it finishes; remove the USB.

  4. 4

    Switch to the VelaOS bootc image

    Log in as root with the password you just set. Run:

    # Trust our cosign key so the signature check succeeds
curl -fsSL https://velaos.ch/cosign.pub -o /etc/pki/cosign/velaos.pub

# Switch — downloads the image, writes an A/B slot, and reboots into it.
bootc switch ghcr.io/vela-hq/velaos-linux:stable

    This takes 3–6 minutes depending on your link. When it finishes, the device reboots into VelaOS.

    The bootc switch command verifies the image signature before activating it. If the signature fails, it refuses the switch — you stay on AlmaLinux minimal. That's the rollback guardrail.
  5. 5

    Read the VelaOS Code on first boot

    After reboot you'll see the enrolment screen:

    VelaOS Linux — Enrollment
─────────────────────────
Your VelaOS Code:  K7M-3QR
Tenant:            not yet enrolled
Status:            waiting

Point your console to: https://console.velaos.ch/dashboard/devices

    Keep this screen up. The code rotates every 10 minutes until enrolment.

  6. 6

    Approve in the console

    In Devices → Pending, click Enter VelaOS Code and type the code from the screen.

    The device shows up as pending. Click Approve. Within about 5 s the device's screen switches to:

    VelaOS — Connected
Tenant:  Acme Corp
Kiosk:   (no policy assigned — showing default shell)

    Assign a policy to give it work to do — see Quickstart step 4.

What happened under the hood

  • AlmaLinux installer wrote a minimal root filesystem + GRUB to the local disk.
  • bootc switch pulled ghcr.io/vela-hq/velaos-linux:stable, verified its cosign signature, and wrote it into slot B. GRUB now points to B; slot A keeps the old AlmaLinux if we need to roll back.
  • The first boot ran every Greenboot check in /etc/greenboot/check/required.d/. Passing = bootc commits the deployment. Failing = automatic rollback to A.
  • vela-agent generated an enrolment code and waited for approval. It never phoned home with credentials until you clicked Approve.

Next steps

Was this helpful?
Updated 2026-04-18Edit on GitHub