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

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 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:

• 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: 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: 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:

# 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:

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

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