# What Is the Omarchy-Dev-Link Workflow? A Complete Developer's Guide > Master the omarchy-dev-link workflow a developer helper that re-targets Omarchy runtime to your local checkout for efficient development. Learn how it works. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: deep-dive - Published: 2026-09-03 --- **The `omarchy-dev-link` workflow is a development-only helper that re-targets the Omarchy runtime to a local source checkout by overriding the sudo secure_path and persisting the checkout location, requiring only a reboot to activate.** The `omarchy-dev-link` workflow enables developers to test local modifications in a live Omarchy environment without rebuilding or reinstalling the package. Located in the `omacom/omarchy` repository at `bin/omarchy-dev-link`, this utility redirects system binaries and configuration paths to your working directory through targeted overrides. Understanding this workflow is essential for anyone contributing to core development or testing changes in the `omacom/omarchy` codebase. ## How the Omarchy-Dev-Link Workflow Works This workflow operates through four tightly-coupled actions that safely redirect system resources to your development checkout. ### Validation and Security Checks The script begins by validating the execution context to prevent environment contamination. It explicitly rejects execution under `sudo` to avoid polluting the root environment, as implemented in lines 10-13 of `bin/omarchy-dev-link`. This safeguard ensures that development paths remain isolated from privileged system contexts during the linking process. ### Secure Path Override Mechanism The workflow constructs a temporary sudoers fragment that prepends your checkout's `bin/` directory to the system `secure_path`. This fragment is written to `/etc/sudoers.d/omarchy-dev-path` only after passing a `visudo` syntax check (source lines 99-105). The effect is immediate: subsequent `sudo omarchy-*` commands resolve to the checkout's binaries rather than the packaged system versions. ### Persisting the Checkout Location The absolute path of your checkout is saved to [`/etc/omarchy.conf`](https://github.com/omacom/omarchy/blob/main//etc/omarchy.conf) as the `OMARCHY_PATH` environment variable (source lines 109-113). Many Omarchy components—including shell scripts in `shell/`, theme assets in `themes/`, and default configurations in `default/`—resolve paths relative to this variable, making the redirection comprehensive across the application stack. ### Reboot Activation Because the `OMARCHY_PATH` variable affects the running user session, a reboot is required to fully activate the linked environment. Unless invoked with the `--no-reboot` flag, the script presents an interactive reboot prompt using `gum confirm` and triggers `omarchy-system-reboot` upon affirmation (source lines 21-23). ## Using the Omarchy-Dev-Link Command Basic usage requires only the path to your local checkout: ```bash # Point Omarchy at a checkout and trigger a reboot prompt omarchy dev link ~/src/omarchy ``` For automation or chaining commands, suppress the reboot prompt: ```bash # Suppress reboot – useful when the next command handles restarting omarchy dev link ~/src/omarchy --no-reboot ``` To restore the original system configuration, use the companion unlink command: ```bash # Undo the link and remove overrides omarchy dev unlink ``` Verify the configuration took effect by inspecting the persisted files: ```bash # Check the persisted path in the configuration cat /etc/omarchy.conf # Verify the secure_path override in sudoers sudo cat /etc/sudoers.d/omarchy-dev-path ``` ## Scope and Limitations of the Workflow The `omarchy-dev-link` workflow deliberately limits its scope to resources that are **path-resolved** via `OMARCHY_PATH`. This includes directories such as `bin/`, `default/`, `shell/`, `themes/`, `applications/`, and `config/` within your checkout. Fixed-system assets remain untouched. Files under `/etc/` (outside the [`omarchy.conf`](https://github.com/omacom/omarchy/blob/main/omarchy.conf) entry) or `/usr/lib/systemd/` are not modified by this workflow. If you need to test changes to these system-level components, you must rebuild the package using `omarchy-dev-pkg-test` instead. ## Summary - The `omarchy-dev-link` workflow connects local source checkouts to the running Omarchy system without package reinstallation or rebuilding. - It creates a sudoers fragment at `/etc/sudoers.d/omarchy-dev-path` to override the `secure_path` for elevated commands, routing `sudo omarchy-*` calls to your checkout. - The checkout location is persisted to [`/etc/omarchy.conf`](https://github.com/omacom/omarchy/blob/main//etc/omarchy.conf) as `OMARCHY_PATH` for system-wide path resolution across shell scripts and assets. - A reboot is required to activate the changes in the user session, though the `--no-reboot` flag allows deferring this step when chaining commands. - Use `omarchy-dev-unlink` (via `omarchy dev unlink`) to restore the original system configuration and remove all path overrides. ## Frequently Asked Questions ### What is the difference between `omarchy-dev-link` and `omarchy-dev-pkg-test`? `omarchy-dev-link` redirects path-resolved resources to a local checkout by modifying `OMARCHY_PATH` and the sudo `secure_path`, requiring only a reboot to test changes. In contrast, `omarchy-dev-pkg-test` performs a full package rebuild and installation, which is necessary when modifying fixed-system assets like files under `/etc/` or systemd units that cannot be resolved through path variables. ### Why does `omarchy-dev-link` require a reboot? The workflow persists the checkout location to [`/etc/omarchy.conf`](https://github.com/omacom/omarchy/blob/main//etc/omarchy.conf) as `OMARCHY_PATH`, which many components reference during session initialization. Since environment variables for running processes cannot be modified retroactively, a reboot ensures that the new user session and all Omarchy services initialize with the correct path context derived from your linked checkout. ### How do I undo a dev link and restore the system configuration? Execute `omarchy dev unlink` to remove the sudoers fragment at `/etc/sudoers.d/omarchy-dev-path` and delete the [`/etc/omarchy.conf`](https://github.com/omacom/omarchy/blob/main//etc/omarchy.conf) file, restoring the system's default binary paths. This command is implemented in `bin/omarchy-dev-unlink` and immediately restores the original configuration without requiring a package reinstall. ### Is it safe to run `omarchy-dev-link` multiple times? Yes, running the command multiple times is safe. Each execution overwrites the previous configuration in [`/etc/omarchy.conf`](https://github.com/omacom/omarchy/blob/main//etc/omarchy.conf) and `/etc/sudoers.d/omarchy-dev-path` with the new checkout path after passing the same `visudo` validation checks. However, you must reboot after each change to ensure the running session reflects the latest `OMARCHY_PATH` variable.