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

> Discover the Omarchy first-run provisioning script at basecamp/omarchy bin/omarchy-provision-first-run. Automate initial system configuration with owner and user setup tasks.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-28

---

**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](https://github.com/basecamp/omarchy/blob/quattro/bin/omarchy-provision-first-run)
- **`bin/omarchy-provision-owner`** — Handles privileged system setup including group recording and package installation. [View source](https://github.com/basecamp/omarchy/blob/quattro/bin/omarchy-provision-owner)
- **`bin/omarchy-provision-user`** — Manages per-user configuration and service enablement. [View source](https://github.com/basecamp/omarchy/blob/quattro/bin/omarchy-provision-user)
- **`install/provisioning/omarchy-provision-owner.service`** — Systemd unit file that ensures the owner script runs automatically during the first boot sequence. [View source](https://github.com/basecamp/omarchy/blob/quattro/install/provisioning/omarchy-provision-owner.service)
- **[`test/shell.d/first-run-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/first-run-test.sh)** — Automated test suite that validates the script’s behavior and idempotency guarantees. [View source](https://github.com/basecamp/omarchy/blob/quattro/test/shell.d/first-run-test.sh)

## Practical Usage and Code Examples

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

```bash

# Manual invocation (requires root privileges)

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

```

The internal logic follows this simplified structure:

```bash
#!/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.