What Is the Omarchy First-Run Provisioning Script and How Does It Work?

The Omarchy first-run provisioning script is the Bash orchestration entry point located at bin/omarchy-provision-first-run in the basecamp/omarchy repository that automates the initial configuration of a fresh installation by executing system-wide owner provisioning followed by per-user setup tasks.

The basecamp/omarchy repository provides a specialized provisioning system designed to transform a blank machine into a fully configured Omarchy environment. The Omarchy first-run provisioning script serves as the critical bridge between the initial boot and a usable system, ensuring that all groups, packages, and user configurations are applied automatically before the first login.

How the First-Run Provisioning Script Works

The script follows a strict four-stage pipeline to ensure that dependencies are established in the correct order.

Bootstrapping the Provisioning Environment

First, the script prepares the state directory at /var/lib/omarchy/provisioning. This directory stores temporary flags and metadata used by downstream provisioning stages. The script ensures the directory exists and is writable before proceeding to any destructive or configuration-changing operations.

Executing Owner-Side Provisioning

Next, the script invokes omarchy-provision-owner (located at bin/omarchy-provision-owner). This stage runs with elevated privileges to perform system-wide actions:

• Records system-wide group memberships required for Omarchy functionality
• Creates the dedicated install user if it does not already exist
• Installs system-wide packages required for all users

This separation ensures that global system state is prepared before any user-specific configuration begins.

Executing User-Side Provisioning

After the owner stage completes, the script calls omarchy-provision-user (located at bin/omarchy-provision-user). This stage configures the first user account:

• Adds the initial user to the groups recorded during the owner stage
• Copies default configuration files into ~/.config/
• Enables optional services such as Docker and network management that are safe to activate during the first run

Finalizing the First-Run

Finally, the script marks the provisioning as complete by creating the file /var/lib/omarchy/provisioning/done. It then removes any temporary state files and optionally triggers a system reboot to ensure that all newly enabled services start with the correct configuration.

Key Source Files and Architecture

Understanding the repository layout reveals how the components interact:

• bin/omarchy-provision-first-run — The main orchestration script that sequences the provisioning pipeline. View source
• bin/omarchy-provision-owner — Handles privileged system setup including group recording and package installation. View source
• bin/omarchy-provision-user — Manages per-user configuration and service enablement. View source
• install/provisioning/omarchy-provision-owner.service — Systemd unit file that ensures the owner script runs automatically during the first boot sequence. View source
• test/shell.d/first-run-test.sh — Automated test suite that validates the script’s behavior and idempotency guarantees. View source

Practical Usage and Code Examples

While the script typically runs automatically via systemd, you can invoke it manually for debugging or custom installation scenarios:

# Manual invocation (requires root privileges)

sudo /usr/local/bin/omarchy-provision-first-run

The internal logic follows this simplified structure:

#!/usr/bin/env bash
set -euo pipefail

# 1. Prepare provisioning directory

PROV_DIR=${OMARCHY_PROVISIONING_DIR:-/var/lib/omarchy/provisioning}
mkdir -p "$PROV_DIR"

# 2. Run owner provisioning (system-wide setup)

/usr/local/bin/omarchy-provision-owner

# 3. Run user provisioning (per-user setup)

/usr/local/bin/omarchy-provision-user

# 4. Mark provisioning complete

touch "$PROV_DIR/done"

Idempotency and Safety Mechanisms

The Omarchy first-run provisioning script is designed to be idempotent. Before executing any provisioning steps, it checks for the existence of /var/lib/omarchy/provisioning/done. If the marker exists, the script exits immediately without reapplying configuration changes. This safety mechanism prevents accidental reconfiguration during reboots or if the script is triggered multiple times, ensuring that provisioning actions are performed exactly once per installation.

Summary

• The Omarchy first-run provisioning script at bin/omarchy-provision-first-run orchestrates the entire initial setup process for new Omarchy installations.
• It sequentially executes omarchy-provision-owner for system-wide configuration and omarchy-provision-user for per-user setup.
• The script relies on a completion flag at /var/lib/omarchy/provisioning/done to provide idempotent behavior across system reboots.
• All source files reside in the basecamp/omarchy repository under the quattro branch, with systemd integration via install/provisioning/omarchy-provision-owner.service.

Frequently Asked Questions

Where is the Omarchy first-run provisioning script located?

The script is located at bin/omarchy-provision-first-run within the basecamp/omarchy repository. When deployed to a target system, it typically installs to /usr/local/bin/omarchy-provision-first-run and is executed automatically by the systemd unit omarchy-provision-owner.service during the first boot.

What happens if the first-run provisioning script is interrupted?

If the script is interrupted due to a crash or power loss, the completion marker /var/lib/omarchy/provisioning/done is never created. On the next execution, the script detects the missing marker and restarts the provisioning process from the beginning, ensuring that partial configurations are completed without requiring manual cleanup.

How does the script differ from omarchy-provision-owner and omarchy-provision-user?

The first-run script acts as an orchestration wrapper that calls the two specialized components in sequence. omarchy-provision-owner performs privileged system-wide tasks like recording group memberships and installing packages, while omarchy-provision-user handles unprivileged per-user configuration such as adding the first user to recorded groups and copying default dotfiles to ~/.config/.

Can I run the first-run provisioning script manually on an existing installation?

While you can manually execute sudo /usr/local/bin/omarchy-provision-first-run, the script will exit immediately upon discovering the /var/lib/omarchy/provisioning/done marker on an already provisioned system. This design prevents accidental reconfiguration of active production environments.

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