What Is the Seed Layer in Omarchy's HOME Population?

The Seed layer is the first stage of Omarchy's HOME population system, where the omarchy-settings package provides baseline configuration files by shipping static defaults to /etc/skel/ that get copied into new user home directories during account creation.

Omarchy's approach to user home directory setup follows a deliberate three-stage architecture. Understanding the Seed layer is essential for system administrators who need to customize default user environments or troubleshoot fresh account creation. This article explains how the Seed layer works, when it executes, and how to interact with it based on the Omarchy source code.

How the Seed Layer Fits Into HOME Population

The Omarchy file layout defines three distinct layers for populating $HOME: Seed, Finalize, and Resync. Each serves a different purpose and runs at a different lifecycle point.

The Seed layer specifically handles brand-new user creation. It is the only mechanism that touches a home directory at the moment of account creation. Later stages handle updates to existing users, but they cannot recreate the initial baseline that Seed provides.

According to the file-layout.md documentation, the Seed layer definition spans lines 33-38, where it describes how static defaults are delivered through the system skeleton mechanism.

What the omarchy-settings Package Provides

The omarchy-settings package is responsible for implementing the Seed layer. It performs two critical functions:

• Ships static defaults to /etc/skel/ during package installation
• Maintains the default/ directory tree in the repository, containing all files intended for new users

Files placed in /etc/skel/ include anything that can be safely copied without per-user expansion: dotfiles like .bashrc, .config/ subdirectories, application launchers, icons, and other static resources.

The package architecture ensures these files remain separate from runtime-generated configurations that require environment variable substitution or hardware detection.

When the Seed Layer Executes

The Seed layer triggers automatically through standard Linux user creation mechanics:

# Standard Arch Linux user creation - Seed layer activates here

sudo useradd -m alice

When useradd -m executes, it copies everything from /etc/skel/ into /home/alice/. This happens before the user first logs in and before any Omarchy-specific finalize scripts run.

You can verify the Seed layer operated correctly:

# Check that seeded files exist in the new home

ls -la /home/alice/.bashrc
ls -la /home/alice/.config/

# Compare with the source skeleton

diff /home/alice/.bashrc /etc/skel/.bashrc

Why Seed Remains a Separate Layer

Some configurations cannot be handled at copy time. The file-layout.md documentation explains that files requiring:

• Knowledge of the actual $HOME path
• Runtime environment variables
• Hardware detection results

...must be deferred to the Finalize layer. Keeping Seed as a simple, copy-only operation ensures:

1. Repeatability — Every new user gets identical starting files
2. Speed — No computation delays account creation
3. Reliability — No dependency on runtime conditions that may not exist

Working With the Seed Layer Manually

While automatic during useradd, you can interact with Seed layer components directly:

# Preview what a new user would receive

tree -a /etc/skel/

# Manually apply Seed to an empty directory (testing scenarios)

mkdir /tmp/testhome
sudo cp -a /etc/skel/. /tmp/testhome/
ls -la /tmp/testhome/

# Examine a specific seeded configuration

cat /etc/skel/.config/omarchy/branding/about.txt

# Check package ownership of skeleton files

pacman -Qo /etc/skel/.bashrc

Key Source Files for the Seed Layer

File	Purpose
[docs/file-layout.md](https://github.com/omacom/omarchy/blob/quattro/docs/file-layout.md)	Documents the three-layer HOME population architecture, including Seed definition at lines 33-38
default/ directory	Contains source files that omarchy-settings installs to /etc/skel/
install/post-install/pacman.sh	Handles post-install deployment of skeleton contents
bin/omarchy-reinstall-configs	Utility command that can re-apply Seed defaults to existing users (destructive operation)

Summary

• The Seed layer provides baseline $HOME contents through /etc/skel/ copies during user creation
• omarchy-settings implements Seed by shipping static defaults that useradd -m automatically deploys
• Seed handles only copy-safe files; dynamic configurations move to the Finalize layer
• Key documentation resides in [docs/file-layout.md](https://github.com/omacom/omarchy/blob/quattro/docs/file-layout.md) lines 33-38
• Administrators can inspect /etc/skel/ directly to preview or modify new user environments

Frequently Asked Questions

What happens if I modify files in /etc/skel/ after creating users?

Changes to /etc/skel/ only affect future user accounts. Existing users retain the files copied at their creation time. To update existing users, Omarchy provides the Resync layer or the omarchy-reinstall-configs command, though the latter is destructive and replaces user modifications.

Can I prevent the Seed layer from running?

The Seed layer is integral to useradd -m behavior. To create a user without Omarchy's defaults, use useradd without the -m flag and create the home directory manually, or remove omarchy-settings from your system before account creation.

How do I add custom files to the Seed layer?

Add files to the default/ directory in the Omarchy repository, rebuild the omarchy-settings package, and reinstall. Alternatively, system administrators can place files directly in /etc/skel/ on deployed systems, though this diverges from package-managed configuration.

What's the difference between Seed and Finalize layers?

Seed runs during account creation via useradd, copying static files from /etc/skel/. Finalize runs at first login, generating dynamic configurations that require runtime information like the actual $HOME path, display environment, or hardware capabilities.

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