Know that a shell plugin runs unsandboxed with your full account access, not as a config file
Gate 1 holds on the documented-default clause: both quoted sentences are in manual/32-shell-plugins.md at the pinned v4.0.2 sha, line 40, verbatim, and the same warning is printed by omarchy-plugin-add lines 104 to 112 on the installed 4.0.2-1. Gate 2 holds: every mechanism the record states, one process, full account reach, clone path, no code shown at add time, is in the manual or the README, and nothing beyond them was added. Gate 3 holds: the record names no way to abuse a plugin. Checked on 4.0.2-1: shell/plugins/README.md is byte-identical to the pinned tag, omarchy-plugin-add, -update, -remove, -validate and -list do what the record says (validate line 53 reserves omarchy.*, remove lines 87 to 115 delete a git checkout and back up a plain folder, update lines 53 to 65 show the diff and confirm), and shell.qml lines 331, 597 and 676 with PluginRegistry.isEnabled confirm that a disabled third-party plugin's QML is never instantiated, which the fix's read-before-enable advice depends on. Three things were wrong. First, the manual is not installed by the package, so "matching omarchy 4.0.2-1 installed here" was only true of the README. Second, and the one that matters, the record said first- and third-party plugins load with no distinction and that upstream treats the absence of a sandbox as settled. That was true at v4.0.2 and false from v4.0.3 (2026-09-08): commit 1702cf0bee, in the v4.0.3 release notes as "Restrict plugin access to authentication services", adds AuthServiceStore.js and per-plugin API objects, and the manual at v4.0.3 and v4.0.4 says third-party plugins get a limited interface with no direct access to authentication services while still running with everything the user can reach. The cause and fix now state the version boundary. Third, without --enable the add command asks whether to enable now, so "leaving off --enable" is not enough on its own, and the cause's "nothing re-confirms it later" ignored the diff-and-confirm step in update, both now fixed. Severity lowered from high to medium against the brief's scale: no default exposes a credential or private data on its own, the exposure needs the user to install third-party code, the add command warns before doing so, and running unsandboxed as the user is the norm for desktop shell extensions rather than weaker than it. High would make every AUR package and curl-pipe-bash install high. Nothing was exercised: no plugin was added, enabled or removed. Re-checked against 4.0.4-1 2026-09-19: Re-checked on omarchy 4.0.4-1 (pacman -Q) against the v4.0.4 tag, commit c668141e9c42b13c80c9ca4ea108e11708c5e8a5, whose shell.qml, PluginRegistry.qml, shell/plugins/README.md and plugin scripts are byte-identical to the installed files. The record's substance holds on 4.0.4: the add warning, the diff-and-confirm update, remove, validate, list and the enable-only-when-listed rule come from omarchy-plugin-* scripts that did not change between v4.0.2 and v4.0.4, and the manual at v4.0.4 still says all plugin code runs with everything the user account can reach. Traced the boundary in code: AuthServiceStore.js keeps the lock and polkit instances out of the public service map and unparented (shell.qml ensureService), a third-party plugin receives a PluginShellApi and PluginRegistryApi facade instead of the host, publicPluginManifest strips the trust fields, and only first-party manifests can declare the authentication capability. Held against the boundary-moved test, it does what it claims and no more: it protects the authentication objects inside the process, and the manual itself says visual plugins can still walk ordinary parent objects and that this is not a sandbox, which the record already says. Two things were wrong. The record credited 4.0.3's change to commit 1702cf0bee, which is on quattro's history but is not an ancestor of the v4.0.3 or v4.0.4 tags. The release carries PR #9618 as a cherry-pick merged through backport PR #10733 (merge cf6fedc9), so the cause now cites the PRs. Second, the claim that updated code runs as soon as the pull lands is no longer true for every plugin: the #9485 backport in 4.0.3 keeps a service with keepLoaded true loaded across a plugin reload (shell.qml unloadPluginServices and _syncServices, lines 974 to 978 and 1033 to 1049), with no first-party check, so such a service runs its new code only after the shell restarts. The cause and fix now say so, and the 4.0.4 manual wording on parent-object reach is quoted. Severity medium and frequency occasional stand. Nothing was exercised: no plugin was added, enabled, updated or removed, and no shell IPC was called.
omarchy plugin remove deletes a git-checked-out plugin outright (the upstream repository is unaffected), so local edits and local commits that were never pushed are lost with it. Only a hand-made plugin folder with no git repo is preserved, moved to a timestamped backup inside the plugins directory. --yes on omarchy plugin add and on omarchy plugin update skips the warning, the diff and the confirmation, so a script that passes it installs and updates code nobody has read.
Symptom
Is it safe to add a shell plugin from GitHub. What can a plugin actually reach once it is enabled, and could a bad one get at passwords, ssh keys, or anything else the desktop session can touch.
Cause
Documented in the Omarchy manual at manual/32-shell-plugins.md in the upstream repository, at the v4.0.2 tag, commit 346e69e1cec6c4e8924531874af6ba010a1bc99e, and at the v4.0.4 tag, commit c668141e9c42b13c80c9ca4ea108e11708c5e8a5, and confirmed by reading shell/plugins/README.md, which the omarchy 4.0.4-1 package installs at /usr/share/omarchy/shell/plugins/README.md byte-identical to the v4.0.4 tag. The manual itself is not installed by the package. The whole Omarchy desktop, not only the bar, runs as plugins inside one long-lived Quickshell process called omarchy-shell: the bar, its panels, the emoji picker, the clipboard manager, the Omarchy menu, the lock screen and the polkit agent that approves privileged actions. A third-party plugin added with omarchy plugin add <url> is cloned into ~/.config/omarchy/plugins/<id>/ and, once enabled, runs as QML inside that same process with everything the user account can reach.
The manual states this at the point where a plugin is added: "Before it does anything, it tells you plainly that plugins run as arbitrary, unsandboxed code inside your long-lived shell process, shows you the URL, and asks you to confirm." And: "A plugin isn't a config file — it's code that runs for as long as your session does, with everything your user account can reach." The warning is printed by omarchy-plugin-add at add time and skipped by --yes. omarchy plugin update shows the diff and asks before a fast-forward pull, also skipped by --yes, but repeats no warning, and the shell reloads a changed plugin directory on its own, so new code runs as soon as the pull lands. From 4.0.3 on there is one exception: a service plugin whose manifest sets keepLoaded: true keeps its running instance across that reload, and its new code starts with the next shell start.
Which version matters here. On 4.0.2 the manual says first-party and third-party plugins are "discovered the same way at startup; the only difference is where they sit on disk". Omarchy 4.0.3, released 2026-09-08, changed that. PR #9618, "Restrict third-party plugin access to authentication services", merged to quattro, and it shipped in 4.0.3 through the backport PR #10733, merge commit cf6fedc9f5a8d73fd2654695703fe5b2f977b4b6, listed in the release notes as "Restrict plugin access to authentication services". It adds shell/services/AuthServiceStore.js, which holds the lock and polkit services outside the shell's public service map with no parent object, and per-plugin API objects, so a third-party plugin is handed a limited interface instead of the trusted shell interfaces. The manual from that release says "The third-party plugin interface does not directly expose authentication services", and also "Visual plugins still share the shell's QML scene and can walk ordinary parent objects, while all plugin code runs with everything your user account can reach." So on 4.0.3 and 4.0.4 the lock and polkit services are kept out of a third-party plugin's reach inside the shell's own object graph, and the rest of this record still holds on every release: the plugin is unsandboxed code running as the user.
Fix
There is no setting that sandboxes a plugin. What can be controlled is which code gets into the process, and when.
Read a plugin's source before enabling it, not only its README. omarchy plugin add <url> shows the clone URL and asks for confirmation, but it does not show the code, and omarchy plugin validate <path> checks the manifest's shape, its entry-point paths and the absence of symlinks, not what the plugin does with the session.
Add without enabling:
omarchy plugin add https://github.com/<owner>/<repo>.git
Without --enable the command clones into ~/.config/omarchy/plugins/<id>/, validates the manifest, and then asks whether to enable the plugin now. Answer no. The shell creates QML components only for plugins it considers enabled, and a third-party plugin is enabled only when its id appears in ~/.config/omarchy/shell.json, so the checkout can be read before omarchy plugin enable <id> runs any of it. Do not pass --yes on a plugin you have not read: it skips the warning as well as the question.
Before accepting omarchy plugin update, read the diff it prints. An update is as consequential as the first install, and the shell reloads the plugin as soon as the fast-forward lands, except a service that sets keepLoaded: true, which runs the new code from the next shell start. omarchy plugin update --yes skips the diff and the question.
Check what is enabled now:
omarchy plugin list
and remove anything that cannot be accounted for with omarchy plugin remove <id>.
The omarchy. id prefix is reserved for first-party plugins, so a third-party plugin cannot claim it, but that only stops a name collision. It says nothing about whether an unreserved id belongs to code worth trusting.
On 4.0.3 and later the shell keeps its authentication services out of a third-party plugin's reach. Update to get that boundary, and treat it as a boundary inside the shell rather than a sandbox: the plugin still runs as your user.
Verify
omarchy plugin list --json
Shows which plugins are actually enabled right now, first-party and third-party together, so the unsandboxed surface being relied on matches what was meant to be installed rather than what is remembered.
Sources
- https://github.com/omacom/omarchy/blob/346e69e1cec6c4e8924531874af6ba010a1bc99e/manual/32-shell-plugins.md
- https://github.com/omacom/omarchy/blob/346e69e1cec6c4e8924531874af6ba010a1bc99e/shell/plugins/README.md
- https://github.com/omacom/omarchy/blob/0534987009061cbe2dacdde4ad564092ab698d12/manual/32-shell-plugins.md
- https://github.com/omacom/omarchy/blob/c668141e9c42b13c80c9ca4ea108e11708c5e8a5/manual/32-shell-plugins.md
- https://github.com/omacom/omarchy/commit/1702cf0bee025aa32eddac391c4f9ac32244cfeb
- https://github.com/omacom/omarchy/commit/094c913065315082c0cbf353a169c0245779c427
- https://github.com/omacom/omarchy/releases/tag/v4.0.3
- https://github.com/omacom/omarchy/blob/c668141e9c42b13c80c9ca4ea108e11708c5e8a5/bin/omarchy-plugin-add
- https://github.com/omacom/omarchy/blob/c668141e9c42b13c80c9ca4ea108e11708c5e8a5/bin/omarchy-plugin-update
- https://github.com/omacom/omarchy/pull/9618
- https://github.com/omacom/omarchy/pull/10733
- https://github.com/omacom/omarchy/blob/c668141e9c42b13c80c9ca4ea108e11708c5e8a5/shell/services/AuthServiceStore.js
- https://github.com/omacom/omarchy/blob/c668141e9c42b13c80c9ca4ea108e11708c5e8a5/shell/shell.qml
- https://github.com/omacom/omarchy/blob/c668141e9c42b13c80c9ca4ea108e11708c5e8a5/shell/plugins/README.md