How Omarchy Chooses Between sudo and pkexec for Privileged Commands

Omarchy uses a require_root helper function that detects the presence of a controlling terminal and the SUDO_LOG environment variable to select sudo for interactive shells, falling back to pkexec for graphical sessions without a terminal.

Privileged operations in the omacom/omarchy repository rely on a centralized decision-making function to determine the appropriate privilege escalation method. When a command requires root access, Omarchy dynamically chooses between sudo and pkexec based on the execution context rather than hardcoding either tool. This ensures seamless operation across both terminal-based workflows and graphical desktop environments.

The require_root Privilege Escalation Logic

The core selection mechanism resides in the require_root function implemented across Omarchy's command scripts. This function evaluates the runtime environment to decide whether the current session can safely prompt for passwords via terminal input or requires a graphical Polkit dialog.

Terminal Detection and the SUDO_LOG Environment Variable

When require_root is invoked, it first checks for a controlling terminal using the test [[ -t 0 ]]. If a terminal is detected and the SUDO_LOG environment variable is set, the function executes the command with sudo. This approach leverages existing passwordless sudo configurations or cached credentials available in interactive shell sessions.

The logic ensures that terminal-based operations avoid the overhead of spawning graphical authentication dialogs when unnecessary.

Graphical Session Fallback to pkexec

If the controlling terminal check fails—indicating the command runs from a graphical session or background process—the function falls back to pkexec. This invokes the Polkit authentication framework, presenting a native GUI dialog for password entry. After successful authentication, Omarchy sets a PKEXEC_MARKER environment variable to signal that subsequent privileged calls in the process tree should recognize the Polkit context.

require_root() {
    [[ -t 0 ]] && exec sudo "$@"
    exec pkexec "$@"
}

Implementation in Core Omarchy Scripts

The require_root abstraction appears in multiple executable scripts within the bin/ directory, ensuring consistent privilege handling regardless of the specific administrative task.

DNS Configuration with bin/omarchy-dns

The DNS management script uses require_root before modifying system resolver settings. When executed from a terminal with SUDO_LOG present, it escalates via sudo; otherwise, it triggers pkexec for GUI-based network configuration.

Browser Policy Updates with bin/omarchy-theme-set-browser-policy

This script demonstrates the non-terminal use case. When invoked from the Quickshell menu or other GUI launchers without a controlling TTY, the function automatically selects pkexec to elevate privileges for updating browser policies, ensuring the user receives a graphical authentication prompt.

Security Validation and Testing

Beyond the selection logic, Omarchy implements safety checks to prevent privilege escalation attacks through path manipulation or symlink hijacking.

Canonical Binary Verification

Before executing either sudo or pkexec, the require_root function validates that the target executable is the canonical binary installed by the package manager, not a user-writable symlink. This verification ensures that privileged commands execute only trusted code from system directories.

The ELEVATORS Test Suite

The test file test/shell.d/privileged-heredoc-test.sh defines an ELEVATORS=(sudo as_root pkexec doas run0) array that validates all supported privilege escalation methods. This comprehensive testing ensures that the selection logic correctly handles various elevation tools across different system configurations, confirming that sudo and pkexec function as expected within the Omarchy environment.

Summary

• Omarchy centralizes privilege escalation decisions in the require_root function found in scripts like bin/omarchy-dns and bin/omarchy-theme-set-browser-policy.
• The function checks for a controlling terminal ([[ -t 0 ]]) and the SUDO_LOG environment variable to prefer sudo in interactive sessions.
• Graphical or non-terminal sessions automatically fall back to pkexec, with a PKEXEC_MARKER flag tracking the Polkit context.
• Safety mechanisms verify that only canonical system binaries receive elevated privileges, preventing execution of tampered scripts.
• The ELEVATORS array in test/shell.d/privileged-heredoc-test.sh provides regression testing for all supported elevation methods.

Frequently Asked Questions

What triggers Omarchy to use pkexec instead of sudo?

Omarchy uses pkexec when the require_root function detects no controlling terminal (TTY) available for the process. This typically occurs when commands launch from graphical menus or desktop shortcuts. If the [[ -t 0 ]] test returns false or the SUDO_LOG variable is unset, the system falls back to Polkit's pkexec to display a graphical authentication dialog.

How does Omarchy ensure sudo is only used in appropriate contexts?

The function specifically checks for the SUDO_LOG environment variable alongside terminal detection. This requirement ensures that sudo invocations occur only within sessions where sudo logging is explicitly enabled or where the user has already authenticated through a terminal session, preventing silent failures in non-interactive contexts.

Can administrators configure which privilege elevator Omarchy uses?

While the default logic automatically selects between sudo and pkexec based on the runtime environment, the underlying scripts respect system-wide policies. Administrators can influence the behavior by configuring sudoers rules or Polkit policies, though the require_root function itself prioritizes sudo when [[ -t 0 ]] and SUDO_LOG conditions are met, and otherwise defaults to pkexec.

Why does Omarchy set a PKEXEC_MARKER when using Polkit?

The PKEXEC_MARKER environment variable serves as a state indicator for subsequent processes in the execution chain. By setting this marker after a successful pkexec authentication, Omarchy scripts can detect that the current context originated from a Polkit escalation, allowing specialized handling or logging specific to graphical privilege elevation sessions.

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