# How Omarchy Chooses Between sudo and pkexec for Privileged Commands

> Discover how Omarchy intelligently selects between sudo and pkexec for privileged commands. Learn its logic for interactive vs. graphical sessions.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: deep-dive
- Published: 2026-09-13

---

**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.

```bash
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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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.