Omarchy Privilege Escalation Model: How `sudo` and `pkexec` Work Together

Omarchy uses sudo for terminal-based password prompts and pkexec for graphical Polkit dialogs when no terminal is available, automatically selecting the appropriate mechanism based on runtime context.

Omarchy implements a context-aware privilege escalation model that balances security with user experience. The system dynamically chooses between sudo and pkexec depending on whether the calling process has an attached terminal, ensuring users always receive an appropriate authentication prompt without breaking background tasks or UI workflows.

How Omarchy Decides Between sudo and pkexec

The escalation logic in Omarchy follows a simple terminal-detection rule:

Context	Mechanism	Authentication Method
Terminal attached (-t 1 returns true)	sudo	Password prompt on terminal
No terminal available (background jobs, UI triggers)	pkexec	Graphical Polkit dialog

This model originates from the privileged-command specification in default/agents/skills/omarchy/SKILL.md. According to the source code at line 53, privileged commands must follow these escalation rules: use sudo when a terminal exists for password entry, pkexec when it does not.

The top-level AGENTS.md at lines 68-70 references this specification as the canonical guidance for all Omarchy agent implementations.

When to Use pkexec in Omarchy

Omarchy restricts pkexec to specific non-terminal scenarios. The guidelines at lines 91-93 state:

Use pkexec only when the caller cannot interact with a terminal or cannot run a background process. Do not replace sudo with pkexec merely because a command is "non-interactive".

This prevents unnecessary graphical prompts in terminal environments where sudo provides a cleaner experience.

Code Examples from the Omarchy Source

Terminal-Detected Escalation Pattern

# Pattern used across Omarchy scripts for automatic mechanism selection

if [[ -t 1 ]]; then      # terminal attached

    exec sudo "$@"
else
    exec pkexec "$@"
fi

This pattern appears in multiple Omarchy utilities and ensures consistent behavior regardless of how a command is invoked.

Terminal-Based Installation (sudo)

# From Omarchy command wrappers: terminal available, use sudo

omarchy-cmd-missing some-tool && sudo apt-get install some-tool

Background Process Escalation (pkexec)

# From bin/omarchy-update-stay-awake: no terminal, use pkexec

omarchy-update-stay-awake \
    # …internal logic…

    inhibit_runner=(pkexec)   # pkexec chosen for non-tty context

The bin/omarchy-update-stay-awake script explicitly sets inhibit_runner=(pkexec) because it runs from UI contexts without terminal access.

Self-Re-escalation Pattern

bin/omarchy-dns demonstrates another pkexec use case: when the script detects it lacks sufficient privileges, it re-executes itself via pkexec to present a graphical authentication dialog.

Key Implementation Files

• default/agents/skills/omarchy/SKILL.md — Complete privilege escalation specification with decision rules and constraints
• AGENTS.md — Top-level agent documentation referencing escalation guidelines
• test/shell.d/polkit-test.sh — Test suite verifying pkexec behavior without terminal
• bin/omarchy-update-stay-awake — Background service using pkexec for inhibition tasks
• bin/omarchy-dns — Network utility with self-re-escalation via pkexec

Summary

• Omarchy's privilege escalation model selects sudo or pkexec based on terminal availability, not command type
• sudo handles interactive terminal sessions with direct password prompts
• pkexec provides graphical authentication for background processes and UI-triggered actions
• The [[ -t 1 ]] test is the canonical detection mechanism used across Omarchy utilities
• Guidelines in SKILL.md explicitly prohibit replacing sudo with pkexec for convenience in terminal contexts

Frequently Asked Questions

How does Omarchy detect whether to use sudo or pkexec?

Omarchy checks if file descriptor 1 (stdout) is attached to a terminal using the bash test [[ -t 1 ]]. When true, sudo provides a terminal password prompt. When false, pkexec displays a graphical Polkit dialog instead of blocking or failing silently.

Can I force pkexec in a terminal for Omarchy commands?

No. The Omarchy guidelines at SKILL.md lines 91-93 explicitly advise against replacing sudo with pkexec merely because a command is non-interactive. Use pkexec only when the caller genuinely cannot access a terminal or run as a background process.

Where is Omarchy's privilege escalation model documented?

The canonical specification lives in default/agents/skills/omarchy/SKILL.md with the terminal-detection rule at line 53 and pkexec restrictions at lines 91-93. The top-level AGENTS.md references this at lines 68-70 as the standard for all agent development.

What tests verify Omarchy's pkexec behavior?

The file test/shell.d/polkit-test.sh contains test cases that verify pkexec functions correctly when no terminal is available, ensuring the escalation model behaves as specified in non-tty environments.

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