# What is `omarchy-provision-user`? Understanding Per-User Provisioning in Omarchy > Discover `omarchy-provision-user`, the Omarchy command that sets up individual user environments by seeding configs, running install scripts, and finalizing runtime settings. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: deep-dive - Published: 2026-08-23 --- **`omarchy-provision-user` is the per-user provisioning command in basecamp/omarchy that initializes a user's environment by seeding their configuration repository, executing scripts from `install/user/`, and finalizing runtime settings after system-wide setup completes.** When you log into an Omarchy system for the first time, `omarchy-provision-user` bridges the gap between system-wide installation and a fully personalized development environment. Unlike `omarchy-provision-owner`, which handles global system configuration as root, this command operates within the user's home directory and `$HOME` context to deliver tailored tooling and dotfiles. According to the Omarchy source code, it serves as the final orchestration layer that transforms a fresh installation into a ready-to-use workspace. ## Core Responsibilities of omarchy-provision-user ### Seeding the Configuration Repository The command creates the initial Git commit that backs the user’s Omarchy configuration. As documented in the repository layout, `omarchy-provision-user` performs the "seed repo + initial commit" step immediately after [`git.sh`](https://github.com/basecamp/omarchy/blob/main/git.sh) runs, establishing the version-controlled foundation for all user-specific settings. This ensures that every change a user makes to their Omarchy configuration is tracked from day one, with the initial commit serving as the baseline state. ### Executing Per-User Install Scripts `omarchy-provision-user` automatically discovers and executes every script located under `install/user/` via the entry point [`install/user/all.sh`](https://github.com/basecamp/omarchy/blob/main/install/user/all.sh). This design allows the system to install user-level tools, copy default configs to `$HOME`, and apply runtime tweaks that require the user's specific environment variables or live system state. According to the file layout documentation, adding any leaf script under `install/user/` automatically wires it into the provisioning flow without requiring manual registration. ### Finalizing the Runtime Environment After the system-wide `omarchy-provision-owner` finishes, `omarchy-provision-user` handles the "finalize" step referenced in the runtime finalization section of the docs. This phase ensures that user-specific daemons, shell configurations, and environment variables are properly initialized and active. ### Idempotent and Safe Operation The command is designed to run safely multiple times. By default, it skips work that has already been completed, but the `--force` flag allows explicit re-execution when configurations change or initial runs fail. The test suite in [`test/shell.d/provision-user-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/provision-user-test.sh) validates this idempotent behavior, ensuring that repeated invocations do not corrupt the environment or duplicate settings. ## How omarchy-provision-user Fits Into the Provisioning Pipeline Omarchy uses a two-tier provisioning strategy: 1. **`omarchy-provision-owner`** – Runs as root to configure system packages, services, and global settings (triggered by `install/provisioning/omarchy-provision-owner.service`). 2. **`omarchy-provision-user`** – Runs as the regular user to configure the personal workspace. During ISO installation, the Omarchy boot sequence explicitly calls `omarchy-provision-user --force --first-install` to ensure the first user lands in a fully configured environment immediately after login. ## Usage Examples and Command Flags Run the command once after your first login to initialize your environment: ```bash omarchy-provision-user --first-install ``` Force a re-run to apply new configurations or recover from failed initial attempts: ```bash omarchy-provision-user --force ``` The typical first-boot sequence invoked by the Omarchy ISO combines both flags: ```bash omarchy-provision-user --force --first-install ``` Complete workflow on a fresh system: ```bash # As root: Configure system-wide components omarchy-provision-owner # As the regular user: Configure personal environment omarchy-provision-user --force --first-install ``` ## Key Source Files and Implementation Details Understanding the implementation requires examining these specific files in the basecamp/omarchy repository: - **`bin/omarchy-provision-user`** – The main Bash orchestration script that coordinates repository seeding and script execution. - **[`install/user/all.sh`](https://github.com/basecamp/omarchy/blob/main/install/user/all.sh)** – The entry point that sources and executes all user-level install scripts. - **[`test/shell.d/provision-user-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/provision-user-test.sh)** – Test coverage validating idempotency and correct skill provisioning. - **[`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md)** – Reference documentation describing the provisioning flow and file organization. - **`install/provisioning/omarchy-provision-owner.service`** – Systemd unit that triggers owner-level provisioning, which precedes the user-level phase. ## Summary - **`omarchy-provision-user`** handles per-user setup after the system-wide `omarchy-provision-owner` completes. - It seeds a Git repository for configuration management and executes all scripts in `install/user/` to personalize the environment. - The command supports `--first-install` for initial setup and `--force` for safe re-runs without side effects. - It is idempotent by design, with test coverage ensuring reliability across multiple executions. - The Omarchy ISO invokes this automatically during first boot to deliver a zero-configuration user experience. ## Frequently Asked Questions ### When should I run omarchy-provision-user? Run `omarchy-provision-user` immediately after logging into a new Omarchy system for the first time, or whenever you add new scripts to `install/user/` and want to apply them to your existing environment. The `--first-install` flag indicates this is the initial setup, while omitting it performs a standard check-and-apply run. ### What is the difference between omarchy-provision-user and omarchy-provision-owner? `omarchy-provision-owner` runs with root privileges to install system packages, configure services, and set up machine-wide infrastructure via systemd units like `omarchy-provision-owner.service`. In contrast, `omarchy-provision-user` operates within the user's `$HOME` directory to install personal dotfiles, development tools, and user-specific services that require the user's identity and environment variables. ### Is omarchy-provision-user safe to run multiple times? Yes. The command is explicitly designed to be idempotent according to the test suite in [`test/shell.d/provision-user-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/provision-user-test.sh). Without the `--force` flag, it skips completed steps. With `--force`, it re-executes all steps but handles existing files and configurations safely without duplication or corruption. ### How do I add custom provisioning steps for new users? Create a new script under the `install/user/` directory (for example, [`install/user/setup-my-tools.sh`](https://github.com/basecamp/omarchy/blob/main/install/user/setup-my-tools.sh)). The `omarchy-provision-user` command automatically discovers and executes any script placed in this directory through the [`install/user/all.sh`](https://github.com/basecamp/omarchy/blob/main/install/user/all.sh) entry point, requiring no additional registration or configuration changes to the provisioning system.