# What Is Dev-Link Mode in Omarchy? A Complete Development Workflow Guide > Discover Omarchy's dev-link mode for instant local testing. This guide explains how to redirect the runtime to your checkout without reinstallation, streamlining your development workflow. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: how-to-guide - Published: 2026-09-08 --- **Dev-link mode redirects the Omarchy runtime to a local source checkout by writing `OMARCHY_PATH` to [`/etc/omarchy.conf`](https://github.com/omacom/omarchy/blob/main//etc/omarchy.conf) and modifying sudo's secure_path, allowing developers to test changes instantly without reinstalling the package.** Omarchy is an open-source agent orchestration framework maintained by **omacom/omarchy**. **Dev-link mode in Omarchy** provides a streamlined mechanism to develop against a local Git checkout rather than the system-installed package, ensuring that contributors can iterate on core functionality and skills without disrupting the stable installation. ## How Dev-Link Mode Works in Omarchy ### Writing System-Wide Configuration When you execute `omarchy dev link `, the script located at `bin/omarchy-dev-link` creates [`/etc/omarchy.conf`](https://github.com/omacom/omarchy/blob/main//etc/omarchy.conf) containing `export OMARCHY_PATH=""` (see lines 81–84 and 10–13). This environment variable persists across reboots, ensuring all future processes resolve the Omarchy runtime against your local checkout rather than the default `/usr/share/omarchy` installation. ### Adjusting Sudo Secure Path The tool generates a temporary sudoers file that prepends `/bin` to the system's `secure_path`, installing it as `/etc/sudoers.d/omarchy-dev-path` (lines 23–30, 98–102, and 15–16). This ensures that commands executed via `sudo` immediately resolve to the checkout's binaries, keeping root-level operations synchronized with your development tree. ### Validation and Safety Checks Before installing the sudoers override, the script validates the file using `visudo -cf` (lines 104–107). This prevents syntax errors that could lock users out of sudo privileges, ensuring the **Omarchy dev-link mode** remains safe for system-level development. ### Reboot Requirements Because Hyprland, systemd, login shells, and application launchers read `$OMARCHY_PATH` only during initialization, the command prompts for a system reboot unless you supply the `--no-reboot` flag (lines 21–23). A reboot guarantees that all runtime layers pick up the new path and skill symlinks resolve correctly. ## Using Dev-Link Mode for Local Development To activate development mode against a local repository: ```bash # Link a local checkout and prompt for reboot omarchy dev link ~/omarchy # Link without rebooting (useful in automation scripts) omarchy dev link ~/omarchy --no-reboot # Revert to the packaged installation omarchy dev unlink ``` The `omarchy dev unlink` command, implemented in `bin/omarchy-dev-unlink`, restores the default configuration by resetting `OMARCHY_PATH` to `/usr/share/omarchy` in [`/etc/omarchy.conf`](https://github.com/omacom/omarchy/blob/main//etc/omarchy.conf) and removing `/etc/sudoers.d/omarchy-dev-path` (lines 50–58). ## Symlink-Based Skill Integration According to the file-layout documentation, **dev-link mode in Omarchy** leverages symlink-based skill linking. Any skill directory under `$OMARCHY_PATH/default/agents/skills/` is symlinked into the user's `~/.agents/skills/` hierarchy (see [`docs/file-layout.md`](https://github.com/omacom/omarchy/blob/main/docs/file-layout.md), line 211). Because these symlinks resolve against `$OMARCHY_PATH`, changing the variable via dev-link instantly retargets all skill-related tooling without requiring package rebuilds or reinstalls. ## Summary - **Dev-link mode** redirects the runtime by setting `OMARCHY_PATH` in [`/etc/omarchy.conf`](https://github.com/omacom/omarchy/blob/main//etc/omarchy.conf) and modifying sudo's `secure_path` via `/etc/sudoers.d/omarchy-dev-path`. - The `omarchy dev link` command validates sudoers syntax with `visudo -cf` before installation to prevent system lockouts. - A reboot is required for Hyprland, systemd, and shell environments to recognize the new path unless using `--no-reboot`. - Skills remain functional through symlinks in `~/.agents/skills/` that point to `$OMARCHY_PATH`, making development changes immediately available. - Use `omarchy dev unlink` to restore the packaged installation from `/usr/share/omarchy`. ## Frequently Asked Questions ### What files does Omarchy dev-link mode modify on my system? Dev-link mode creates two files: [`/etc/omarchy.conf`](https://github.com/omacom/omarchy/blob/main//etc/omarchy.conf) containing the `OMARCHY_PATH` export, and `/etc/sudoers.d/omarchy-dev-path` adjusting sudo's secure_path. It does not touch fixed-location resources like files in `/etc/`, `/usr/lib/systemd/`, or `/usr/share/plymouth`, which remain unchanged according to lines 34–38 of `bin/omarchy-dev-link`. ### Why does dev-link mode require a reboot in Omarchy? Most system layers including Hyprland, systemd, login shells, and application launchers read the `OMARCHY_PATH` environment variable only during initialization. While the sudoers adjustment takes effect immediately, a full reboot ensures all user-space components resolve skills and binaries from the new checkout path, as noted in lines 21–23 of the implementation. ### How do I safely exit dev-link mode and return to the stable package? Run `omarchy dev unlink` to automatically rewrite [`/etc/omarchy.conf`](https://github.com/omacom/omarchy/blob/main//etc/omarchy.conf) to point back to `/usr/share/omarchy` and remove the sudoers drop-in file. The command optionally prompts for a reboot to ensure the system fully reverts to the packaged installation state (lines 50–58 of `bin/omarchy-dev-unlink`). ### Can I use dev-link mode for testing package builds? No, dev-link mode is specifically for runtime redirection against a source tree. To test modifications to fixed paths like systemd units or Plymouth themes, use `omarchy dev pkg-test` instead, which rebuilds and installs the package properly rather than symlinking the runtime directory.