How omarchy‑dev‑link Maintains Sudo Access for Local Development

omarchy-dev-link maintains sudo access by injecting a sudoers snippet that prepends your local checkout's bin directory to sudo's secure_path, ensuring privileged commands resolve to development binaries instead of system packages.

When developing Omarchy locally, you need root privileges to test system-level changes—but you also want those commands to execute from your active source checkout rather than the installed package. The omarchy-dev-link helper solves this by reconfiguring sudo's path resolution without compromising security or requiring constant manual overrides.

Creating the Sudoers Snippet

The core mechanism lives in bin/omarchy-dev-link at lines 23–25. The script constructs a temporary sudoers file that redefines secure_path specifically for Omarchy commands:

# Temporary sudoers content generated by omarchy-dev-link

Defaults    secure_path="/home/<user>/omarchy/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"

This prepends the checkout's bin directory to the standard secure path. Only commands matching omarchy-* patterns are affected—other privileged operations retain the system's default path.

Validating Before Installation

Security-critical configuration demands validation. Lines 99–106 run visudo -cf against the generated snippet:

# Validation step from omarchy-dev-link

if ! visudo -cf "$temp_sudoers" >/dev/null 2>&1; then
    echo "Error: Generated sudoers file has syntax errors" >&2
    exit 1
fi

This check prevents installation of malformed rules that could lock you out of sudo access.

Installing with Strict Permissions

Once validated, the snippet deploys to /etc/sudoers.d/omarchy-dev-path with 0440 permissions (lines 15–16). The restrictive mode ensures only root can read or modify the file, satisfying sudoers security requirements.

Setting OMARCHY_PATH for Persistence

Parallel to sudo configuration, the script writes /etc/omarchy.conf (lines 9–13):

# Content written to /etc/omarchy.conf

export OMARCHY_PATH=/home/<user>/omarchy

This environment variable persists across reboots, allowing non-sudo Omarchy components to locate the checkout after system restart.

Immediate Effect Without Reboot

Unlike OMARCHY_PATH, the sudoers change takes effect immediately upon installation. Lines 17–19 confirm this with informational output:

Sudo now uses development binaries from: /home/<user>/omarchy/bin
Run 'sudo which omarchy-launch' to verify

You can test this instantly:

# Verify sudo resolves to your checkout

sudo which omarchy-launch

# Output: /home/<user>/omarchy/bin/omarchy-launch (not /usr/bin/omarchy-launch)

Usage Examples

Link a local checkout with automatic reboot:

omarchy dev link ~/omarchy

Link without reboot prompt (useful for scripting):

omarchy dev link ~/omarchy --no-reboot

Force reconfiguration after pulling upstream changes:

omarchy dev link ~/omarchy --force

Key Implementation Files

Path	Role in sudo access
bin/omarchy-dev-link	Generates and installs sudoers snippet; writes /etc/omarchy.conf
/etc/sudoers.d/omarchy-dev-path	Runtime sudoers override modifying secure_path for omarchy-* commands
/etc/omarchy.conf	Persists OMARCHY_PATH across reboots for non-sudo components
bin/omarchy-system-reboot	Handles reboot confirmation when --no-reboot is omitted

Security Design

The omarchy-dev-link approach follows principle of least privilege: it modifies secure_path only for Omarchy-prefixed commands rather than globally expanding sudo's search path. This confines the development environment's influence while permitting full functionality.

Summary

• Snippet generation: omarchy-dev-link builds a secure_path override targeting your checkout's bin directory
• Validation: visudo -cf guarantees syntactic correctness before any system modification
• Installation: Validated rules deploy to /etc/sudoers.d/omarchy-dev-path with 0440 permissions
• Persistence: /etc/omarchy.conf stores OMARCHY_PATH for reboot-surviving configuration
• Immediate effect: Sudo uses development binaries instantly; other components require reboot

Frequently Asked Questions

What happens if the sudoers validation fails?

The script aborts without modifying system files. You'll see an error message indicating syntax problems in the generated snippet, and no changes are made to /etc/sudoers.d/. Fix any path issues or special characters in your checkout directory, then retry.

Does this affect sudo commands unrelated to Omarchy?

No. The secure_path modification applies globally in the sudoers file, but Omarchy's architecture uses prefixed command names (omarchy-launch, omarchy-install, etc.). Standard system utilities continue resolving from their original paths unless explicitly invoked through Omarchy's wrapper scripts.

Why is a reboot needed if sudo works immediately?

The sudoers change affects only privileged command resolution. Non-sudo Omarchy tools—such as user-facing CLI helpers or desktop integration—read OMARCHY_PATH from /etc/omarchy.conf, which is sourced at session startup. A reboot ensures these components also reference the development checkout.

Can multiple checkouts be linked simultaneously?

No. The script overwrites /etc/omarchy.conf and /etc/sudoers.d/omarchy-dev-path on each run. Only one checkout can be active at a time. Switching projects requires re-running omarchy dev link with the new path.

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