What Does omarchy-provision-first-run Handle? Omarchy First-Run Provisioning Explained

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):

omarchy-provision-first-run

Force re-provisioning:

omarchy-provision-first-run --force

Automated dotfiles input (useful in scripts):

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, which ensures reliable execution across different installation scenarios. Additional documentation appears in docs/file-layout.md (First-run section) and 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.

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