# What Does omarchy-provision-first-run Handle? Omarchy First-Run Provisioning Explained > Learn what omarchy-provision-first-run handles: initializing Omarchy, enabling services, deploying configs, running migrations, and more. Ensure a smooth setup. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: internals - Published: 2026-08-29 --- **The `omarchy-provision-first-run` script is the entry-point that initializes a fresh Omarchy installation by detecting first-run state, enabling system services, prompting for dotfiles, deploying default configs, running migrations, and creating completion markers to prevent duplicate execution.** When you install Omarchy from the **basecamp/omarchy** repository, the `omarchy-provision-first-run` script orchestrates the entire initial setup process. This executable, located at `bin/omarchy-provision-first-run` in the source tree, ensures that brand-new environments are ready for immediate use while preserving user customizations and applying necessary data migrations. ## First-Run Detection and Idempotency The script begins by checking for the existence of `$HOME/.config/omarchy/first-run-done`. If this **marker file** is absent, the script assumes this is the initial launch and proceeds with provisioning. This check guarantees that the provisioning logic runs only once, avoiding repeated prompts and configuration overwrites on subsequent logins. If the marker exists, the script exits silently unless invoked with the `--force` flag, which bypasses the check and re-runs all steps for debugging or re-provisioning scenarios. ## Core Provisioning Responsibilities Once triggered, `omarchy-provision-first-run` executes a specific sequence of initialization tasks defined in the basecamp/omarchy source code. ### Enabling Migration Notifications The script starts and enables the **systemd user service** `omarchy-migrate-notify.service`. According to the implementation in `bin/omarchy-provision-first-run`, this step ensures users receive notifications about pending Omarchy migrations immediately after the initial setup completes, keeping the environment up-to-date. ### Dotfiles Repository Integration The script prompts the user with "Got a dots repo?" If confirmed, it clones the supplied Git URL into `~/.config/omarchy/dots`. This integration allows users to immediately apply their personal configuration (dotfiles) on a fresh machine, bridging the gap between default installation and personalized workflow. ### Default Configuration Deployment For core components such as **Hyprland** and **Quickshell**, the script invokes the `omarchy-refresh-config` helper. This utility copies default configurations while safely backing up any existing user configs, ensuring that first-time users receive sensible defaults without destroying prior customizations. ### First-Run Migration Execution The script executes any pending migration scripts under the `migrations/` directory that are specifically marked as "first-run". These migrations update the internal data model to the current Omarchy version before the user begins interacting with the system, preventing version compatibility issues. ## Command Usage and Options The `omarchy-provision-first-run` binary supports both automatic invocation and manual control. Normal execution (automatically invoked on login): ```bash omarchy-provision-first-run ``` Force re-provisioning: ```bash omarchy-provision-first-run --force ``` Automated dotfiles input (useful in scripts): ```bash omarchy-provision-first-run <<< $'yes\nhttps://github.com/your/dots-repo.git' ``` ## Implementation and Testing The complete logic resides in `bin/omarchy-provision-first-run` within the basecamp/omarchy repository. The behavior is validated by the automated test suite in [`test/shell.d/first-run-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/first-run-test.sh), which ensures reliable execution across different installation scenarios. Additional documentation appears in [`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md) (First-run section) and [`docs/update-process.md`](https://github.com/basecamp/omarchy/blob/main/docs/update-process.md) (Migration-notify integration). ## Summary - The `omarchy-provision-first-run` script serves as the single entry-point for Omarchy initialization, located at `bin/omarchy-provision-first-run`. - It checks for `$HOME/.config/omarchy/first-run-done` to ensure idempotent execution, unless `--force` is specified. - The script enables the `omarchy-migrate-notify.service` systemd user service for update notifications. - Users can immediately import dotfiles by cloning repositories into `~/.config/omarchy/dots` during the interactive prompt. - Default configurations are deployed via `omarchy-refresh-config` with automatic backup of existing files. - First-run specific migrations in the `migrations/` directory execute to align the data model with the current version. ## Frequently Asked Questions ### What triggers omarchy-provision-first-run to execute? Omarchy automatically invokes `omarchy-provision-first-run` during the first user login after installation. The script checks for the marker file at `$HOME/.config/omarchy/first-run-done` to determine if provisioning is necessary, ensuring it only runs once unless manually triggered with the `--force` flag. ### How does omarchy-provision-first-run handle existing user configurations? When deploying defaults, the script calls `omarchy-refresh-config` to safely back up existing user configurations before copying new default files for components like Hyprland and Quickshell. This prevents data loss while ensuring first-time users receive functional default settings. ### Can I re-run the first-run provisioning on an existing installation? Yes. Invoke the script with the `--force` flag to bypass the marker file check and re-execute all provisioning steps. This is useful for debugging migration scripts or re-applying initial configuration logic after system changes. ### Where are the migration scripts located that run during first-run? First-run migration scripts reside in the `migrations/` directory of the Omarchy installation. The `omarchy-provision-first-run` script specifically executes those marked for first-run execution to update the internal data model to the current version before user interaction begins.