Omahub
← All plugins
M

Homelab

by Milind Mishra

Launch app/container endpoints first, with raw system ports collapsed behind a disclosure.

GitHub Homepage

Security review

No obvious issues detected

Deterministic scan — not a security guarantee

None
Risk level
None
Analyzed commit
e8ae44d
Scanned
1 month ago

No potentially dangerous behavior detected in the analyzed commit.

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
e8ae44d
Reviewed
1 month ago

The plugin is a transparent bar widget that lists listening sockets and Docker ports, with user-initiated actions to open, copy, or kill processes. All external commands (ss, docker ps, xdg-open, wl-copy, kill-service) are invoked with the user's permissions and the kill path revalidates PID, start time, command name, and listening socket before sending SIGTERM. No obfuscation, persistence, credential theft, or destructive install behavior was found.

  • The plugin can send SIGTERM to processes, but only after strict validation and only when the user presses 'K' on a selected row.
  • It invokes xdg-open on derived URLs, which could open a malicious endpoint if a service is compromised, but this requires explicit user click.
  • Runs unsandboxed inside omarchy-shell, as documented, but all actions are user-triggered and limited to the current user's permissions.
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/thatbeautifuldream/omarchy-homelab-plugin --enable
Developer Tools #bar #system

Omarchy Homelab Plugin

A compact Omarchy bar widget for local homelab/service discovery.

<img width="2560" height="1600" alt="image" src="https://github.com/user-attachments/assets/172c30b8-0c54-4518-8644-68768face7a1" />

It scans listening TCP/UDP sockets with ss, merges Docker-published ports when Docker is available, and shows app/container endpoints first while keeping raw system ports behind a disclosure.

Features

  • Omarchy bar-widget plugin with a keyboard-friendly popup.
  • App/container endpoints shown before raw system sockets.
  • Docker-published ports merged with matching ss rows.
  • System ports collapsed by default.
  • Stable refresh layout with no stat-card jump.
  • Click/keyboard actions:
    • R: refresh.
    • S: show or hide system ports.
    • K: send SIGTERM to the selected visible app process when safe.
    • Enter: open launchable endpoint, copy otherwise.
    • C: copy selected endpoint.
    • Left click: open/copy row.
    • Right click: copy row.

Install

Omarchy's official plugin contract is a public git repository with manifest.json at the repository root. The installer clones the repo into ~/.config/omarchy/plugins/<id>/; updates are fast-forward pulls of that checkout. See the publishing guide for the marketplace requirements.

Review the code first. Plugins run unsandboxed inside the long-running omarchy-shell process.

omarchy plugin add https://github.com/thatbeautifuldream/omarchy-homelab-plugin.git --enable

Non-interactive install:

omarchy plugin add https://github.com/thatbeautifuldream/omarchy-homelab-plugin.git --enable --yes

Update:

omarchy plugin update thatbeautifuldream.homelab

Non-interactive update:

omarchy plugin update thatbeautifuldream.homelab --yes

Remove:

omarchy plugin remove thatbeautifuldream.homelab

Publish to the marketplace

Before submitting, validate the exact commit you intend to publish and push it to the public GitHub repository:

make validate
make lint
git add .
git commit -m "Prepare marketplace release"
git push origin HEAD

Then open the marketplace submission form and submit:

  • Repository URL: https://github.com/thatbeautifuldream/omarchy-homelab-plugin
  • Category: System
  • Tags: Bar, Quickshell, System
  • Maintainer notes: ss from iproute2 is required; Docker CLI and wl-copy are optional. The plugin runs ss, optional docker ps, xdg-open, and wl-copy with the current user's permissions and does not modify user configuration.

The submission checklist requires a public repository with install and removal instructions, a documented license and dependencies, permission to submit the code and preview assets, no implicit user-configuration overwrites, and acknowledgement that marketplace approval is not a security review.

Local development

Work from any normal source checkout. Do not install the plugin by copying files into a personal development path; use Omarchy's git-managed plugin flow so the local install matches marketplace users.

make validate
make install-local

make install-local / make sync-to:

  1. validates this repo with omarchy plugin validate .;
  2. requires the current branch HEAD to be pushed to origin;
  3. backs up any existing non-git plugin folder;
  4. installs or updates Omarchy's managed checkout for thatbeautifuldream.homelab under ~/.config/omarchy/plugins/;
  5. rescans Omarchy shell plugins.

Useful commands:

make validate          # validate manifest/schema
make lint              # run qmllint with Omarchy import paths
make test-model        # run model regression tests
make install-local     # install/update through Omarchy's git-managed plugin flow
make sync-to           # compatibility alias for install-local
make link              # compatibility alias; symlinks are not used
make update-installed  # run omarchy plugin update thatbeautifuldream.homelab --yes
make reload            # force plugin rescan
make status            # query live plugin status IPC

make sync-from intentionally does not copy files back. Official Omarchy installs are ordinary git checkouts; use git in the source repo instead.

Requirements

  • Omarchy with omarchy-shell plugin support.
  • ss from iproute2.
  • Optional: Docker CLI for Docker-published port detection.
  • Optional: wl-copy for copy actions.

Safety and permissions

The plugin has no install or startup hook beyond the commands declared in manifest.json. At runtime it:

  • reads listening sockets with ss;
  • optionally reads Docker-published ports with docker ps;
  • invokes xdg-open only for classified TCP endpoints;
  • invokes wl-copy only when copying an endpoint; and
  • sends SIGTERM only after revalidating the selected visible app process by PID, /proc start time, command name, and current listening socket. Docker-backed and system rows cannot be killed.

These commands run with the current user's permissions inside the unsandboxed omarchy-shell process. The plugin does not write user configuration or persistent state.

Removing the plugin deletes its Omarchy-managed checkout. It does not alter the services or containers it discovers. Use the removal command above.

Repo shape

manifest.json
BarWidget.qml
Panel.qml
Model.js
HomelabIcon.qml
homelab.svg
poll-services
kill-service

The manifest declares one bar-widget entry point: BarWidget.qml. Panel.qml is loaded by the bar widget, so it is not declared as a separate plugin kind.

License

MIT