What Are the Three Layers of Provisioning in Omarchy?

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

omarchy-provision-user

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

omarchy-reinstall-configs

The implementation resides in 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 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 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, which executes both Seed (via standard useradd) and Finalize (via omarchy-provision-user --first-install) in sequence during the first boot after installation.

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