# Omarchy User Provisioning Process: First-Boot Wizard Technical Guide

> Learn the Omarchy user provisioning process with our technical guide. Discover how the first-boot wizard automates user setup, system settings, and encryption.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: technical-guide
- Published: 2026-08-30

---

**The Omarchy user provisioning process is a three-phase, console-based wizard driven by the `omarchy-provision-owner` systemd service that automatically configures user accounts, system settings, and encryption keys immediately after a deferred-provisioning installation or factory reset.**

The Omarchy user provisioning process begins automatically when the marker file `/var/lib/omarchy/provisioning/pending` exists on the system. According to the omacom/omarchy source code, this deterministic workflow orchestrates interactive form collection, background system configuration, and per-user finalization through the coordinated execution of `bin/omarchy-provision-owner` and `bin/omarchy-provision-user`.

## The Three Phases of the Omarchy User Provisioning Process

The provisioning workflow divides logically into three distinct phases, each handled by specific functions within the main provisioning script.

### Phase 1: Interactive Configuration and Form Collection

The wizard initializes the console environment and presents a branded interface for data collection. The **`greeter_screen`** function (lines [68‑140] in `bin/omarchy-provision-owner`) draws the Omarchy logo and a responsive progress bar that scales with console resize events.

This phase sequentially executes three form functions:

- **`keyboard_form`** (lines [83‑101]) – Presents a `gum`-based picker via `omarchy_prompt_keyboard`, instantly applies the layout with `loadkeys`, and persists the selection using `systemd-firstboot` or `localectl`.
- **`user_form`** (lines [130‑155]) – Collects the username, password, full name, email address, hostname, and timezone through a series of `omarchy_prompt_*` helper functions.
- **`confirm_form`** (lines [156‑170]) – Displays a summary table for user review and confirmation before proceeding to system modification.

### Phase 2: Background Provisioning Execution

After confirmation, **`run_provisioning`** (lines [95‑136]) spawns an asynchronous background worker that executes idempotent configuration steps while the main thread updates the progress bar visualization.

Key provisioning tasks include:

- **`create_user`** (lines [221‑266]) – Writes the username to the provisioning state, creates or updates the user account via `useradd`/`usermod`, sets the encrypted password, assigns supplementary groups recorded in `user_groups`, and installs a sudo-wheel drop-in configuration.
- **`install_authorized_keys`** (lines [278‑293]) – Copies staged SSH public keys from the provisioning directory into the new user’s `~/.ssh/authorized_keys` file with correct permissions.
- **`configure_login`** (lines [295‑326]) – Configures SDDM for automatic first-boot login and installs a one-shot systemd service to remove autologin privileges on the next boot for unencrypted installations.
- **`configure_hostname`** and **`configure_timezone`** (lines [329‑354]) – Overwrites the placeholder values seeded during deferred installation with the user-specified system identity and regional settings.

### Phase 3: Per-User Finalization and System Hardening

The final phase transitions from system-wide configuration to user-specific runtime setup and security hardening.

The **`finalize_user`** function (lines [308‑349]) writes `"finalize"` to the state file and invokes **`omarchy-provision-user --force --first-install`**. This companion script, located at `bin/omarchy-provision-user`, performs per-user tweaks that cannot reside in `/etc/skel`, including skill symlink creation, XDG user directory setup, default application configuration, and migration marker initialization.

For encrypted installations, **`rekey_luks`** (lines [511‑566]) adds the user’s password as a new LUKS key, removes the temporary staging key, and rebuilds the Unified Kernel Image. If this step fails, the process aborts with a surface-level warning to prevent lockout.

For factory reset scenarios, **`reset_limine_config`** (lines [595‑639]) identifies stale Limine boot entries by checking for a stale machine-id and replaces them with fresh templates before running `limine-update`.

Finally, **`cleanup_oem_state`** (lines [667‑682]) removes all provisioning state files and disables the `omarchy-provision-owner.service` unit, leaving a clean production system.

## Step-by-Step Technical Execution Flow

### Service Initialization and Console Setup

The `omarchy-provision-owner.service` unit triggers on `tty1` only when `/var/lib/omarchy/provisioning/pending` exists, as documented in the script header (lines [7‑12]). Upon launch, **`scale_console_font`** calculates optimal font sizing to accommodate the ASCII logo, then **`greeter_screen`** establishes the visual environment with 256-color support.

### Account Creation and Authorization

During **`create_user`**, the script first validates username availability, then executes `useradd` with the `--create-home` flag or `usermod` for existing accounts. The password is encrypted and applied via `chpasswd`, while group memberships are enumerated from the `user_groups` associative array defined in [`install/provisioning/setup-form.sh`](https://github.com/omacom/omarchy/blob/main/install/provisioning/setup-form.sh).

### Encryption and Bootloader Management

On encrypted installs, the **`rekey_luks`** function performs cryptographic key rotation by adding the user-supplied passphrase to LUKS slot 1, removing the temporary install key from slot 0, and regenerating the Unified Kernel Image using `dracut` or `mkinitcpio` depending on the build configuration.

Concurrently, **`limine_entries_stale`** checks `/etc/machine-id` against bootloader entries; if a factory reset is detected, stale entries are purged and regenerated from templates in `/usr/share/omarchy/limine/`.

## Error Handling and Recovery Mechanisms

The main execution loop (lines [123‑143]) implements robust error trapping. If any provisioning step exits non-zero, the progress bar halts, the console displays the specific error context, and the user receives a choice to **retry the wizard** or **drop to a root shell** for manual intervention.

If per-user finalization fails during initial boot, administrators can re-execute the runtime configuration independently after login.

## Debugging and Manual Execution Commands

You can manually trigger or inspect the Omarchy user provisioning process using the following commands:

```bash

# Manually start the provisioning service for debugging

sudo systemctl start omarchy-provision-owner.service

```

```bash

# Re-run per-user finalization after login (force refresh)

omarchy-provision-user --force --first-install

```

```bash

# Inspect current provisioning state and phase

cat /run/omarchy-provision-owner.state

```

```bash

# View detailed provisioning logs

less /var/log/omarchy-provision-owner.log

```

## Summary

- The **Omarchy user provisioning process** triggers automatically via `omarchy-provision-owner.service` when `/var/lib/omarchy/provisioning/pending` exists.
- **Three distinct phases** handle interactive form collection (`keyboard_form`, `user_form`), background system configuration (`create_user`, `configure_login`), and per-user finalization (`omarchy-provision-user`).
- **Encryption-aware workflows** include LUKS re-keying (`rekey_luks`) and Limine bootloader refresh (`reset_limine_config`) for factory resets.
- **Idempotent design** allows safe retry via the error handling loop or manual re-execution of `omarchy-provision-user --force --first-install`.
- **Source files** include `bin/omarchy-provision-owner` for system-wide setup and `bin/omarchy-provision-user` for runtime user environment configuration.

## Frequently Asked Questions

### What triggers the Omarchy user provisioning process to start?

The provisioning process activates when the systemd service `omarchy-provision-owner.service` detects the file `/var/lib/omarchy/provisioning/pending` on the system. This file is created during deferred-provisioning installations or factory resets, causing the service to launch automatically on `tty1` and present the configuration wizard.

### How does Omarchy handle disk encryption during the provisioning process?

For encrypted installations, the process calls `rekey_luks` (lines [511‑566]) to replace the temporary installation key with the user’s chosen password. The function adds the new passphrase to a secondary LUKS slot, removes the throw-away staging key, and rebuilds the Unified Kernel Image to ensure the system remains bootable and secure.

### Can I rerun the Omarchy user provisioning process after the initial setup?

Yes. While the main provisioning wizard disables itself after successful completion, you can re-execute the per-user finalization step by running `omarchy-provision-user --force --first-install` as the target user. This command, implemented in `bin/omarchy-provision-user`, recreates skill symlinks, refreshes XDG directories, and applies any new default application configurations without affecting system-wide settings.

### Where does Omarchy store logs and state information during provisioning?

The provisioning script writes runtime state to `/run/omarchy-provision-owner.state` and detailed execution logs to `/var/log/omarchy-provision-owner.log`. Additionally, intermediate configuration data is staged in `/var/lib/omarchy/provisioning/` before being committed to the system or the user’s home directory.