How Omarchy's Provisioning System Populates the User's Home Directory: A Complete Technical Guide

Omarchy's provisioning system populates a user's home directory through a three-stage pipeline—bootstrap, owner-level setup, and user-level setup—that copies default configurations from $OMARCHY_PATH/config/ to ~/.config/, installs user assets, and configures permissions via idempotent shell scripts.

Omarchy is an open-source Linux distribution built for reproducible development environments. Its provisioning system is designed to run without requiring an active desktop session, making it ideal for ISO installations and chroot environments. The system splits privileges carefully, ensuring secure initialization while giving users personalized dotfiles and themes.

---

The Three-Stage Provisioning Pipeline

Stage 1: Bootstrap the Provisioning State

The process begins when omarchy-provision-first-run executes. This script in bin/omarchy-provision-first-run initializes the provisioning environment:

• Creates the temporary provisioning directory at $OMARCHY_PROVISIONING_DIR
• Records a "first-run" marker to prevent duplicate execution
• Orchestrates the subsequent privileged and unprivileged stages

This bootstrap runs automatically on first login via the init system, but administrators can invoke it manually for debugging or custom ISO builds.

---

Stage 2: Owner-Level Setup (Privileged)

The first-run script sources omarchy-provision-owner from bin/omarchy-provision-owner to perform system-wide tasks:

• Creates required system groups
• Installs necessary packages
• Copies immutable configuration files into the provisioning root
• Prepares the environment for user-specific customization

This stage runs without a live graphical session, ensuring the base system is ready before any desktop components load.

---

Stage 3: User-Level Setup (Unprivileged)

After privileged work completes, omarchy-provision-user (from bin/omarchy-provision-user) executes in the user's context. This script performs the actual home directory population:

1. Configuration deployment — Uses omarchy-refresh-config to copy files from $OMARCHY_PATH/config/ to $HOME/.config/, with automatic backup of existing files
2. Asset installation — Installs user-specific resources from install/user/ (fonts, themes, scripts)
3. Permission setup — Applies group memberships and permissions via the user_groups() function defined in install/provisioning/setup-form.sh

---

Key Provisioning Commands and Usage

Running the Full First-Run Process

# Execute complete provisioning (normally automatic on first boot)

sudo omarchy-provision-first-run

Manual User-Level Provisioning

# Trigger only user-side setup for debugging or reconfiguration

omarchy-provision-user

Refreshing Individual Configuration Files

# Update a specific config file after editing system defaults

omarchy-refresh-config hypr/hyprland.lua

The omarchy-refresh-config command (from bin/omarchy-refresh-config) provides safe, atomic updates with backup generation.

---

Idempotency and Safety Mechanisms

The provisioning system implements marker-based idempotency:

• Each stage creates marker files under $OMARCHY_PROVISIONING_DIR
• Re-execution checks for these markers and skips completed steps
• Subsequent boots automatically bypass provisioning once initialization succeeds

This design ensures that system updates or user-initiated re-runs never corrupt existing configurations.

---

Source File Reference

Component	Path	Purpose
First-run orchestrator	bin/omarchy-provision-first-run	Main entry point, bootstraps provisioning state
Privileged provisioning	bin/omarchy-provision-owner	System-level setup (groups, packages, base files)
User provisioning	bin/omarchy-provision-user	Home directory population and configuration
Config refresh utility	bin/omarchy-refresh-config	Safe, atomic config file updates
Provisioning utilities	install/provisioning/setup-form.sh	Shared functions including user_groups()
User asset installer	install/user/theme.sh	Theme and font installation
Default configurations	config/	Source tree copied to ~/.config/
Migration example	migrations/1786539345.sh	Demonstrates provisioning integration

---

Summary

• Three-stage pipeline: bootstrap → owner setup → user setup, enabling unattended ISO and chroot installations
• Home directory population: omarchy-provision-user copies config/ to ~/.config/ via omarchy-refresh-config with automatic backups
• Privilege separation: privileged operations run first without graphical session, then user context takes over
• Idempotent by design: marker files prevent duplicate execution across reboots
• Extensible structure: install/provisioning/ for system code, install/user/ for user assets

---

Frequently Asked Questions

What triggers the provisioning system on a fresh Omarchy install?

The init system invokes omarchy-provision-first-run automatically on first login. This script detects the uninitialized state and executes the full three-stage pipeline. Administrators can also run it manually with sudo for debugging or custom deployment scenarios.

Can I re-run provisioning without losing my existing configurations?

Yes. The omarchy-refresh-config command backs up existing files before overwriting them. Additionally, marker-based idempotency ensures that stage-level operations skip themselves if already completed, though manual re-invocation of specific commands remains possible.

Where are the default configuration files stored before copying to my home directory?

Default configurations live in the config/ directory at the repository root ($OMARCHY_PATH/config/). The provisioning system mirrors this structure into your home directory, typically at ~/.config/, using the refresh utility to handle conflicts safely.

How does Omarchy handle user groups and permissions during provisioning?

The user_groups() function in install/provisioning/setup-form.sh defines required group memberships. The owner-level script applies these system-wide, while the user-level provisioning ensures the current user receives appropriate supplementary groups without requiring additional authentication.

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