# What Are the Three Layers of Provisioning in Omarchy?

> Discover Omarchy's three provisioning layers: Seed, Finalize, and Resync. Learn how these layers manage user home directory configuration effectively.

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

---

**Omarchy uses three provisioning layers—Seed, Finalize, and Resync—to populate and manage the user's home directory configuration.**

The Omarchy project implements a structured, layered approach to user environment setup that separates static defaults from dynamic runtime configuration and reset capabilities. According to the project's [file layout documentation](https://github.com/omacom/omarchy/blob/quattro/docs/file-layout.md), this three-layer design ensures reproducible user environments while allowing flexibility for hardware-specific and runtime-dependent customizations.

## The Three Provisioning Layers

### 1. Seed Layer

The **Seed** layer provides the foundational static configuration copied to a user's home directory at creation time.

- Files are sourced from `/etc/skel/` as installed by the `omarchy-settings` package
- Triggered automatically by Arch Linux's `useradd -m` command during user creation
- Contains baseline dotfiles, directories, and default templates

This layer is implemented entirely through standard Unix mechanisms rather than custom Omarchy code. The [file layout specification](https://github.com/omacom/omarchy/blob/quattro/docs/file-layout.md#L33-L45) documents this as the first of the three population stages for `$HOME`.

### 2. Finalize Layer

The **Finalize** layer handles dynamic setup that depends on runtime context and cannot be performed at seed time.

Key responsibilities include:
- Symlinking portable skills into the user environment
- Updating XDG user directories based on current locale and preferences
- Applying per-user hardware quirks and device-specific configurations
- Setting up runtime-dependent paths and caches

Execute this layer manually with:

```bash
omarchy-provision-user

```

The [omarchy-provision-user](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-provision-user) script implements this layer. It is designed to be idempotent and safe to run multiple times.

For ISO installations that defer user creation, the [omarchy-provision-owner.service](https://github.com/omacom/omarchy/blob/quattro/install/provisioning/omarchy-provision-owner.service) systemd unit automatically invokes the Finalize layer on first boot after the owner user is created.

### 3. Resync Layer

The **Resync** layer allows existing users to reset their configuration to current defaults.

Purpose and characteristics:
- Overwrites `$HOME` contents with the latest `/etc/skel/` files
- Useful after Omarchy updates ship new defaults
- Provides a clean-slate option without full user recreation

Enable this layer with:

```bash
omarchy-reinstall-configs

```

The implementation resides in [bin/omarchy-reinstall-configs](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-reinstall-configs). This command does not preserve local modifications—use version control or backups before resyncing.

## Provisioning Workflow in Practice

| Scenario | Layers Involved | Commands |
|----------|----------------|----------|
| Fresh user creation | Seed → Finalize | `useradd -m <user>` then automatic or manual `omarchy-provision-user` |
| Deferred ISO install | Seed → Finalize (delayed) | Boot triggers `omarchy-provision-owner.service` |
| Update defaults | Resync | `omarchy-reinstall-configs` |
| Runtime reconfiguration | Finalize only | `omarchy-provision-user` |

## Deferred Provisioning Note

Installations built with the ISO generator may skip initial user creation, entering a deferred provisioning state. In this mode, the [omarchy-provision-owner.service](https://github.com/omacom/omarchy/blob/quattro/install/provisioning/omarchy-provision-owner.service) creates the owner account on first boot and immediately runs the **Finalize** layer. This design separates system image generation from per-user personalization.

## Summary

- **Seed** delivers static defaults from `/etc/skel/` at user creation
- **Finalize** applies dynamic, runtime-dependent configuration via `omarchy-provision-user`
- **Resync** resets existing users to current defaults using `omarchy-reinstall-configs`

The three-layer architecture separates concerns: Seed for immutability, Finalize for adaptability, and Resync for recoverability. All layers are documented in [docs/file-layout.md](https://github.com/omacom/omarchy/blob/quattro/docs/file-layout.md) and implemented across the `bin/` and `install/provisioning/` directories.

## Frequently Asked Questions

### What happens if I run `omarchy-provision-user` multiple times?

The Finalize layer is idempotent. Repeated executions safely reapply dynamic configuration without duplicating entries or breaking existing setup. Symlinks are recreated, XDG directories updated, and hardware quirks re-evaluated based on current system state.

### Can I skip the Seed layer and use Finalize on an existing empty home directory?

No—the Seed layer establishes the baseline directory structure and static files that Finalize expects to find. Running Finalize on an empty `$HOME` may fail or produce incomplete configuration because it assumes certain skeleton files are already present.

### How do I preserve my changes before running Resync?

The Resync layer overwrites files unconditionally. Before running `omarchy-reinstall-configs`, commit or stash modifications in a version control repository such as Git, copy critical files to a backup location, or use `tar` to create an archive of your current configuration state.

### Which layer runs when I create a user through the Omarchy ISO installer?

The ISO defers user creation to the [omarchy-provision-owner.service](https://github.com/omacom/omarchy/blob/quattro/install/provisioning/omarchy-provision-owner.service), which executes both Seed (via standard `useradd`) and Finalize (via `omarchy-provision-user --first-install`) in sequence during the first boot after installation.