Omarchy User Provisioning and Finalization Process: Three-Phase Setup Explained

Omarchy provisions users through a structured three-phase pipeline—Seed, Finalize, and Resync—that separates static file copying from runtime configuration, with deferred provisioning support for ISO installations.

The Omarchy user provisioning and finalization process transforms a fresh system image into a fully configured desktop environment according to the basecamp/omarchy source code. This architecture divides user setup into discrete stages to ensure idempotent, maintainable configuration that handles everything from initial home directory creation to first-run graphical adjustments.

The Three-Phase Provisioning Model

Omarchy’s user-setup architecture separates concerns into three distinct phases, each handled by specific components in the repository.

Phase 1: Seed (Static Defaults)

The Seed phase copies static defaults from the omarchy-settings package into newly created user directories. This is the only step that touches a brand-new home directory, copying the /etc/skel tree into $HOME. These files live in etc/skel/ and are shipped by the omarchy-settings package, providing the baseline configuration files present before any user-specific logic executes.

Phase 2: Finalize (Runtime Configuration)

The Finalize phase runs once for each user immediately after the Seed step. It performs actions requiring $HOME, live $OMARCHY_PATH, or runtime detection—such as creating skill symlinks, updating XDG defaults, installing per-user systemd services, refreshing generated desktop entries, and applying migrations.

The command driving this step is omarchy-provision-user, which is routed via the CLI as omarchy provision user. According to docs/file-layout.md lines 95-118, this phase handles all configuration that cannot be completed during the initial seed because it requires knowledge of the live environment or user-specific paths.

Phase 3: Resync (Configuration Reset)

The Resync phase allows an existing user to overwrite their configuration with shipped defaults. Executed via omarchy-reinstall-configs, this command—implemented in bin/omarchy-reinstall-configs—provides a mechanism to restore factory settings without recreating the user account.

Deferred Provisioning and First-Boot Setup

Omarchy supports deferred provisioning for ISO installations, delaying user creation until the first boot rather than during the image build process.

The Deferred Provisioning Marker

When building an ISO with omarchy-apply-system --defer-provisioning, no user is created during installation. Instead, the system drops a marker file at /var/lib/omarchy/provisioning/pending. This marker triggers the systemd unit omarchy-provision-owner.service, installed from install/provisioning/omarchy-provision-owner.service.

First-Boot User Creation

On the first boot, bin/omarchy-provision-owner reads the pending marker and creates the primary user on tty1. It immediately calls omarchy-provision-user with the environment variable OMARCHY_SETUP_CONTEXT=provision-owner, ensuring the Finalize phase runs as part of the first-boot user creation workflow (see docs/file-layout.md lines 50-56).

First-Run Finalization

After the user logs in for the first time, omarchy-provision-first-run executes to handle graphical-session-specific configuration.

Graphical Session Setup

The first-run script first invokes omarchy-provision-user || true to guarantee that finalization has occurred, then proceeds with UI-dependent tasks. These include enabling user systemd units, applying GNOME/GTK settings, audio tuning, and displaying a welcome toast. According to docs/file-layout.md lines 61-89, this entire flow is idempotent and guarded by a marker file at ~/.local/state/omarchy/done/first-run-user, ensuring it executes only once per user.

Manual Provisioning Commands

Administrators can trigger provisioning steps manually using the following commands:

# Run the finalize step manually (e.g., after adding a new user)

omarchy provision user   # equivalent to omarchy-provision-user

# Create the first user on a deferred-provisioned system (run as root)

omarchy-provision-owner   # normally triggered by systemd on first boot

# Trigger first-run actions manually (useful for debugging)

omarchy-provision-first-run

# Reset user configs to defaults (Resync phase)

omarchy-reinstall-configs

Key Implementation Files

• bin/omarchy-provision-user: Implements the Finalize phase; invoked as omarchy provision user.
• bin/omarchy-provision-owner: Systemd-triggered wrapper that creates the first user on deferred-provisioned installs.
• bin/omarchy-provision-first-run: Handles the First-run UI-dependent steps.
• install/provisioning/omarchy-provision-owner.service: Systemd unit that launches the owner provisioning script on first boot.

Summary

• Seed phase: Copies static defaults from /etc/skel via the omarchy-settings package into new user directories.
• Finalize phase: Runs once per user via omarchy-provision-user to handle runtime configuration like symlinks, systemd services, and migrations.
• Resync phase: Allows resetting configurations using omarchy-reinstall-configs without deleting the user account.
• Deferred provisioning: Supports ISO installations that delay user creation until first boot using /var/lib/omarchy/provisioning/pending and omarchy-provision-owner.service.
• First-run protection: Graphical setup runs once per user via omarchy-provision-first-run, safeguarded by state markers in ~/.local/state/omarchy/done/.

Frequently Asked Questions

What triggers the Omarchy user provisioning process on a fresh install?

On standard installs, the process triggers when a user is created, executing the Seed phase via /etc/skel followed immediately by the Finalize phase via omarchy-provision-user. On deferred-provisioned ISOs, the systemd unit omarchy-provision-owner.service triggers on first boot, creating the user and running finalization automatically.

What is the difference between omarchy-provision-user and omarchy-provision-first-run?

omarchy-provision-user handles system configuration that requires a home directory but does not require a graphical session, running once per user creation. omarchy-provision-first-run executes after the first graphical login, handling UI-dependent settings like GTK themes, audio profiles, and welcome notifications, and is protected by a marker file to ensure it runs only once.

How does deferred provisioning work in Omarchy?

Deferred provisioning builds the ISO without creating a user account, leaving a marker file at /var/lib/omarchy/provisioning/pending. On first boot, omarchy-provision-owner detects this marker, creates the user on tty1, and runs the Finalize phase with OMARCHY_SETUP_CONTEXT=provision-owner before clearing the marker.

Is the Omarchy provisioning process idempotent?

Yes, individual components are designed to be safely rerun. The Finalize phase can be manually invoked via omarchy provision user, and the First-run phase checks for the existence of ~/.local/state/omarchy/done/first-run-user before executing graphical setup tasks, preventing duplicate configuration changes.

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