velaOS

Quickstart

Flash a thin client, enroll it into your cloud tenant, and push your first policy. Target: 10 minutes.

You'll need

  • A UEFI x86-64-v2 device with ≥4 GB RAM and ≥32 GB storage (any thin client, mini-PC, NUC, Minisforum, or compatible desktop)
  • A USB stick (8 GB+) for the install media, or direct-to-disk flashing
  • A computer to write the ISO (balenaEtcher or dd)
  • A VelaOS cloud account — sign up at console.velaos.ch
  1. 1

    Download and write the VelaOS ISO

    From the console, go to Downloads → VelaOS Linux and grab the latest velaos-linux-v2.x.iso.

    Write it to the USB stick with balenaEtcher (or dd if=velaos-linux-v2.x.iso of=/dev/sdX bs=4M status=progress). Takes about 3 minutes on a USB 3 stick.

    VelaOS ISO is an AlmaLinux 10.1 bootc installer. No OS setup wizard — boots straight into the VelaOS enrollment screen after install finishes.
  2. 2

    Boot the device and read the VelaOS Code

    Plug in the USB stick, boot from USB (F12 / F10 / Esc on most firmware), and follow the minimal installer. First boot shows:

    VelaOS Enrollment
─────────────────────
Your VelaOS Code:  A7K-9MX
Scan the QR above or enter this code in the console.
Waiting for approval...

    Keep this screen up. The code expires in 10 minutes.

  3. 3

    Approve the device in the console

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

    The device will show up with status pending. Click Approve. Within 5 seconds the device screen updates to:

    VelaOS — Approved
Tenant: Acme Corp
Status: Connected
  4. 4

    Create a policy

    Go to Policies → New Policy. Pick the Kiosk template, name it "Browser Kiosk", and click Create.

    Open the editor, go to the Kiosk tab, and set:

    • Web kiosk URL — your app's URL (e.g. https://app.example.com)
    • Allow status bar — off
    • Allow settings — off

    Save.

  5. 5

    Apply the policy to the device

    Go to Devices, click your thin client, scroll to the Policy tab, click Change Policy, pick "Browser Kiosk", confirm.

    Within 3 seconds the device reloads into kiosk mode, fullscreen on your URL.

  6. 6

    Verify it works

    Back in the console, the device detail page should show:

    • Status: online (green)
    • Policy: Browser Kiosk (applied v1)
    • Compliance: compliant
    • Last seen: a few seconds ago

    Open Live View to see a real-time screenshot streaming from the device.

You're done!

You've enrolled a device, created a policy, and pushed it to production in under 10 minutes. A fleet of 100 devices is the same 5 steps — you just approve 100 codes instead of 1.

Common issues

  • Installer fails to boot — enable UEFI and disable Legacy/CSM in firmware. VelaOS is UEFI-only.
  • Code shows but never enrolls — check the device has internet (ethernet is most reliable). See Device stuck enrolling.
  • Policy doesn't apply — policies are fetched over MQTT on port 8883. Make sure outbound 8883 is not blocked.

Next steps

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