How the env-bootstrap System Configures OMARCHY_PATH and PATH in Omarchy

The env-bootstrap system centralizes Omarchy's environment configuration by sourcing a single script across all shell contexts, determining OMARCHY_PATH from /etc/omarchy.conf or defaulting to /usr/share/omarchy, then restructuring PATH to prioritize development binaries when applicable while appending user-level tools and preventing duplicates.

The env-bootstrap mechanism serves as the single source of truth for runtime environment configuration in the basecamp/omarchy repository. This system ensures consistent variable initialization across login shells, SSH sessions, and graphical environments by centralizing logic in one master script. Understanding how the env-bootstrap system configures both OMARCHY_PATH and PATH is essential for developers customizing their Omarchy installation or troubleshooting environment issues.

env-bootstrap System Architecture and Entry Points

The master environment logic resides in default/bash/env-bootstrap, which acts as the centralized configuration engine. This script is invoked through multiple wrapper files to ensure coverage across different execution contexts, and its behavior is validated by test/shell.d/dev-env-path-test.sh.

The following files source the bootstrap script:

• etc/profile.d/omarchy.sh – System-wide entry point for login shells, installed to /etc/profile.d/omarchy.sh
• /etc/skel/.bashrc – Interactive shell initialization template
• default/uwsm/env.d/10-omarchy – uwsm Hyprland session environment, installed to /usr/share/uwsm/env.d/10-omarchy
• default/bash/envs – Additional environment sourcing layer

This multi-point sourcing strategy guarantees that whether you access the system via terminal, SSH, or graphical session, the environment remains consistent.

How OMARCHY_PATH Is Determined

The bootstrap script first establishes the OMARCHY_PATH variable, which defines the root directory for Omarchy's resources and binaries. The logic implements a cascading configuration pattern with a secure fallback.

Configuration File Parsing

When the script executes, it checks for the presence of /etc/omarchy.conf, a host-administrative configuration file typically written by omarchy-dev-link:

if [ -f /etc/omarchy.conf ]; then
  . /etc/omarchy.conf
  : "${OMARCHY_PATH:=/usr/share/omarchy}"
else
  OMARCHY_PATH=/usr/share/omarchy
fi
export OMARCHY_PATH

If /etc/omarchy.conf exists, the script sources it, allowing administrators to override OMARCHY_PATH with an active development checkout (e.g., /home/user/omarchy). The ${OMARCHY_PATH:=/usr/share/omarchy} syntax ensures that if the configuration file omits the variable, it defaults to the packaged production path /usr/share/omarchy. If the configuration file does not exist at all, the script explicitly sets and exports the default path.

PATH Modification Strategy

After establishing OMARCHY_PATH, the script modifies PATH through three distinct stages, each using case-statement pattern matching to prevent duplicate entries. The modifications prioritize system integrity while accommodating development workflows.

Stage 1: Prepending Omarchy Binaries in Dev-Link Mode

When OMARCHY_PATH differs from the default /usr/share/omarchy (indicating a development link), the script prepends the custom Omarchy binary directory to ensure development builds take precedence:

if [ "$OMARCHY_PATH" != /usr/share/omarchy ]; then
  case ":$PATH:" in
    *":${OMARCHY_PATH%/}/bin:"*) ;;
    *) PATH="${OMARCHY_PATH%/}/bin${PATH:+:$PATH}" ;;
  esac
fi

This conditional prepending ensures that development versions of Omarchy tools override system-wide installations only when explicitly configured via /etc/omarchy.conf.

Stage 2: Appending Mise Shims

The script unconditionally appends the mise version manager shims directory, which provides user-installed language runtimes:

case ":$PATH:" in
  *":$HOME/.local/share/mise/shims:"*) ;;
  *) PATH="${PATH:+$PATH:}$HOME/.local/share/mise/shims" ;;
esac

By appending rather than prepending, the system preserves the priority of distribution-managed binaries while making user-managed tool versions available.

Stage 3: Appending User-Local Binaries

Finally, the script appends the user's local binary directory:

case ":$PATH:" in
  *":$HOME/.local/bin:"*) ;;
  *) PATH="${PATH:+$PATH:}$HOME/.local/bin" ;;
esac

export PATH

This placement ensures that user-installed utilities are available but do not override system or Omarchy-specific tools.

Duplicate Prevention Mechanism

Each modification stage uses the case ":$PATH:" in *":$target:"*) pattern to wrap the existing PATH with colons, enabling reliable substring matching. This technique prevents the accumulation of duplicate entries across multiple shell initializations, particularly important for long-running sessions or nested shells.

Complete Execution Flow

The env-bootstrap script executes the following deterministic sequence:

1. Source configuration: Checks for and sources /etc/omarchy.conf if present
2. Set OMARCHY_PATH: Defaults to /usr/share/omarchy if not set by configuration
3. Export OMARCHY_PATH: Makes the variable available to child processes
4. Conditional PATH prepend: Adds ${OMARCHY_PATH%/}/bin to the front only when in development mode
5. PATH append operations: Adds mise shims and ~/.local/bin to the end, skipping duplicates
6. Export PATH: Finalizes the environment for all inheriting processes

Practical Configuration Examples

Inspecting the environment after sourcing reveals the bootstrap behavior in different scenarios.

Production installation with default paths:

$ source /usr/share/omarchy/default/bash/env-bootstrap
$ echo "$OMARCHY_PATH"
/usr/share/omarchy
$ echo "$PATH"
/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/home/user/.local/share/mise/shims:/home/user/.local/bin

Development link configuration:

# After configuring /etc/omarchy.conf to point to /home/dev/omarchy

$ source /usr/share/omarchy/default/bash/env-bootstrap
$ echo "$OMARCHY_PATH"
/home/dev/omarchy
$ echo "$PATH"
/home/dev/omarchy/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/home/dev/.local/share/mise/shims:/home/dev/.local/bin

The development example demonstrates how /home/dev/omarchy/bin appears at the beginning of PATH, while the mise shims and local bin directories maintain their positions at the end.

Duplicate prevention verification:

$ export PATH="/usr/bin:/home/user/.local/bin"
$ source /usr/share/omarchy/default/bash/env-bootstrap
$ echo "$PATH"
/usr/bin:/home/user/.local/bin:/home/user/.local/share/mise/shims

Note that ~/.local/bin appears only once, and the mise shims are appended without duplication.

Summary

• The env-bootstrap system centralizes environment configuration in default/bash/env-bootstrap, sourced by multiple shell entry points including etc/profile.d/omarchy.sh and the uwsm environment.
• OMARCHY_PATH defaults to /usr/share/omarchy but can be overridden via /etc/omarchy.conf for development workflows.
• PATH modifications occur in three stages: conditional prepending of Omarchy binaries (development mode only), followed by appending mise shims and user-local binaries.
• Duplicate prevention uses colon-wrapped pattern matching to ensure idempotent environment configuration across multiple shell initializations.
• The system maintains hierarchical tool priority: development builds override system packages, while user tools supplement rather than replace system utilities.

Frequently Asked Questions

How do I switch to a development version of Omarchy using env-bootstrap?

Create or modify /etc/omarchy.conf to set OMARCHY_PATH to your local checkout directory (e.g., /home/user/omarchy). When you next source default/bash/env-bootstrap or start a new shell, the script will detect the non-default path, prepend your checkout's bin directory to PATH, and export the updated OMARCHY_PATH variable.

Why does the env-bootstrap script append rather than prepend user directories to PATH?

The script appends $HOME/.local/share/mise/shims and $HOME/.local/bin to maintain security and system integrity. This ordering ensures that distribution-managed binaries in /usr/bin and Omarchy's own tools take precedence over user-installed utilities, reducing the risk of command shadowing by untrusted or experimental software.

What prevents duplicate PATH entries when sourcing env-bootstrap multiple times?

The script uses case-statement pattern matching with colon-wrapped PATH strings (case ":$PATH:" in *":$target:"*)). This technique detects existing entries regardless of their position in the colon-separated list, allowing the script to skip appending or prepending if the directory is already present, making the configuration idempotent across nested shells or repeated sourcing.

Where should I look to verify that env-bootstrap is running in my shell session?

Check the value of OMARCHY_PATH using echo $OMARCHY_PATH. If it returns /usr/share/omarchy or your configured development path, the bootstrap has executed. For debugging, you can also examine the first few entries of your PATH variable to verify that development binaries appear at the front (if applicable) and that mise shims appear at the end without duplication.

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