What Is the Purpose of the Seed Layer in Omarchy's Home Directory?

The Seed layer is the first phase of Omarchy's three-step home directory initialization, responsible for copying static configuration files from /etc/skel/ to a new user's $HOME exactly once during account creation.

Omarchy uses a sophisticated architecture to populate user home directories with consistent defaults through three distinct phases. The Seed layer establishes the foundational configuration by deploying baseline dotfiles and resources before any user-specific processing occurs. According to the repository's documented file layout, this initial phase ensures every fresh account starts with identical settings required for the desktop environment to function immediately upon login.

How the Seed Layer Works in Omarchy

The Seed layer operates through a specific mechanism tied to standard Linux user creation tools. It functions as a one-time injection of defaults that cannot handle runtime variables or hardware detection.

Static Defaults via the omarchy-settings Package

Configuration files ship as part of the omarchy-settings package installation. These static files reside in the system skeleton directory at /etc/skel/, including paths like /etc/skel/.config/omarchy/ and /etc/skel/.local/state/omarchy/. The repository stores these templates in the default/ directory, which the package installs to the skeleton location.

User Creation Trigger

The Seed layer activates automatically when creating a new user account. When administrators run useradd -m, Arch Linux copies the entire /etc/skel/ tree into the newly created $HOME. This represents the only moment the Seed layer interacts with the home directory, as documented in docs/file-layout.md.

Limitations and Constraints

Because execution occurs before the user first logs in, the Seed layer cannot reference the actual $HOME path, live environment variables, or perform hardware detection. These dynamic operations remain the responsibility of the Finalize and Resync layers, which execute after the initial seeding completes.

Technical Implementation and Source Files

The architecture is documented in docs/file-layout.md, which defines the three population layers: Seed, Finalize, and Resync. The actual skeleton files live in the repository's default/ folder, containing dotfiles and application launchers that define the initial desktop experience.

After the Seed layer completes, the install/provisioning/ scripts handle the Finalize phase, performing user-specific adjustments that require runtime context. For existing users needing to restore defaults, the bin/omarchy-reinstall-configs command implements the Resync layer, effectively re-applying seeded configurations.

Practical Examples: Working with the Seed Layer

The following commands demonstrate how the Seed layer behaves during user creation and maintenance.

Create a new user and observe the Seed copying:

# Add a new user named "alice"; the -m flag triggers the skeleton copy

sudo useradd -m alice

# Show a few seeded files in alice's home directory

ls -1 /home/alice/.config/omarchy
ls -1 /home/alice/.local/state/omarchy

Inspect what is shipped in the skeleton:

# List the contents that the Seed layer provides

ls -R /etc/skel/.config/omarchy
ls -R /etc/skel/.local/state/omarchy

Re-apply the seeded defaults to an existing user via the Resync layer:

# For an existing user "bob", restore the original defaults

sudo -u bob omarchy-reinstall-configs

Summary

• The Seed layer provides baseline configuration files through the /etc/skel/ mechanism during account creation.
• It executes exactly once when running useradd -m, copying static files from the omarchy-settings package.
• The layer handles only environment-agnostic defaults, while the Finalize layer manages runtime-specific configurations.
• Seeded files originate from the repository's default/ directory and install to /etc/skel/.
• Existing users can restore Seed defaults using the omarchy-reinstall-configs command, which triggers the Resync layer.

Frequently Asked Questions

What exactly does the Seed layer copy into the home directory?

The Seed layer copies all files from /etc/skel/ into the new user's $HOME, including dotfiles in .config/omarchy/, state directories like .local/state/omarchy/, theme resources, and application launchers. These files originate from the default/ directory in the Omarchy repository and ship via the omarchy-settings package.

When does the Seed layer run during user setup?

The Seed layer executes once during account creation when the administrator runs useradd -m or equivalent commands that trigger the skeleton copy mechanism. This occurs before the user first logs in, making it impossible for the Seed layer to access runtime environment variables or perform hardware detection.

How is the Seed layer different from Finalize and Resync?

The Seed layer handles static defaults via /etc/skel/ at creation time, while Finalize runs post-creation scripts from install/provisioning/ to adjust configurations based on actual hardware and environment variables. Resync, implemented through bin/omarchy-reinstall-configs, allows existing users to overwrite their current configs with the original seeded defaults.

Can I update the Seed defaults after installation?

While you cannot re-run the Seed layer on existing users (since it only triggers during useradd), you can update the skeleton files in /etc/skel/ for future users. For existing users, use the omarchy-reinstall-configs command to force the Resync layer, which restores the current seed defaults to that user's home directory.

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