How Omarchy Privileged Commands Handle Sudo vs Pkexec Escalation

Omarchy selects sudo when a terminal is available for password entry and pkexec when running without a terminal (e.g., UI actions or background tasks) to ensure appropriate privilege escalation without blocking the user interface.

The basecamp/omarchy repository implements a context-aware privilege escalation model that distinguishes between interactive terminal sessions and graphical or background operations. This approach ensures that privileged commands in Omarchy obtain root rights through the most appropriate mechanism for the calling context, maintaining both security and usability across different execution environments.

The Terminal-Based Escalation Model

Omarchy's privilege escalation logic hinges on a single deterministic factor: whether the calling process has a terminal attached (tty). According to the source code in default/agents/skills/omarchy/SKILL.md, the system evaluates the execution context and selects the escalation method accordingly:

• sudo – Used when the caller has a terminal attached, allowing the user to type a password directly into the command line interface.
• pkexec – Used when the caller lacks a terminal (such as background tasks, UI-triggered actions, or scripts launched from menus), triggering a graphical Polkit authentication dialog instead.

This model prevents UI blocking in graphical environments while preserving the standard terminal workflow for command-line operations.

Implementation Guidelines from Source Code

The specific rules governing these choices are documented in the Omarchy agent skills specification and referenced from the top-level AGENTS.md (lines 68-70).

Terminal-Attached Contexts (Sudo)

For commands executed within a terminal session, Omarchy mandates the use of sudo. The documentation at line 53 of default/agents/skills/omarchy/SKILL.md states:

For privileged commands, follow the Privilege Escalation rules below: sudo when a terminal is available for the password prompt, pkexec when it is not.

This ensures that users receive password prompts in their current terminal window without spawning unnecessary graphical dialogs that might break terminal-based workflows or SSH sessions.

Non-Terminal Contexts (Pkexec)

When the calling context lacks a terminal—such as desktop menu items or automated background scripts—Omarchy requires pkexec to display a graphical authentication dialog. Lines 91-93 of default/agents/skills/omarchy/SKILL.md specify:

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 distinction is critical for background operations that must not hang waiting for terminal input that will never arrive.

Self-Managing Commands

The guidelines explicitly prohibit wrapping commands that already handle their own privilege elevation. Developers should not add sudo or pkexec prefixes to tools that internally manage escalation, as this could cause double-authentication prompts or permission conflicts.

Practical Code Examples

The Omarchy codebase demonstrates this escalation model through several implementation patterns.

Terminal-based installation using sudo:

# Example 1 – a command run from a terminal (uses sudo)

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

Background/UI operation using pkexec:

# Example 2 – a UI menu item that needs root but has no terminal (uses pkexec)

# The Omarchy helper automatically picks pkexec when the menu runs in a non‑tty context.

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

    inhibit_runner=(pkexec)   # <-- pkexec chosen because the caller is a background script

Adaptive script that checks for terminal availability:

# Example 3 – a script that must work both interactively and non‑interactively

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

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

The [[ -t 1 ]] test checks if file descriptor 1 (stdout) is associated with a terminal, providing a runtime determination of which escalation method to invoke.

Key Source Files and Test Coverage

Several files in the basecamp/omarchy repository define and enforce this privilege escalation model:

• default/agents/skills/omarchy/SKILL.md – Contains the complete Privilege Escalation specification (lines 53, 91-93) that agents must follow when generating or executing privileged commands.

• AGENTS.md – Top-level documentation (lines 68-70) that summarizes the escalation rules and points to the detailed SKILL.md specification.

• test/shell.d/polkit-test.sh – Test suite that verifies pkexec usage when a terminal is unavailable, ensuring the escalation logic behaves correctly in non-tty contexts.

• bin/omarchy-update-stay-awake – Production script that selects pkexec for background inhibition tasks where no terminal is present.

• bin/omarchy-dns – Utility script that elevates via pkexec when re-executing itself in contexts lacking terminal access.

Summary

• Omarchy privileged commands use sudo when a terminal is available and pkexec when running without a terminal.
• The decision logic relies on checking terminal attachment (typically via [[ -t 1 ]]) to determine the appropriate escalation mechanism.
• pkexec is reserved specifically for UI-triggered actions and background tasks where terminal interaction is impossible, not merely for non-interactive commands.
• Commands that manage their own privilege elevation should not be wrapped with either sudo or pkexec.
• Implementation rules are enforced through agent specifications in default/agents/skills/omarchy/SKILL.md and verified by the test/shell.d/polkit-test.sh test suite.

Frequently Asked Questions

When should I use pkexec instead of sudo in Omarchy?

Use pkexec only when the caller cannot interact with a terminal or runs as a background process without tty access, such as desktop menu items or automated scripts. According to the Omarchy source code, sudo remains the default for all terminal-attached contexts even if the command itself is non-interactive.

Can I replace sudo with pkexec for non-interactive commands?

No. The Omarchy guidelines explicitly prohibit replacing sudo with pkexec merely because a command is "non-interactive". The determining factor is terminal availability, not interactivity. If a terminal exists, use sudo; reserve pkexec for contexts where terminal input is impossible.

How does Omarchy detect whether a terminal is available?

Omarchy scripts typically use the shell test [[ -t 1 ]] to check if file descriptor 1 (standard output) is attached to a terminal. This runtime check allows scripts to branch between exec sudo "$@" for terminal contexts and exec pkexec "$@" for non-terminal contexts, as demonstrated in the bin/omarchy-dns implementation.

Where are the privilege escalation rules documented?

The primary specification resides in default/agents/skills/omarchy/SKILL.md at lines 53 and 91-93, with a high-level summary referenced in AGENTS.md at lines 68-70. These documents form the authoritative source for how agents and scripts must handle privilege escalation within the Omarchy framework.

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