Omarchy User Provisioning Process: First-Boot Wizard Technical Guide

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.

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:

# Manually start the provisioning service for debugging

sudo systemctl start omarchy-provision-owner.service

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

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

# Inspect current provisioning state and phase

cat /run/omarchy-provision-owner.state

# 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}