# Omarchy User Finalization: The 9-Step Provisioning Process Explained

> Master Omarchy user finalization with our 9-step provisioning guide. Learn how to transform a basic home directory into a fully functional desktop with AI skills and custom configurations.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-27

---

**Omarchy user finalization is a nine-step configuration sequence performed by the `omarchy-provision-user` command that converts a fresh home directory—populated from the static `/etc/skel` template—into a fully functional desktop environment with AI skills, application defaults, and hardware-specific tuning.**

The `basecamp/omarchy` repository separates new user provisioning into three distinct phases: **seed**, **finalize**, and **resync**. While the seed phase merely copies static files from `/etc/skel` to `$HOME`, the finalize phase executes dynamic, per-user configuration that cannot be handled by the read-only skeleton tree. This article breaks down the technical implementation of Omarchy user finalization as documented in [`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md) and implemented across the core command binaries.

## The Three-Phase Provisioning Model

Omarchy treats user creation as a pipeline with clearly separated responsibilities:

1. **Seed** – Copies static defaults from `/etc/skel` into the user's home directory.
2. **Finalize** – Executes `omarchy-provision-user` (also exposed as `omarchy finalize user`) to perform dynamic configuration requiring runtime environment awareness.
3. **Resync** – Handles ongoing synchronization of dotfiles and environment updates.

The finalization phase runs once per user immediately after the seed completes, triggered either during ISO installation via `omarchy-provision-user --force --first-install` or deferred to first boot via `omarchy-provision-owner`.

## The Nine Steps of Omarchy User Finalization

According to the runtime sequence defined in [`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md) (lines 95–119), the `omarchy-provision-user` command performs the following operations in order:

### 1. AI Skill Symlink Creation

The finalizer iterates over every skill directory under `default/agents/skills/`—such as `omarchy` and `diagnose-crash`—and creates symbolic links in the user's agent directories. These links point to:

- `~/.agents/skills/<name>`
- `~/.claude/skills/<name>`
- `~/.codex/skills/<name>`
- `~/.pi/agent/skills/<name>`

This architecture allows users to execute the latest skill scripts directly from the repository without copying files into their home directories, ensuring updates propagate immediately.

### 2. XDG User Directory Initialization

The command executes `xdg-user-dirs-update` to refresh the XDG user-directories specification. This ensures that standard folders like `Desktop`, `Documents`, and `Downloads` are correctly populated under `$HOME` after the initial skeleton copy.

### 3. GTK Bookmarks Configuration

The finalizer regenerates `~/.config/gtk-3.0/bookmarks` to reflect the current `$HOME` layout. This updates the "Places" sidebar in GTK-based file managers such as Nautilus or Thunar to display the user's actual directory structure rather than stale template paths.

### 4. Hyprland Keyboard Layout Defaults

Instead of rewriting per-user Hyprland configuration files, the finalizer ensures the Wayland compositor reads its keymap settings (`XKBLAYOUT` and `XKBVARIANT`) from the central [`/etc/vconsole.conf`](https://github.com/basecamp/omarchy/blob/main//etc/vconsole.conf) file. This maintains consistency between the system console and the graphical environment without duplicating keyboard layout definitions in `$HOME`.

### 5. Default Application Assignment

The script calls `xdg-settings set default-web-browser` and `xdg-mime default` to establish the system's default web browser and mail handler within the user's MIME association database. This ensures that `xdg-open` and similar tools launch the correct applications for HTTP and mailto links.

### 6. Application Launcher Refresh

Running `omarchy-refresh-applications` regenerates `.desktop` entry files for installed applications. This guarantees that the application menu reflects the current system state, including any newly installed packages or removed software, without requiring a full session restart.

### 7. Per-User Install Script Execution

The finalizer sources [`install/user/all.sh`](https://github.com/basecamp/omarchy/blob/main/install/user/all.sh), which encapsulates the bulk of user-specific configuration:

- Installing and activating themes
- Configuring Chromium browser defaults
- Setting up Git configuration and credentials
- Installing `mise` (the universal version manager)
- Provisioning the GPG keyring
- Applying hardware-specific quirks such as ASUS microphone fixes

This script runs in the context of the target user, ensuring all changes are owned by the correct UID.

### 8. First-Install Migration Marking

When invoked with the `--first-install` flag, the finalizer records every shipped user migration as already applied. This prevents migration scripts from executing again for newly created users, avoiding redundant operations and potential configuration drift on fresh installations.

### 9. Idempotency Marker Creation

Upon successful completion, `omarchy-done` writes a completion marker to `~/.local/state/omarchy/done/finalize-user`. Subsequent executions of `omarchy-provision-user` detect this file and exit immediately as no-ops, making the process safe to run repeatedly without side effects.

## Manual Execution and Debugging

While the ISO installer automatically triggers finalization via `omarchy-provision-user --force --first-install`, administrators can manually invoke the process for troubleshooting or user repair:

```bash

# Standard finalization (exits immediately if marker exists)

omarchy provision-user

# Force re-execution, ignoring the idempotency marker

omarchy provision-user --force

# First-install mode: marks all migrations as applied before running

omarchy provision-user --first-install

```

The `--force` flag is particularly useful when testing changes to [`install/user/all.sh`](https://github.com/basecamp/omarchy/blob/main/install/user/all.sh) or when recovering from a failed initial setup.

## Key Implementation Files

Understanding the Omarchy user finalization architecture requires familiarity with these critical paths in the `basecamp/omarchy` repository:

- **`bin/omarchy-provision-user`** – The primary entry point that implements the nine-step sequence and handles CLI flags like `--force` and `--first-install`.
- **[`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md)** – Documents the runtime finalization sequence and the distinction between seed, finalize, and resync phases (lines 95–119).
- **[`install/user/all.sh`](https://github.com/basecamp/omarchy/blob/main/install/user/all.sh)** – The comprehensive per-user installation script responsible for themes, browsers, Git, `mise`, GPG, and hardware quirks.
- **[`default/agents/skills/omarchy/SKILL.md`](https://github.com/basecamp/omarchy/blob/main/default/agents/skills/omarchy/SKILL.md)** – Defines the skill directory structure that gets symlinked into user agent directories during step one.
- **`~/.local/state/omarchy/done/finalize-user`** – The runtime idempotency marker that prevents duplicate executions.

## Summary

- Omarchy user finalization consists of **nine sequential steps** executed by `omarchy-provision-user` after the static `/etc/skel` seed.
- The process creates **symlinks for AI skills**, initializes **XDG directories**, updates **GTK bookmarks**, and configures **Hyprland keyboard layouts** from system defaults.
- **Application defaults** and **launcher menus** are refreshed through `xdg-settings` and `omarchy-refresh-applications`.
- The heavy lifting occurs in **[`install/user/all.sh`](https://github.com/basecamp/omarchy/blob/main/install/user/all.sh)**, which handles themes, browsers, Git, `mise`, GPG, and hardware fixes.
- **Idempotency** is guaranteed by a marker file in `~/.local/state/omarchy/done/`, with `--force` available to override when necessary.

## Frequently Asked Questions

### What distinguishes the seed phase from the finalize phase in Omarchy?

The **seed** phase copies static, read-only files from `/etc/skel` into `$HOME`, while the **finalize** phase executes dynamic configuration through `omarchy-provision-user` that requires runtime environment awareness, such as creating symlinks to repository skills or setting up per-user GPG keys.

### How can I re-run the user finalization process if something went wrong during installation?

Execute `omarchy provision-user --force` to bypass the idempotency check at `~/.local/state/omarchy/done/finalize-user` and re-execute all nine configuration steps. Use `--first-install` if you also need to mark migrations as applied for a fresh user environment.

### Where does Omarchy store the completion marker to prevent duplicate finalization runs?

After successful execution, the system writes an empty file to **`~/.local/state/omarchy/done/finalize-user`**. The `omarchy-provision-user` command checks for this file before running and exits immediately if found, unless the `--force` flag is provided.

### What happens during the skill symlink creation step?

The finalizer scans `default/agents/skills/` and creates symbolic links in the user's home directory under `~/.agents/skills/`, `~/.claude/skills/`, and similar agent-specific paths. This allows AI assistants to access the latest skill scripts directly from the repository without requiring file copies that would become stale.