What is `omarchy-provision-user`? Understanding Per-User Provisioning in Omarchy

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 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. 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 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:

omarchy-provision-user --first-install

Force a re-run to apply new configurations or recover from failed initial attempts:

omarchy-provision-user --force

The typical first-boot sequence invoked by the Omarchy ISO combines both flags:

omarchy-provision-user --force --first-install

Complete workflow on a fresh system:

# 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 – The entry point that sources and executes all user-level install scripts.
• test/shell.d/provision-user-test.sh – Test coverage validating idempotency and correct skill provisioning.
• 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. 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). The omarchy-provision-user command automatically discovers and executes any script placed in this directory through the install/user/all.sh entry point, requiring no additional registration or configuration changes to the provisioning system.

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