# First-Run Setup vs User Finalization in Omarchy: Key Differences Explained

> Understand the key differences between Omarchy's first run setup and user finalization. Learn how each process optimizes your initial experience and runtime environment.

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

---

**First-run setup handles one-time UI toasts and hardware tweaks immediately after the first graphical login, while user finalization prepares the persistent runtime environment after `/etc/skel` seeding completes.**

The Omarchy distribution from basecamp/omarchy implements a two-stage onboarding process that separates initial user experience configuration from persistent environment preparation. Understanding the distinction between **first-run setup** and **user finalization** is essential for troubleshooting installation issues and manually reprovisioning user environments.

## Execution Timing and Triggers

The primary distinction between these phases lies in *when* they execute during the boot-and-login sequence.

**First-run setup** launches automatically immediately after the *first interactive login*—the very first time a user reaches the graphical shell. This phase runs **once per installation** and is triggered by the login manager starting the `omarchy-provision-first-run` binary. Upon completion, the script sets a marker file at `~/.local/state/omarchy/done/first-run-user` to prevent re-execution.

**User finalization** runs **once per user** after the `/etc/skel` seed has been copied and first-run work is finished. Unlike first-run, this phase can be re-invoked manually using the `omarchy finalize user` command, which executes `bin/omarchy-provision-user`. It leaves a completion marker at `~/.local/state/omarchy/done/finalize-user`.

## Core Responsibilities and Tasks

Each phase manages distinct configuration domains that cannot be interchanged.

### First-Run Setup Tasks

First-run setup focuses on UI-related, one-time user experience tasks that require a running graphical session. According to the source code in `install/user/first-run/`, this phase includes:

- **Enabling user units** via [`install/user/first-run/enable-user-units.sh`](https://github.com/basecamp/omarchy/blob/main/install/user/first-run/enable-user-units.sh) to start necessary systemd user services
- **GNOME/GTK theme tweaks** handled by [`gnome-theme.sh`](https://github.com/basecamp/omarchy/blob/main/gnome-theme.sh) and [`gtk-primary-paste.sh`](https://github.com/basecamp/omarchy/blob/main/gtk-primary-paste.sh)
- **Audio hardware tuning** through [`audio-tuning.sh`](https://github.com/basecamp/omarchy/blob/main/audio-tuning.sh) for speaker-specific configuration
- **Welcome notifications** displayed by [`welcome.sh`](https://github.com/basecamp/omarchy/blob/main/welcome.sh), showing key-binding cheats as a toast notification
- **Connectivity alerts** managed by [`wifi.sh`](https://github.com/basecamp/omarchy/blob/main/wifi.sh) for Wi-Fi and update notifications

### User Finalization Tasks

User finalization handles runtime-environment preparation that `/etc/skel` cannot perform during initial seeding. The main logic resides in [`install/user/all.sh`](https://github.com/basecamp/omarchy/blob/main/install/user/all.sh) and includes:

- Creating **XDG user directories** and establishing mime defaults
- Generating **skill symlinks** and other runtime files requiring `$HOME` expansion
- Running pending **migrations** via `omarchy-migrate`
- Seeding per-user configuration requiring live system detection

## Idempotency and State Management

Both phases implement idempotent guards using marker files in `~/.local/state/omarchy/done/`.

The **first-run** marker (`first-run-user`) ensures the provisioner runs exactly once per installation. If the script fails, the marker is cleared automatically, allowing retry on the next login.

The **finalization** marker (`finalize-user`) makes the operation safe to re-run manually. When you execute `omarchy finalize user`, it applies only missing configuration pieces without duplicating existing setup.

## Manual Execution and Troubleshooting

You can interact with both provisioning phases manually for debugging or reconfiguration.

To force a re-run of the first-run setup after a failure:

```bash
rm -f "$HOME/.local/state/omarchy/done/first-run-user"

```

The next login will automatically execute the first-run scripts again.

To manually trigger user finalization or preview changes:

```bash

# Execute finalization

omarchy finalize user

# Preview changes without applying

omarchy finalize user --dry-run

```

For targeted debugging of specific first-run steps:

```bash
omarchy-provision-first-run --step welcome.sh

```

## Summary

- **First-run setup** (`bin/omarchy-provision-first-run`) executes once after the first graphical login, handling UI toasts, theme configuration, and hardware-specific audio tuning.
- **User finalization** (`bin/omarchy-provision-user` via `omarchy finalize user`) prepares the persistent runtime environment with XDG directories and migrations after `/etc/skel` seeding.
- First-run triggers automatically via login manager; finalization can be run manually and is safely idempotent.
- Both phases use marker files in `~/.local/state/omarchy/done/` to prevent duplicate execution.
- First-run scripts live in `install/user/first-run/` while finalization logic resides in [`install/user/all.sh`](https://github.com/basecamp/omarchy/blob/main/install/user/all.sh).

## Frequently Asked Questions

### Can I run first-run setup or user finalization multiple times?

User finalization is designed to be re-run safely using `omarchy finalize user` and will only apply missing configuration. First-run setup is intended to run only once automatically, but you can force re-execution by removing the `~/.local/state/omarchy/done/first-run-user` marker file before logging in again.

### What happens if first-run setup fails during initial login?

If `omarchy-provision-first-run` encounters an error, it automatically clears the `first-run-user` marker file. This allows the first-run scripts to execute again on your next login, ensuring critical initial configuration like user unit enabling and theme setup eventually completes successfully.

### Where does Omarchy store the completion markers for these phases?

Both phases write state files to `~/.local/state/omarchy/done/`. First-run creates `first-run-user` while finalization creates `finalize-user`. These markers prevent duplicate execution and can be manually deleted to force re-provisioning when necessary.

### Why can't `/etc/skel` handle all user finalization tasks?

The `/etc/skel` directory only supports static file copying during account creation. User finalization handles dynamic configuration requiring `$HOME` path expansion, live system detection, and migration scripts that must run after the graphical environment is fully initialized—tasks impossible to perform during initial skeleton seeding.