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

> Learn how Omarchy populates a new user's home directory by copying default config files with the omarchy-refresh-config utility during first login.

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

---

**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/`

```bash

# 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`](https://github.com/basecamp/omarchy/blob/main/hypr/hyprland.lua) and [`hypr/bindings.lua`](https://github.com/basecamp/omarchy/blob/main/hypr/bindings.lua).

**`bin/omarchy-refresh-tmux`** performs the same function for terminal multiplexer settings, ensuring [`tmux/tmux.conf`](https://github.com/basecamp/omarchy/blob/main/tmux/tmux.conf) and related files populate the user's home directory correctly.

```bash

# 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`](https://github.com/basecamp/omarchy/blob/main/welcome.sh) and [`wifi.sh`](https://github.com/basecamp/omarchy/blob/main/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:

```bash

# 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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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.