First boot — VelaOS Docs

What an end user sees the first time a Vela-flashed thin client powers on. Timing, screens, what happens in each phase.

This page describes exactly what the end user sees on first boot — useful for rolling VelaOS out to sites where the person unboxing the device isn't the person who provisioned it.

Target: under 20 seconds to login screen

On Wyse 5070 / HP t640 class hardware, power-on to the kiosk login screen takes under 20 seconds. Slower hardware lengthens the firmware phase, not the VelaOS phases. See Architecturefor the BOOT_OPTIMIZATION targets.

Phase 1 — Firmware (≤ 4 s)

UEFI POST, Secure Boot verifies the AlmaLinux shim + GRUB + kernel chain. A vendor logo usually shows; nothing Vela-specific yet. Duration is set by the thin-client firmware, not by us.

Phase 2 — Kernel + initramfs (≤ 7 s combined)

A quiet kernel message log scrolls past (we set quiet splash in the cmdline). The Plymouth splash takes over within a second or two. On LUKS- encrypted devices, Clevis unseals the key from the TPM here — no password prompt, because the key is sealed to the Secure Boot PCRs.

If the TPM unseal fails (e.g., firmware update changed PCR 0), the initramfs falls back to the recovery passphrase prompt. That's the one case where first boot pauses for user input — see Boot failure for the recovery workflow.

Phase 3 — systemd + services (≤ 6 s)

systemd brings up networking, auditd, firewalld, usbguard, fapolicyd, and the vela-agent. The agent writes a heartbeat sentinel to /run/vela/agent.heartbeatso greenboot can verify it's alive. Meanwhile greenboot-healthcheckruns through the 10 required health checks in parallel — any failure at this point triggers an automatic rollback to the previous bootc slot.

Phase 4 — GDM autologin + GNOME Kiosk (≤ 2 s)

GDM auto-logs the kiosk system user into a Wayland session. The user never sees a login prompt — that's deliberate, per the security model: the kiosk user has /usr/sbin/nologin, no sudo, no pseudo-terminal access. Authentication happens against the cloud when the assigned VelaApp (Citrix, Horizon, Chromium kiosk, etc.) launches.

Phase 5 — Vela Shell + enrolment or policy (≤ 1 s)

The Vela Shell paints its first frame. What happens next depends on device state:

Unenrolled device: the shell shows the enrolment screen with a rotating 7-character VelaOS Code + a QR of the same code. The code changes every 10 minutes until approved in the cloud console.
Enrolled, no policy: the shell shows a branded idle screen ("Waiting for policy assignment"). The device is connected and reachable; the tenant admin just hasn't picked a kiosk app for it.
Enrolled, policy assigned: the assigned VelaApp launches immediately — Chromium kiosk hits the managed URL, Citrix opens the XenApp storefront, etc. Total time-to-useful screen: under 20 s from power-on.

What the user never sees

A login prompt — kiosk user autologin is a hard requirement, not an option.
A password field for the OS itself — OS passwords are locked; policy-driven app auth happens inside the VelaApp.
The GNOME Activities overview — Vela Shell masks it on kiosk images (policy-toggleable on workstation variants).
A software-update nag — bootc pulls happen in the background on a 4-hour timer, and only re-gate the deployment at the next reboot.

Handing the device to an end user

Most deployments enrol + assign a policy at the depot before the device ships to site. When the end user powers it on, they skip straight to phase 5 — the assigned VelaApp launches in under 20 s. The only variable is the firmware phase, which the end user would see the same length on any OS.

If enrolment wasn't done at the depot, the end user sees the VelaOS Code screen and needs to relay that code to the person managing the console. QR code at the bottom of the screen makes that a phone-scan. Once approved, the assigned policy takes over within 5 s.