# Omarchy Privilege Escalation Pattern: How SKILL.md Chooses sudo vs pkexec

> Discover how Omarchy's SKILL.md chooses between sudo and pkexec for privilege escalation. Learn its automatic selection for interactive vs non-interactive environments.

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

---

**Omarchy's privilege escalation pattern automatically selects `sudo` when running in an interactive terminal (TTY) and falls back to `pkexec` for non-interactive contexts where no terminal is attached.**

The `omacom/omarchy` repository defines a deterministic privilege escalation strategy in [`default/agents/skills/omarchy/SKILL.md`](https://github.com/omacom/omarchy/blob/main/default/agents/skills/omarchy/SKILL.md) that determines whether to elevate permissions using `sudo` or `pkexec` based solely on terminal availability. This approach ensures secure authentication across both command-line sessions and graphical desktop environments.

## The Core Decision Logic

The privilege escalation pattern hinges on a single environmental check: the presence of an interactive terminal.

When a command executes within a visible, interactive terminal (standard TTY), **Omarchy prepends `sudo`** to privileged commands. This allows the terminal to display native password prompts and capture user input directly.

When a command runs without a controlling terminal—such as from background processes, systemd services, or graphical launchers—**Omarchy invokes `pkexec`**. This triggers PolicyKit's graphical authentication dialog, which operates independently of TTY access.

According to the source code analysis, this logic is implemented by checking terminal attachment using standard shell tests like `[ -t 1 ]` or inspecting the `$TERM` environment variable.

## Implementation in SKILL.md

The authoritative rules are documented in specific sections of [`default/agents/skills/omarchy/SKILL.md`](https://github.com/omacom/omarchy/blob/main/default/agents/skills/omarchy/SKILL.md):

- **Line 53 (Privilege Escalation)**: Establishes the foundational rule: "`sudo` when a terminal is available for the password prompt, `pkexec` when it is not."

- **Lines 86-87 (Interactive Use)**: Specifies that for interactive scripts or commands run in visible terminals, the system uses `sudo` for privileged work.

- **Lines 92-93 (Background Use)**: Contains a critical warning: "Background processes may be granted password-less `sudo` access via policy; do **not** replace `sudo` with `pkexec` merely because a process is backgrounded."

This distinction matters because blindly switching to `pkexec` for background processes could break automated workflows that rely on password-less `sudo` policies configured for specific service accounts.

## Helper Functions and Hooks

The logic is implemented across multiple files within the skill directory:

- **[`default/agents/skills/omarchy/hooks.md`](https://github.com/omacom/omarchy/blob/main/default/agents/skills/omarchy/hooks.md)**: Contains helper functions that perform the terminal detection checks and route commands to either `sudo` or `pkexec` based on the TTY state.

- **[`default/agents/skills/omarchy/contributing.md`](https://github.com/omacom/omarchy/blob/main/default/agents/skills/omarchy/contributing.md)**: Documents override flags such as `--no-sudo` that allow developers to bypass the automatic selection and force a specific elevation method when necessary.

## Practical Code Examples

The following patterns demonstrate how Omarchy applies this logic in practice:

```bash

# Example 1: Interactive use with TTY present

# Omarchy detects the terminal and prepends sudo automatically

omarchy restart-omarchy-service

# Executes as: sudo systemctl restart omarchy.service

# Example 2: Non-interactive launch from graphical environment

# Omarchy detects no TTY and uses pkexec for graphical authentication

omarchy launch-htop

# Executes as: pkexec htop

```

For scripts that need to detect the terminal state manually before invoking Omarchy commands, use standard bash checks:

```bash
if [ -t 1 ]; then
    echo "Running with sudo (interactive terminal detected)"
else
    echo "Would require pkexec (no terminal attached)"
fi

```

## Background Processes and Policy Exceptions

The pattern includes specific guidance for background execution contexts. While the default assumption might suggest using `pkexec` for any non-interactive process, the SKILL.md explicitly warns against this replacement.

**Background processes** often operate under restricted environments where graphical PolicyKit dialogs cannot render. Instead, these processes should rely on **password-less `sudo`** configured via `/etc/sudoers` policies. This allows automated maintenance scripts and daemon operations to elevate privileges without human interaction, whereas `pkexec` would hang indefinitely waiting for a graphical authentication prompt that never appears.

## Summary

- **Terminal detection** drives the choice between `sudo` and `pkexec` in Omarchy's privilege escalation pattern.
- **Interactive TTY sessions** use `sudo` to leverage terminal-based password prompts.
- **Non-interactive contexts** use `pkexec` to invoke graphical authentication dialogs via PolicyKit.
- **Background processes** should maintain `sudo` usage, often with password-less policies, rather than switching to `pkexec`.
- **Override flags** like `--no-sudo` exist in [`default/agents/skills/omarchy/contributing.md`](https://github.com/omacom/omarchy/blob/main/default/agents/skills/omarchy/contributing.md) for manual control when automatic detection fails.

## Frequently Asked Questions

### When does Omarchy use sudo instead of pkexec?

Omarchy uses `sudo` whenever it detects an interactive terminal (TTY) attached to the current session. This typically occurs when users run commands manually in visible terminal emulators or SSH sessions where the `[ -t 1 ]` test returns true.

### How does Omarchy detect if a terminal is interactive?

The implementation checks for terminal attachment using standard POSIX shell mechanisms, specifically testing file descriptor 1 with `[ -t 1 ]` or inspecting the `$TERM` environment variable. These checks determine whether a password prompt can be displayed natively in the terminal or if a graphical fallback is required.

### Can I force pkexec even when running in a terminal?

Yes, the framework provides override mechanisms documented in [`default/agents/skills/omarchy/contributing.md`](https://github.com/omacom/omarchy/blob/main/default/agents/skills/omarchy/contributing.md). You can use flags such as `--no-sudo` to bypass the automatic TTY detection and force the use of `pkexec` regardless of terminal availability.

### Why does the pattern warn against replacing sudo with pkexec for background processes?

Background processes often lack access to graphical display servers required by PolicyKit authentication dialogs. Replacing `sudo` with `pkexec` in these contexts would cause the process to hang indefinitely waiting for user interaction. Instead, background services should use `sudo` with properly configured password-less policies in `/etc/sudoers`.