Omahub
← All plugins
S

Omaport

by Sahzudin Mahmic

Inspect and manage local development ports from the Omarchy bar.

GitHub

Security review

No obvious issues detected

Deterministic scan — not a security guarantee

None
Risk level
None
Analyzed commit
2c59ba2
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
2c59ba2
Reviewed
1 month ago

The plugin is a local port inspector with safe process termination and Docker stop features, all guarded by user ownership and confirmation. No malicious behavior detected.

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/sahzudin/omaport --enable
Developer Tools #bar #quickshell #system

Omaport

Omaport is an Omarchy bar widget for seeing what is listening on your machine without leaving the desktop. It presents local TCP listeners and Docker-published ports in a native, theme-aware popup.

Features

  • Compact, icon-only Omarchy bar indicator with listener status in its tooltip.
  • Search by port, process, command, project directory, or container.
  • Open a listener in the browser or copy its local URL.
  • Gracefully terminate or force-kill user-owned processes after confirmation.
  • Stop Docker containers through Docker rather than killing proxy processes.
  • Highlight listeners bound beyond loopback.
  • Optional UDP discovery and configurable ignored ports.

Omaport deliberately shows system-owned processes as read-only. Before signaling a process, the helper verifies its owner and Linux process start time so a reused PID cannot target a different process.

Requirements

  • Omarchy 4.0 or newer
  • Python 3
  • ss from iproute2
  • xdg-open and wl-copy for the open and copy actions
  • Docker CLI and access to the Docker daemon for optional container discovery

Install

omarchy plugin add https://github.com/sahzudin/omaport.git --enable

For local development, place or link this repository at:

~/.config/omarchy/plugins/io.github.sahzudin.omaport

Then discover and enable it:

omarchy-shell shell rescanPlugins
omarchy plugin enable io.github.sahzudin.omaport --section right

Right-click the bar widget to refresh it manually. Left-click opens the panel.

Remove

omarchy plugin remove io.github.sahzudin.omaport

Removing Omaport deletes its plugin checkout and bar entry. It does not modify other Omarchy configuration or leave a background service running.

Settings

The Omarchy bar settings expose:

  • refreshIntervalSec: listener refresh interval, from 2 to 120 seconds.
  • includeDocker: include published ports from running Docker containers.
  • includeUdp: include unconnected UDP sockets.
  • ignoredPorts: comma-separated ports or ranges such as 53,631,8000-8010.

The default ignore list hides DNS, CUPS, and mDNS ports: 53,631,5353.

Security

Like every Omarchy shell plugin, Omaport runs as unsandboxed code under your user account. Its helper reads local socket and process metadata using ss and /proc. It can send SIGTERM or SIGKILL only to processes owned by the current user, after confirming both the PID owner and process start time. Docker container discovery and stopping are available only when Docker support is enabled and the current user already has access to the Docker daemon.

Omaport operates entirely with the current user's existing access. It does not install packages, download or execute remote code, overwrite user configuration, or run a persistent background service.

Development

Run the collector directly:

python3 omaport.py list --ignore-ports 53,631,5353 | python3 -m json.tool

Run the tests and validate the plugin manifest:

python3 -m unittest discover -s tests -v
omarchy plugin validate .

Plugin files hot-reload while installed under ~/.config/omarchy/plugins/.