# How Omarchy Populates the User Home Directory: The Three-Layer System

> Discover Omarchy's three-layer system Seed, Finalize, and Resync for populating user home directories. Learn how static, dynamic, and refresh capabilities work together.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: internals
- Published: 2026-08-27

---

**Omarchy uses a three-layer process—Seed, Finalize, and Resync—to populate user home directories, combining static skeleton files, dynamic runtime provisioning, and destructive refresh capabilities.**

Populating the user's home directory in Omarchy requires more than a simple copy operation. The basecamp/omarchy repository implements a structured three-stage approach that separates static defaults from dynamic configuration, ensuring new users receive consistent setups while allowing existing users to reset their environments safely.

## The Three Layers of Home Directory Population

Omarchy’s architecture divides home directory setup into three distinct stages, each documented in [`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md) within lines 33-45.

### 1. Seed – Static Defaults via /etc/skel/

The **Seed** layer provides static defaults shipped in the `omarchy-settings` package. These files reside under `/etc/skel/` and are copied automatically when creating a new user account. According to the documentation in `docs/file-layout.md#L33-L38`, this is the only stage that touches a brand-new user's files during account creation.

When you execute `useradd` with the `-m` flag, Arch Linux copies the entire `/etc/skel/` tree into the fresh home directory:

```bash

# Seed happens automatically on user creation

sudo useradd -m alice   # copies /etc/skel/* into /home/alice

```

### 2. Finalize – Dynamic Per-User Provisioning

The **Finalize** layer handles items that cannot be pre-seeded because they require runtime expansion of variables like `$HOME` or `$OMARCHY_PATH`. As documented in `docs/file-layout.md#L39-L42`, this stage runs via the `omarchy-provision-user` command, exposed through the `omarchy finalize user` interface.

This script executes once per user to handle system state detection and path-specific configurations:

```bash

# Finalize – run once after first login or manually

omarchy finalize user   # internally calls omarchy-provision-user

```

The implementation in `bin/omarchy-provision-user` includes a safety check ensuring it runs as the target user rather than root:

```bash

# Inside bin/omarchy-provision-user

echo "Error: run omarchy-provision-user as the user being configured, not as root." >&2

```

### 3. Resync – Destructive Configuration Refresh

The **Resync** layer provides an explicit, destructive refresh mechanism for existing users who want to revert all customizations. As noted in `docs/file-layout.md#L43-L45`, the `omarchy-reinstall-configs` command clobbers current `$HOME` contents with the original configuration templates.

```bash

# Resync – reset an existing home to defaults (DESTRUCTIVE)

omarchy-reinstall-configs   # overwrites $HOME with shipped defaults

```

## Key Implementation Files

Three primary files implement this stratified approach to populating the user's home directory:

- **`default/**` → `/etc/skel/`** – Provides the static skeleton copied during account creation via the `omarchy-settings` package.
- **`bin/omarchy-provision-user`** – Executes dynamic per-user runtime setup with user-context validation, requiring execution as the target user.
- **`bin/omarchy-reinstall-configs`** – Handles the destructive overwrite of `$HOME` with shipped defaults.

## Summary

- **Seed** uses `/etc/skel/` static files copied automatically by `useradd -m` for new accounts.
- **Finalize** runs `omarchy-provision-user` once per user to handle dynamic `$HOME` expansion and runtime detection.
- **Resync** executes `omarchy-reinstall-configs` to destructively reset existing home directories to defaults.
- All three layers are documented in [`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md) within the basecamp/omarchy repository.

## Frequently Asked Questions

### What triggers the Seed layer in Omarchy?

The Seed layer triggers automatically when creating a new user account with the `-m` flag via `useradd -m`. Arch Linux copies the contents of `/etc/skel/`—populated by the `omarchy-settings` package—into the newly created home directory according to `docs/file-layout.md#L33-L38`.

### Can I run omarchy-provision-user as root?

No. The script in `bin/omarchy-provision-user` explicitly checks its execution context and aborts if run as root, displaying an error message directing you to run it as the user being configured. This ensures proper file ownership and `$HOME` resolution.

### Is omarchy-reinstall-configs safe to run?

No, it is destructive by design. This command overwrites existing files in your home directory with the default templates shipped in the Omarchy package. Use it only when you intend to reset all customizations and return to the shipped defaults.

### Where are the three layers documented?

The three-layer system is documented in [`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md) at lines 33-45, which details the Seed (lines 33-38), Finalize (lines 39-42), and Resync (lines 43-45) stages and their respective responsibilities in populating the user's home directory.