# How omarchy-dev-link Enables Development Against a Local Checkout

> Learn how omarchy-dev-link helps you develop against a local Omarchy checkout. This tool redirects your installation to use local source, streamlining your workflow.

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

---

**`omarchy-dev-link` redirects the running Omarchy installation to use a local source checkout instead of the packaged copy by updating [`/etc/omarchy.conf`](https://github.com/basecamp/omarchy/blob/main//etc/omarchy.conf) and adding a sudoers fragment that modifies the secure path.**

The [`omarchy`](https://github.com/basecamp/omarchy) repository includes a development workflow that lets contributors modify code and test changes without repeatedly reinstalling the package. The `omarchy-dev-link` script, located at [`bin/omarchy-dev-link`](https://github.com/basecamp/omarchy/blob/quattro/bin/omarchy-dev-link), automates this by reconfiguring two critical system locations that Omarchy respects for runtime path resolution.

## How omarchy-dev-link Configures the Runtime Path

### Updating /etc/omarchy.conf

The script writes an `export OMARCHY_PATH="<checkout-path>"` line to [`/etc/omarchy.conf`](https://github.com/basecamp/omarchy/blob/main//etc/omarchy.conf) (lines 6-8 of the script). This environment variable is the primary mechanism Omarchy uses to locate its runtime tree, which includes `bin/`, `default/`, `shell/`, `themes/`, and other directories.

Once set, every unprivileged Omarchy command (`omarchy …`) automatically runs code from the specified checkout rather than the system-packaged version. The [`default/bash/env-bootstrap`](https://github.com/basecamp/omarchy/blob/quattro/default/bash/env-bootstrap) file sources [`/etc/omarchy.conf`](https://github.com/basecamp/omarchy/blob/main//etc/omarchy.conf) early in the user's shell environment to ensure this variable is available.

### Configuring Sudo Access with /etc/sudoers.d/omarchy-dev-path

Because `sudo` ignores the caller's `$PATH` and resolves commands against its own `secure_path`, the script creates a temporary sudoers fragment that prepends the checkout's `bin/` directory to the secure path (lines 9-12 and 95-98). This fragment is validated with `visudo -cf` before installation (lines 100-103) and then installed with `sudo install -Dm440` (line 112).

The result: any `sudo omarchy-*` command resolves to binaries in `$checkout/bin` rather than the packaged versions. This ensures **both regular and privileged Omarchy components use the same source checkout**.

## Reboot Requirements and Handling

Changes to [`/etc/omarchy.conf`](https://github.com/basecamp/omarchy/blob/main//etc/omarchy.conf) only take effect after a reboot because many services—including Hyprland, systemd, and the login shell—read `OMARCHY_PATH` only at startup. The script prompts the user to reboot (lines 17-19) unless the `--no-reboot` flag is supplied (lines 49-55).

```bash

# Link your checkout and prompt for reboot

omarchy dev link ~/omarchy

# Link without reboot prompt (plan to reboot later)

omarchy dev link ~/omarchy --no-reboot

```

## Safety Checks Built Into omarchy-dev-link

The script includes several protective mechanisms:

- **Refuses to run under sudo** (lines 10-13) — prevents permission conflicts
- **Verifies checkout structure** (lines 82-86) — checks for expected directories (`bin`, `default`, `shell`) and warns if missing
- **Validates sudoers syntax** — uses `visudo -cf` to check the generated fragment before installation

## Using omarchy-dev-link in Practice

### Linking a Checkout

```bash

# From your omarchy repository clone

omarchy dev link ~/omarchy

```

### Verifying the Configuration

```bash

# Confirm OMARCHY_PATH points to your checkout

echo "$OMARCHY_PATH"

# → /home/you/omarchy

# Verify sudo resolves omarchy-* from the checkout

sudo which omarchy-launch-terminal

# → /home/you/omarchy/bin/omarchy-launch-terminal

```

### Reverting to Packaged Version

Use the companion script to restore system defaults:

```bash
omarchy dev unlink

```

The [`bin/omarchy-dev-unlink`](https://github.com/basecamp/omarchy/blob/quattro/bin/omarchy-dev-unlink) script removes `/etc/sudoers.d/omarchy-dev-path` and clears the `OMARCHY_PATH` entry from [`/etc/omarchy.conf`](https://github.com/basecamp/omarchy/blob/main//etc/omarchy.conf).

## How omarchy-dev-link Fits Into the Development Workflow

According to the Omarchy source code as implemented in `basecamp/omarchy`, this mechanism enables a tight development loop:

1. Edit code in your local checkout
2. Test changes immediately with `omarchy` commands
3. Use `sudo omarchy-*` for privileged operations, which also run from the checkout
4. Reboot when necessary to pick up environment changes

The [[`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md)](https://github.com/basecamp/omarchy/blob/quattro/docs/file-layout.md) file explicitly documents that [`/etc/omarchy.conf`](https://github.com/basecamp/omarchy/blob/main//etc/omarchy.conf) is written by `omarchy-dev-link`, confirming this is the officially supported development path.

## Summary

- **`omarchy-dev-link`** redirects Omarchy to a local checkout by setting `OMARCHY_PATH` in [`/etc/omarchy.conf`](https://github.com/basecamp/omarchy/blob/main//etc/omarchy.conf) and adding a sudoers fragment for `secure_path`
- **Both unprivileged and privileged commands** use the checkout, ensuring consistent testing
- **Reboot required** for full effect due to early environment loading by services
- **Safety checks** prevent sudo execution, validate checkout structure, and verify sudoers syntax
- **Companion `omarchy-dev-unlink`** script restores packaged behavior

## Frequently Asked Questions

### What happens if I run omarchy-dev-link with sudo?

The script exits with an error. Lines 10-13 of `bin/omarchy-dev-link` explicitly check for sudo execution and refuse to run, preventing permission conflicts that could corrupt the configuration.

### Why do I need to reboot after running omarchy-dev-link?

Many Omarchy services—Hyprland, systemd units, and the login shell—source [`/etc/omarchy.conf`](https://github.com/basecamp/omarchy/blob/main//etc/omarchy.conf) only once at startup. A reboot ensures all components pick up the new `OMARCHY_PATH` value. Use `--no-reboot` to suppress the prompt if you plan to restart later.

### How does omarchy-dev-link affect sudo commands differently than regular commands?

Regular commands read `OMARCHY_PATH` directly from the environment. Sudo commands ignore the caller's `$PATH`, so the script creates `/etc/sudoers.d/omarchy-dev-path` to prepend the checkout's `bin/` to sudo's `secure_path`. This ensures `sudo omarchy-*` resolves to checkout binaries.

### What directories must exist in my checkout for omarchy-dev-link to work?

The script verifies that `bin`, `default`, and `shell` directories exist in the specified path (lines 82-86). These are essential Omarchy components; the script warns and may fail if any are missing, protecting against invalid checkout paths.