# Runtime Finalization with `omarchy-provision-user`: How Omarchy Prepares User Environments

> Learn about runtime finalization with omarchy-provision-user. Omarchy prepares user environments efficiently using idempotency markers and supports forced re-runs with the --force flag.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-03

---

**The `omarchy-provision-user` script finalizes per-user runtime configuration after system-wide provisioning completes, using idempotency markers to prevent duplicate work and supporting forced re-runs via the `--force` flag.**

In the Omarchy repository, user environment setup is deliberately split into **static configuration** (applied during the initial refresh) and **runtime finalization** (applied when a user actually logs in). The `omarchy-provision-user` script handles the latter—steps that cannot be expressed in configuration files because they depend on the active user context, such as dev-aware skill symlinks or per-user state directories.

## What `omarchy-provision-user` Does

The script performs **runtime-only tweaks** that complete a user's Omarchy environment. These include creating skill symlinks, adjusting user-specific configurations, and setting up per-user runtime state.

According to the [Omarchy source code](https://github.com/omacom/omarchy/tree/quattro), the finalizer is designed to be:

- **Idempotent** – Safe to run multiple times without side effects
- **Conditional** – Skips work when a completion marker exists
- **Forceable** – Allows override via `--force` for upgrades or repairs

## How the Finalization Chain Works

Three scripts cooperate to ensure proper initialization:

| Script | Purpose | Key Interaction |
|--------|---------|---------------|
| `omarchy-provision-owner` | System-wide provisioning | Calls user finalizer after system setup |
| `omarchy-provision-first-run` | First-login wrapper | Builds arguments and invokes finalizer |
| `omarchy-provision-user` | Per-user runtime finalization | Executes actual user-level setup |

### 1. System-Wide Provisioning Triggers User Finalization

After installing packages and configuring system services, `omarchy-provision-owner` invokes the user finalizer with flags indicating a first-install scenario:

```bash
"$OMARCHY_PATH/bin/omarchy-provision-user" --force --first-install

```

*See [omarchy-provision-owner#L851](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-provision-owner#L851)*

### 2. First-Run Wrapper Collects Arguments

The `omarchy-provision-first-run` script gathers configuration arguments and passes them to the finalizer:

```bash
omarchy-provision-user "${finalize_user_args[@]}" || true

```

*See [omarchy-provision-first-run#L46](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-provision-first-run#L46)*

Argument collection occurs earlier in the same script (lines 19–24), allowing customization of the finalization process.

### 3. User Finalization Executes Runtime Logic

Once invoked, `omarchy-provision-user` follows this control flow:

```bash

# Check for existing completion marker

if omarchy-done check finalize-user && (( force == 0 )); then
    exit 0
fi

# ... perform runtime setup ...

# Record completion

omarchy-done mark finalize-user

```

*See idempotency check at [L59](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-provision-user#L59) and marker creation at [L130](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-provision-user#L130)*

The usage signature is defined at [L10](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-provision-user#L10).

## Idempotency and the Marker System

The finalizer avoids redundant work through **state markers** stored in `~/.local/state/omarchy/done/`.

| Command | Behavior |
|---------|----------|
| `omarchy-done check finalize-user` | Returns success if marker exists |
| `omarchy-done mark finalize-user` | Creates marker after successful completion |

The `--force` flag bypasses this check, enabling re-finalization after environment changes or upgrades.

## Practical Usage Examples

```bash

# Automatic first-login execution (no manual invocation needed)

# This runs automatically via shell profile integration

# Force re-finalization after adding new skills

omarchy-provision-user --force

# Typical invocation from system provisioning

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

```

## Why Separate Runtime Finalization?

Certain configuration steps **cannot be performed statically**:

- **Dev-aware symlinks** – Skill directories may reference `OMARCHY_PATH` locations that differ across installations
- **Per-user state** – Marker files and runtime directories must reside in `$HOME`
- **Conditional setup** – Some steps depend on the execution environment present only during active login

By isolating these in `omarchy-provision-user`, Omarchy maintains clean separation between system-level and user-level concerns.

## Source File Reference

| File | URL |
|------|-----|
| `bin/omarchy-provision-user` | https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-provision-user |
| `bin/omarchy-provision-owner` | https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-provision-owner |
| `bin/omarchy-provision-first-run` | https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-provision-first-run |
| `bin/omarchy-done` | https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-done |

## Summary

- **`omarchy-provision-user`** completes per-user environment setup that static configuration cannot express
- **Idempotency markers** in `~/.local/state/omarchy/done/` prevent duplicate work; use `--force` to override
- The script is invoked automatically via `omarchy-provision-first-run` or directly from `omarchy-provision-owner` during first install
- **Dev-aware paths** and user-specific state require this runtime separation from system-wide provisioning

## Frequently Asked Questions

### How do I re-run the user finalizer after modifying my Omarchy skills?

Pass the `--force` flag to bypass the idempotency check: `omarchy-provision-user --force`. This recreates symlinks and applies any new runtime configuration without requiring manual marker deletion.

### Where does `omarchy-provision-user` store its completion state?

The marker file is created at `~/.local/state/omarchy/done/finalize-user` via the `omarchy-done mark` command, checked via `omarchy-done check` at [L59](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-provision-user#L59).

### What is the difference between `omarchy-provision-owner` and `omarchy-provision-user`?

`omarchy-provision-owner` performs **system-wide** setup (packages, services, global configuration) while `omarchy-provision-user` handles **per-user** runtime finalization that requires an active user environment. The owner script triggers the user script at [L851](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-provision-owner#L851) during first install.

### When is `omarchy-provision-first-run` executed?

This wrapper runs automatically when a user logs in for the first time, collecting arguments and invoking the finalizer at [L46](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-provision-first-run#L46) to complete environment setup before interactive use begins.