omarchy plugin add clones upstream HEAD with no pin

What the two commands actually do

Checked against the v4.0.4 source tree, omarchy plugin add and omarchy theme install both end in a plain git clone of whatever the repository’s default branch points at at that moment.

bin/omarchy-plugin-add does this, in order:

1. Runs omarchy-git-url-check on the URL. That helper refuses a helper::address form and any scheme:// that git does not connect itself, so a URL cannot name ext:: and run a shell command at clone time. It landed in 4.0.1. It is a check on the URL, not on the code.
2. Prints a warning that plugins run as arbitrary, unsandboxed code inside your long-lived shell process, shows the URL, and asks you to confirm.
3. Runs git clone -- "$url" "$stage" into a staging directory under ~/.config/omarchy/plugins/.
4. Runs omarchy-plugin-validate on the staged folder.
5. Refuses if another plugin already claims that id, moves the folder to ~/.config/omarchy/plugins/<id>/, and asks whether to enable it.

There is no --rev, no branch or tag argument, no checksum, and no signature anywhere in that path. The command accepts a URL, --enable and --yes. Issue #11375 makes the same point from the other direction while reporting a website bug: omarchy-plugin-add always requires a git URL and has no code path for a bare plugin id.

bin/omarchy-theme-install has the same shape. It runs the same URL check, derives a theme name from the repository path and holds it to a safe character set, deletes any existing directory of that name, then git clone -- "$REPO_URL" "$THEME_PATH".

Updates differ between the two:

• omarchy plugin update fetches origin HEAD, shows you the full diff before applying it, asks you to confirm, fast-forwards, revalidates, and resets back with git reset --hard ORIG_HEAD if the new revision fails validation. That review step is the strongest control in the whole flow, and it disappears if you pass --yes.
• omarchy theme update runs git -C "$theme" pull for every user-installed theme. No diff, no prompt.

It matters what omarchy-plugin-validate is and is not. It checks schemaVersion, required manifest fields, an id outside the reserved omarchy. namespace, entry points that are safe relative paths and exist, an entry point for every declared kind, and no symlinks inside the folder. It is a manifest check. It reads none of the QML that will run inside your shell.

Omarchy’s own marketplace says the same thing

The community marketplace at plugins.omarchy.org, repo omacom/omarchy-plugin-marketplace, publishes a security notice in its README. It says upstream code may change after review unless the installed version is pinned to the reviewed commit, and then states plainly that the current install and update commands “clone mutable upstream HEAD and are not verification-bound”.

The gap is measurable. The marketplace catalog records both listingValidatedCommit, the commit its baseline scan actually read, and upstreamObservedCommit, what the default branch points at now. In the catalog generated on 2026-09-16 there were 2,921 listings with a working install command, and 771 of them, about one in four, had moved past the commit that was reviewed. The catalog marks every one of those 771 as unverified. Copy the install line from one of their listing pages and you get the current HEAD, not the commit the scan read.

There is a second irony worth knowing. The marketplace’s own Automated Security Baseline flags remote-git-execution-unpinned inside a submitted plugin: code pulled from an external git repository and run without being bound to a full commit. Omarchy’s install command is that pattern, applied to the plugin itself.

Pin it yourself

Nothing here needs new tooling. Use the clone as a staging area and do the review before the code ever runs.

1. Clone somewhere harmless and read it. Plugins are QML plus a manifest, so this is usually a short read.

git clone https://github.com/acme/omarchy-weather.git /tmp/omarchy-weather
cd /tmp/omarchy-weather
git log --oneline -10

2. If the plugin is listed on the marketplace, get the commit its scan actually read.

curl -s https://plugins.omarchy.org/catalog.json |
  jq -r '.plugins[]
         | select(.repo == "https://github.com/acme/omarchy-weather")
         | [.verificationStatus, .listingValidatedCommit, .upstreamObservedCommit]
         | @tsv'

3. Check out the commit you reviewed, or the one the scan reviewed, as a full 40 character SHA.

git -C /tmp/omarchy-weather checkout <full-sha>

4. Validate it and move it into place under its own manifest id, then enable it as a separate step.

id=$(jq -r .id /tmp/omarchy-weather/manifest.json)
omarchy plugin validate /tmp/omarchy-weather
mv /tmp/omarchy-weather ~/.config/omarchy/plugins/"$id"
omarchy-shell shell rescanPlugins
omarchy plugin enable "$id"

The directory name has to match the manifest id, because omarchy plugin update and omarchy plugin remove address plugins by id.

If you would rather stay on the supported path, run omarchy plugin add <url> without --enable, answer no when it offers to turn the plugin on, read the checkout in ~/.config/omarchy/plugins/<id>/, then git checkout the commit you want and enable it. You still clone HEAD, but nothing has run yet.

For themes, clone and check out the same way into ~/.config/omarchy/themes/<name>/, then run omarchy theme set <name>. Remember that omarchy theme update will pull every user theme forward without asking, so skip it if you are pinning.

Verify the pin held

git -C ~/.config/omarchy/plugins/<id> rev-parse HEAD
git -C ~/.config/omarchy/plugins/<id> status --short --branch
omarchy plugin list

The first command should print the SHA you chose. The second should report a detached HEAD, which is what a pin looks like. omarchy plugin list should show the plugin with its id and enabled state.

Why it works this way

Git URLs are the whole distribution mechanism today. The manual says as much: publish a public repo and anyone can run omarchy plugin add against your URL. Nothing else existed when the Quattro shell shipped in 4.0.0 on 2026-08-14, and theme installs worked the same way on 3.x, back when omarchy-theme-install did not even check the URL first.

Omarchy is honest about the consequence rather than hiding it. The install prompt tells you plugins run as arbitrary unsandboxed code, the manual repeats it, and the manual tells you to read the code before you enable anything. What is missing is not the warning. It is any way to record which code you read.

The registry that is coming

omacom/omarchy-plugin-registry is a Rails control plane serving an append-only JSON index and immutable, checksummed tarballs at plugins.omarchy.org. Its client contract specifies a pinned Ed25519 public key, detached signatures on every index file, SHA-256 verification of each tarball, a signed revocation list that fails closed when stale, an install receipt written next to the manifest, and plugins that land disabled so enabling stays a separate consent step. The rollout plan puts git URL installs behind an --unsafe flag.

None of that is shipped. The registry README lists the Omarchy-side client, signature and freshness verification, receipts, the kill-bit check and deployment as not yet done and required before launch. There is no plugin registry code in the 4.0.4 bin/ tree. Treat the registry as a design you can read, not a protection you have.

What to watch for on newer versions

The next announced release is Quattro RS 4.5. If a registry client lands, the signal is a bin/ script that talks to plugins.omarchy.org and an omarchy plugin add publisher/name form that takes no URL. Until then, check omarchy plugin add --help after any update: while it still prints [git-url], nothing has changed. Behaviour has been identical across 4.0.1, 4.0.2, 4.0.3 and 4.0.4.

Related

• Plugins run unsandboxed
• Is Omarchy safe
• Omarchy manual: Shell Plugins