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

> Master Omarchy user provisioning with our three-phase setup Seed Finalize Resync. Learn how to separate static file copying from runtime configuration for efficient ISO installations.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: deep-dive
- Published: 2026-08-28

---

**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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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:

```bash

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