How Omarchy Populates a New User's Home Directory: Config Workflow Explained

Omarchy populates a new user's home directory by copying default configuration files from $OMARCHY_PATH/config into ~/.config using the omarchy-refresh-config utility, which automatically executes via first-run hooks when the user initially logs in.

When deploying the Omarchy desktop environment from the basecamp/omarchy repository, the toolkit automatically provisions user environments without manual intervention. This process ensures that every new user receives a fully configured ~/.config directory containing default templates for Hyprland, tmux, and other subsystems before any interactive applications launch.

The Default Config Repository Structure

All shipped configuration templates reside in the $OMARCHY_PATH/config directory within the Omarchy installation root. This repository contains organized subdirectories for each subsystem, including hypr/ for Hyprland window manager settings, tmux/ for terminal multiplexer configuration, and omarchy/ for core toolkit settings. When the system needs to populate a new user's home directory, it treats this location as the authoritative source of truth for initial user environments.

The Core Refresh Utility (bin/omarchy-refresh-config)

The bin/omarchy-refresh-config script serves as the atomic unit of configuration deployment. This utility handles the safe copying of a single configuration file from the system-wide defaults to the user's personal ~/.config directory.

According to the source code in bin/omarchy-refresh-config, the script performs three critical operations:

1. Creates the target directory structure in ~/.config if it does not exist
2. Backs up any existing user configuration as filename.bak.<timestamp> to prevent data loss
3. Copies the default file from $OMARCHY_PATH/config/ to the appropriate location within ~/.config/

# Deploy a single configuration file to the current user's home directory

$ omarchy-refresh-config hypr/hyprland.lua

#  • Creates ~/.config/hypr if needed

#  • Backs up any existing file as ~/.config/hypr/hyprland.lua.bak.<timestamp>

#  • Copies $OMARCHY_PATH/config/hypr/hyprland.lua into the user's config

High-Level Refresh Scripts

While omarchy-refresh-config handles individual files, Omarchy provides high-level convenience scripts that orchestrate multiple configuration updates for specific subsystems. These scripts reside in the bin/ directory and invoke the core utility for each relevant configuration file.

bin/omarchy-refresh-hyprland automatically deploys the complete Hyprland window manager configuration set by executing multiple omarchy-refresh-config calls for files such as hypr/hyprland.lua and hypr/bindings.lua.

bin/omarchy-refresh-tmux performs the same function for terminal multiplexer settings, ensuring tmux/tmux.conf and related files populate the user's home directory correctly.

# Copy the complete Hyprland configuration set to a new user

$ omarchy-refresh-hyprland   # runs a series of omarchy-refresh-config calls:

# → omarchy-refresh-config hypr/hyprland.lua

# → omarchy-refresh-config hypr/bindings.lua

# → … (other hypr files)

First-Run Hooks and Automatic Deployment

The automatic population of a new user's home directory occurs through systemd user service hooks installed during the initial setup process. Scripts located in install/user/first-run/—such as welcome.sh and wifi.sh—execute automatically on the user's first login session.

These first-run scripts export the HOME environment variable (defaulting to $USERHOME if unset) and then invoke the high-level refresh utilities to seed the initial configuration:

# install/user/first-run/welcome.sh (installed as a post-update hook)

HOME="${HOME:-$USERHOME}"

# Populate a minimal set of config files

omarchy-refresh-config hypr/hyprland.lua
omarchy-refresh-config tmux/tmux.conf

# … other subsystems …

The test suite validates this behavior in test/shell.d/voxtype-invitation-test.sh, ensuring that the refresh mechanism triggers correctly during the initial user session and completes before the desktop environment initializes.

Backup Behavior and Safety Mechanisms

Before overwriting any existing user configuration, Omarchy's refresh system implements defensive backup procedures. When omarchy-refresh-config detects an existing file at the destination path, it preserves the user's current settings by creating a timestamped backup with the .bak.<timestamp> extension. This ensures that operations to populate a new user's home directory remain non-destructive, allowing users to recover previous configurations if necessary.

Summary

• Omarchy stores default configurations in $OMARCHY_PATH/config with subdirectories for each subsystem like hypr/, tmux/, and omarchy/.
• The bin/omarchy-refresh-config utility performs atomic copy operations while backing up existing files to ~/.config/filename.bak.<timestamp>.
• High-level scripts such as bin/omarchy-refresh-hyprland orchestrate multiple configuration deployments for specific applications.
• First-run hooks in install/user/first-run/*.sh execute automatically on initial login to populate new user home directories without manual intervention.
• The system validates this workflow through tests in test/shell.d/voxtype-invitation-test.sh.

Frequently Asked Questions

Where does Omarchy store the default configuration templates?

Omarchy maintains all default configuration files in the $OMARCHY_PATH/config directory within the installation root. This includes organized subdirectories for Hyprland, tmux, and other subsystems that serve as the source when the system needs to populate a new user's home directory.

What happens if a user already has configuration files in ~/.config?

Before copying any defaults, the bin/omarchy-refresh-config script automatically backs up existing files by appending .bak.<timestamp> to the filename. This prevents data loss while allowing Omarchy to install its default templates during the first-run process.

How does Omarchy know when to populate a new user's home directory?

The installation process configures systemd user service hooks that execute scripts from install/user/first-run/ automatically upon the user's first login. These hooks call the refresh utilities to copy configurations before any desktop environment or terminal applications initialize.

Can administrators manually trigger the home directory population process?

Yes. Administrators or users can manually invoke bin/omarchy-refresh-config with a specific configuration path, or use high-level scripts like bin/omarchy-refresh-hyprland to redeploy entire configuration sets. These commands function identically whether run automatically during first-login or manually by a system administrator.

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