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

> Understand Omarchy service architecture. Learn how Omarchy isolates third-party services from built-in ones using Quickshell for enhanced security and control.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: architecture
- Published: 2026-09-10

---

**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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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:

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

```

Enable a third-party service:

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

```

Call a method on a first-party service:

```bash
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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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.