Omahub
← All plugins
B

Wallpaper Engine for Omarchy

by brussell

Steam Wallpaper Engine backgrounds on Omarchy/Hyprland with per-display controls, reversible wallpaper-matched themes, Workshop browse, and theme restore.

GitHub

Security review

Potentially dangerous behavior detected · 18 findings

Deterministic scan — not a security guarantee

High
Risk level
High
Analyzed commit
729d400
Scanned
1 week ago
  • high persistence tests/test-backend.sh:206

    Registers scheduled or boot-time system tasks.

    systemd-run" <<'EOF'
  • high persistence tests/test-backend.sh:222

    Registers scheduled or boot-time system tasks.

    systemd-run" "$stub_bin/hyprctl" "$apply_stub"
  • high persistence tests/test-backend.sh:243

    Registers scheduled or boot-time system tasks.

    systemd-run stub records argv and starts the payload, like --user without --wait.
  • high persistence tests/test-backend.sh:257

    Registers scheduled or boot-time system tasks.

    systemd-run" <<'EOF'
  • high persistence tests/test-backend.sh:319

    Registers scheduled or boot-time system tasks.

    systemd-run" "$stub_bin/hyprctl" "$apply_stub"
  • high persistence tests/test-backend.sh:328

    Registers scheduled or boot-time system tasks.

    systemd-run post-boot hook blocked for ${elapsed}ms"
  • high persistence tests/test-backend.sh:330

    Registers scheduled or boot-time system tasks.

    systemd-run'
  • high persistence tests/test-backend.sh:331

    Registers scheduled or boot-time system tasks.

    systemd-run was not invoked with --user'
  • high persistence tests/test-backend.sh:332

    Registers scheduled or boot-time system tasks.

    systemd-run was not invoked with --collect'
  • high persistence tests/test-backend.sh:334

    Registers scheduled or boot-time system tasks.

    systemd-run was not invoked with KillMode=process'
  • high persistence tests/test-backend.sh:336

    Registers scheduled or boot-time system tasks.

    systemd-run still used KillMode=control-group'
  • high persistence tests/test-backend.sh:339

    Registers scheduled or boot-time system tasks.

    systemd-run --wait would keep the hook blocked on apply'
  • high persistence tests/test-backend.sh:346

    Registers scheduled or boot-time system tasks.

    systemd-run post-boot restore did not complete'
  • high persistence tests/test-backend.sh:349

    Registers scheduled or boot-time system tasks.

    systemd-run post-boot restore output was not logged'
  • high persistence hooks/post-boot.sh:68

    Registers scheduled or boot-time system tasks.

    systemd-run >/dev/null 2>&1 \
  • high persistence hooks/post-boot.sh:69

    Registers scheduled or boot-time system tasks.

    systemd-run --user --collect --quiet --unit="$unit" \
  • high persistence hooks/monitor-watch.sh:93

    Registers scheduled or boot-time system tasks.

    systemd-run >/dev/null 2>&1; then
  • high persistence hooks/monitor-watch.sh:95

    Registers scheduled or boot-time system tasks.

    systemd-run --user --quiet --unit="$WE_MONITOR_WATCH_UNIT" \

Automated analysis only — not a security guarantee.

AI advisory review

No obvious issues detected

Language-model assessment · ~deepseek/deepseek-v4-flash-latest — advisory only

Low
AI risk level
Low
Recommendation
install
Model
~deepseek/deepseek-v4-flash-latest
Analyzed commit
729d400
Reviewed
1 week ago

The plugin is a legitimate Wallpaper Engine integration for Omarchy/Hyprland. The deterministic scan flagged systemd-run usage as persistence, but that is for transient user units that detach boot-restore and monitor-watch processes, which is expected functionality, not malicious persistence. The code is well-structured, validates inputs, and only modifies plugin-owned files under ~/.config/omarchy and ~/.local/state.

  • The deterministic scan flagged systemd-run in hooks and tests as persistence; this is benign and used to detach legitimate background tasks (post-boot wallpaper restore, monitor hotplug watcher).
  • The plugin installs hooks into ~/.config/omarchy/hooks and creates a monitor-watch process; these are documented and reversible via uninstall.sh.
  • The install script copies the plugin tree and swaps it atomically; it does not execute arbitrary code beyond its own validated scripts.
How this check works

This review combines the deterministic scan (the rule-based results above) with an independent look at the plugin's code by a language model. The model reads a trimmed sample of the repository's files, the manifest, and the README, then gives a plain-language risk level and a recommendation: install (no notable danger), review (look closer first), or avoid (clearly dangerous).

It runs on the same analyzed commit as the deterministic scan and is strictly advisory — it is not a security guarantee and never blocks a plugin by itself. A human moderator still reviews plugins before they are listed.

AI advisory only — automated analysis, not a security guarantee.

Install
$ omarchy plugin add https://github.com/14brussell/Wallpaper-Engine-Omarchy --enable
Appearance #Hyprland #quickshell #media

Wallpaper Engine for Omarchy

<p align="center"> <img src="preview.png" alt="Wallpaper Engine for Omarchy interface" width="100%"> </p>

Omarchy / Hyprland / Quickshell plugin that plays Steam Wallpaper Engine Workshop items through Almamu/linux-wallpaperengine. Per-display panel and optional bar widget, Style menu entries, gum TUI, boot/theme hooks. Hyprland + Omarchy only.

https://github.com/user-attachments/assets/8a745361-9db8-40a0-b371-2725e26a6d5e

Requirements

omarchy pkg aur add linux-wallpaperengine-git
  • Steam + Wallpaper Engine Workshop items with project.json (scene, video, or web). Steam does not need to be running.
omarchy install gaming steam

Optional:

  • python-pillow — auto-match theme only (ImageMagick can still compose stills). Not needed to apply a wallpaper.
omarchy pkg add python-pillow

Paths: plugins, config, hooks, and themes live under ~/.config/omarchy. Runtime state is ~/.local/state/omarchy. XDG_CONFIG_HOME / XDG_STATE_HOME are ignored. Install as a real directory named io.github.14brussell.wallpaper-engine. Do not symlink a mixed-case checkout (QML rejects the path).

Layer: leave omarchy.background enabled. The engine is forced to --layer bottom.

Overlays: Hyprland fades fullscreen Quickshell surfaces (volume OSD, notification toasts) by default. While Wallpaper Engine is running it also damages the whole screen every frame, so that fade makes shell previews hitch. The plugin disables compositor animation on linux-wallpaperengine, omarchy-osd, and omarchy-notifications, and starts the engine with EGL vsync off (vblank_mode=0, __GL_SYNC_TO_VBLANK=0) so the compositor can draw those overlays on time. Keep FPS modest (default 30); very high FPS still costs GPU time under the OSD.

install.sh ends with omarchy-we doctor || true. A missing engine is a broken setup. python-pillow may show missing and still be optional.

Install

omarchy plugin add https://github.com/14brussell/Wallpaper-Engine-Omarchy.git --enable
~/.config/omarchy/plugins/io.github.14brussell.wallpaper-engine/scripts/install.sh

Update

Omarchy's plugin add/update commands never invoke install.sh; run it after updating to complete setup and reload the plugin.

omarchy plugin update io.github.14brussell.wallpaper-engine
~/.config/omarchy/plugins/io.github.14brussell.wallpaper-engine/scripts/install.sh

Copy installs with no .git cannot use plugin update. This is a one-time reinstall (config in ~/.config/omarchy/wallpaper-engine/ is kept). Never --purge for an update.

omarchy plugin remove io.github.14brussell.wallpaper-engine
omarchy plugin add https://github.com/14brussell/Wallpaper-Engine-Omarchy.git --enable
~/.config/omarchy/plugins/io.github.14brussell.wallpaper-engine/scripts/install.sh

Remove

Run uninstall.sh before omarchy plugin remove (while the plugin files still exist):

~/.config/omarchy/plugins/io.github.14brussell.wallpaper-engine/scripts/uninstall.sh
omarchy plugin remove io.github.14brussell.wallpaper-engine

Default: restore theme background, remove plugin-owned hooks/menu/CLI links. Keeps ~/.config/omarchy/wallpaper-engine/ and ~/.local/state/omarchy/wallpaper-engine/. Does not delete the plugin tree (that is plugin remove), Steam, Workshop content, or linux-wallpaperengine.

--purge also deletes that config, state, and the generated wallpaper-engine-auto-match theme (ownership marker required). Irreversible. Never --purge to update.

~/.config/omarchy/plugins/io.github.14brussell.wallpaper-engine/scripts/uninstall.sh --purge
omarchy plugin remove io.github.14brussell.wallpaper-engine

Usage

  • Style → Wallpaper Engine — panel
  • Style → Revert to theme background — stop engines, restore theme
  • Style → Wallpaper Engine (advanced TUI) — gum TUI (omarchy-we with no args is the same; needs a TTY)
  • Bar widget: left-click toggles the panel, middle-click TUI, right-click revert

omarchy-we panel · omarchy-we menu · omarchy-we doctor

Panel

One tab per live Hyprland output. Pick a wallpaper, set scaling/FPS/clamp/audio/properties, Save & apply. Per-tab Start / Stop. Clear & stop drops that display’s saved config. Folder button adds extra Workshop libraries (Steam library, steamapps, or workshop/content/431960). Catalog and search stay cached across tabs.

Auto-match theme needs a live plugin-owned engine and a successfully applied source frame. Writes only ~/.config/omarchy/themes/wallpaper-engine-auto-match. Button becomes Undo theme match. Last engine stop with auto-match on restores the previous theme. CLI: omarchy-we auto-theme [monitor] / omarchy-we undo-auto-theme.

Replacement waits for a complete rendered frame, then stops the old process. Video startup screenshots can be black at high FPS because decoding is asynchronous; in that case, replacement waits for libmpv video output and one second of continuous display-layer ownership by the new process. The requested FPS is preserved. A black startup snapshot is excluded from auto-match, which extracts a video frame instead. Failed start keeps the previous wallpaper. Scene crash before first frame: one retry with particles disabled.

Fullscreen startup: Apply can complete as started-paused when fullscreen pausing is enabled, a matching fullscreen app exists, and the replacement process continuously owns its display surface for a startup grace period. The panel reports the pause; rendering and the deferred screenshot resume when the fullscreen policy allows. Missing frames without those checks still fail. Diagnostic transition messages are retained in transition.log, not displayed as errors.

CLI

omarchy-we                  # menu (TUI; needs a TTY)
omarchy-we panel
omarchy-we doctor
omarchy-we apply [monitor…] # no names: live configured heads only
omarchy-we stop [monitor…]  # no names: all plugin engines
omarchy-we revert
omarchy-we auto-theme [monitor]
omarchy-we undo-auto-theme
omarchy-we set-wallpaper-dirs <path>…

apply / stop take one or more monitors. Disconnected or lid-disabled outputs are skipped. omarchy-we properties <id> and omarchy-we set-property <monitor> <name> <value> for wallpaper-specific keys.

Hooks and files

install.sh already installs these wrappers (they exec current plugin sources):

  • ~/.config/omarchy/hooks/post-boot.d/50-wallpaper-engine — if active=true, restore saved wallpapers; --ensures monitor-watch
  • ~/.config/omarchy/hooks/theme-set.d/50-wallpaper-engine — remember the real theme background for revert; does not tear down a live wallpaper

monitor-watch is not a third Omarchy hook. Post-boot starts it. It listens for Hyprland monitoraddedv2 / monitorremovedv2 and runs omarchy-we sync-outputs. Newly added outputs must remain stable for three seconds before their renderer starts, avoiding transient dock/profile layouts. It does not reconcile on configreloaded (that was tearing down live engines). Does not replace Omarchy’s clamshell watcher.

  • Config: ~/.config/omarchy/wallpaper-engine/config.json
  • State / logs: ~/.local/state/omarchy/wallpaper-engine/

Set "nvidia_workaround": true to also run the engine with __GL_THREADED_OPTIMIZATIONS=0. EGL vsync is already disabled for compositor overlay latency.

Limitations

  • No general mirror/flip (linux-wallpaperengine); wallpaper-specific flip properties still appear when present.
  • Playback speed, audio-reactive, and mouse features depend on the wallpaper and the engine.
  • Some Workshop items crash or fail to render in linux-wallpaperengine (Scene/particles/3D/scripts/Web). Those are upstream compatibility issues; this plugin starts and manages the process only.