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

> Explore the Omarchy privilege escalation model. Discover how sudo and pkexec work together for secure terminal and graphical authentication, ensuring seamless access.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: internals
- Published: 2026-08-18

---

**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`](https://github.com/basecamp/omarchy/blob/main/default/agents/skills/omarchy/SKILL.md). According to the source code at [line 53](https://github.com/basecamp/omarchy/blob/quattro/default/agents/skills/omarchy/SKILL.md#L53), 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](https://github.com/basecamp/omarchy/blob/quattro/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](https://github.com/basecamp/omarchy/blob/quattro/default/agents/skills/omarchy/SKILL.md#L91) 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

```bash

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

```bash

# From Omarchy command wrappers: terminal available, use sudo

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

```

### Background Process Escalation (pkexec)

```bash

# 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`](https://github.com/basecamp/omarchy/blob/main/default/agents/skills/omarchy/SKILL.md)** — Complete privilege escalation specification with decision rules and constraints
- **[`AGENTS.md`](https://github.com/basecamp/omarchy/blob/main/AGENTS.md)** — Top-level agent documentation referencing escalation guidelines
- **[`test/shell.d/polkit-test.sh`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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.