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

> Discover how Omarchy provisioning populates user home directories in this technical guide. Learn about its three-stage pipeline for configuration, assets, and permissions.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: deep-dive
- Published: 2026-09-01

---

**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`](https://github.com/omacom/omarchy/blob/main/install/provisioning/setup-form.sh)

---

## Key Provisioning Commands and Usage

### Running the Full First-Run Process

```bash

# Execute complete provisioning (normally automatic on first boot)

sudo omarchy-provision-first-run

```

### Manual User-Level Provisioning

```bash

# Trigger only user-side setup for debugging or reconfiguration

omarchy-provision-user

```

### Refreshing Individual Configuration Files

```bash

# 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`](https://github.com/omacom/omarchy/blob/main/install/provisioning/setup-form.sh) | Shared functions including `user_groups()` |
| User asset installer | [`install/user/theme.sh`](https://github.com/omacom/omarchy/blob/main/install/user/theme.sh) | Theme and font installation |
| Default configurations | `config/` | Source tree copied to `~/.config/` |
| Migration example | [`migrations/1786539345.sh`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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.