Omarchy Service Architecture: First-Party vs Third-Party Service Isolation

Omarchy isolates third-party services from authentication components by running all plugins inside a single Quickshell process, where built-in services receive full host access while external plugins are restricted to capability-scoped facades.

The Omarchy service architecture centers on a single long-lived Quickshell process (omarchy-shell) that hosts every desktop component as a QML plugin. Plugins declare a specific kind—such as service for headless background tasks or bar-widget for UI elements—and the system applies distinct trust boundaries depending on whether the plugin is distributed with the core system or installed later by the user.

How the Core Architecture Works

At startup, omarchy-shell initializes the PluginRegistry (shell/services/PluginRegistry.qml) that tracks every loaded instance and enforces isolation rules. Plugins are categorized by their declared kind:

• service – Headless singleton with no UI (e.g., battery monitor, night-light)
• bar-widget – UI element placed on the bar
• panel, overlay, menu – Other UI-specific kinds

The architecture treats first-party (built-in) and third-party (user-installed) plugins differently at the host-injection layer.

First-Party Services

First-party services are built into the Omarchy distribution and receive unrestricted access to the shell's internals.

They are loaded at startup automatically when the shell launches, ensuring critical background tasks are available immediately. According to the implementation in docs/omarchy-shell.md (lines 40-42), these trusted plugins receive the complete set of injected host objects:

• omarchyPath
• shell
• pluginRegistry
• barWidgetRegistry

This grants them direct access to other services and the ability to interact with privileged authentication components. Because they are part of the core distribution, first-party services are never sandboxed and may freely communicate with sensitive subsystems.

Third-Party Services

External plugins operate under strict capability restrictions to protect system integrity.

Third-party services are loaded on demand, instantiated only when explicitly enabled via Setup › Plugins or the CLI (omarchy-shell enablePlugin). Instead of full host objects, these plugins receive a capability-scoped façade that limits control to their own service lifecycle and configuration queries. As documented in docs/omarchy-shell.md (lines 48-53), ordinary plugins "may look up and control only their own service and lifecycle."

Authentication-related services remain outside the public service map and QML object tree. Third-party facades cannot reach these components, preventing accidental or malicious interference with system credentials.

Managing Services via IPC

CLI tools communicate with the running shell through IPC methods exposed by omarchy-shell. The binary (bin/omarchy-shell) forwards commands to start, stop, or query services using the plugin registry.

List all discovered service-type plugins:

omarchy-shell listPlugins | jq '.[] | select(.kinds | contains(["service"]))'

Enable a third-party service:

omarchy-shell enablePlugin myorg.weather '{"enabled":true}'

Call a method on a first-party service:

omarchy-shell call omarchy.battery getStatus

Other lifecycle commands include setPluginEnabled, rescanPlugins, and direct method invocation via the call interface, as specified in docs/omarchy-shell.md (lines 99-107).

Summary

• Omarchy runs all plugins inside a single Quickshell process (omarchy-shell) that distinguishes trust levels at runtime using shell/services/PluginRegistry.qml.
• First-party services start automatically with full access to host objects (omarchyPath, shell, pluginRegistry, barWidgetRegistry) and authentication services.
• Third-party services load on-demand and receive capability-scoped facades that restrict access to their own configuration and lifecycle, preventing access to the authentication layer.
• The bin/omarchy-shell CLI communicates via IPC to manage plugin state with commands like enablePlugin, setPluginEnabled, and call.

Frequently Asked Questions

Can third-party services access the battery or night-light status?

No. Third-party facades cannot look up or interact with first-party services like omarchy.battery or omarchy.nightlight. The PluginRegistry blocks cross-service queries for external plugins, limiting them to their own instance and configuration.

How do I convert a third-party service back to a first-party one?

You cannot promote a third-party plugin to first-party status at runtime. First-party services must be built into the core distribution under shell/plugins/ (documented in shell/plugins/README.md) and are identified by their presence in the trusted manifest at build time.

What happens if a third-party service crashes?

Because third-party services run as isolated QML components with restricted facades, failures are contained to that specific plugin instance. The shell process (omarchy-shell) remains stable, and you can restart the service via omarchy-shell enablePlugin <id> '{"enabled":false}' followed by re-enabling it.

Where are authentication services located to keep them hidden from third-party code?

Authentication services reside outside the public service map maintained by PluginRegistry. They are not published in the QML object tree accessible to third-party facades, ensuring that only built-in, startup-loaded services can access credential management components.

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