Omahub
← All plugins
A

Omarchy Phone

by Adam Moussa Ali

Ruby-powered Android control and iPhone AirPlay mirroring for Omarchy.

GitHub

Security review

No obvious issues detected

Deterministic scan — not a security guarantee

None
Risk level
None
Analyzed commit
5b4d275
Scanned
1 month ago

No potentially dangerous behavior detected in the analyzed commit.

Automated analysis only — not a security guarantee.

AI advisory review

Review recommended

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

Medium
AI risk level
Medium
Recommendation
review
Model
~deepseek/deepseek-v4-flash-latest
Analyzed commit
5b4d275
Reviewed
1 month ago

The readable Ruby source and manifest appear legitimate and defensive: commands are invoked without a shell, input is validated, state files are permission-restricted, and the deterministic scan found nothing suspicious. The main unresolved risk is that the plugin ships a precompiled x86-64 mruby runtime and generated QML/native bundle that are not auditable from the sampled source, so a user executes binary code that is not proven to match the supplied Ruby source.

  • The plugin is keepLoaded and loads a prebuilt native x86-64 runtime/QML bundle under OmarchyUI/Bundles; the sampled files include only the tiny QML shims and Ruby source, not the shipped binary, so the actual executable payload cannot be fully audited.
  • The README directs users to install and enable the plugin directly from the repository; combined with the prebuilt runtime, this means the installed/run code should be verified by a human before publication.
  • The plugin starts local tools such as adb, scrcpy, uxplay, and avahi-browse and can listen on local network ports when AirPlay is started; this is disclosed and user-triggered, but the network exposure and process management code deserve a manual security review.
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/AdamMusa/omarchy-phone --enable
Hardware #bar #quickshell #media

Omarchy Phone

Marketplace submission License: MIT

The first application built with Omarchy UI. It provides Android discovery, wireless pairing, scrcpy control, iPhone discovery, and AirPlay mirroring from an Omarchy bar widget and panel.

Android sessions support mouse and keyboard control through scrcpy. iPhone sessions mirror video and audio through AirPlay; Apple does not permit remote touch or keyboard input through AirPlay.

Built entirely in Ruby

All application behavior, system integration, and UI declarations are authored in Ruby. There is no handwritten QML source. Omarchy UI compiles the Ruby-declared UI into OmarchyUI/Bundles/ and emits the tiny root QML loader shims required by the plugin manifest; those shims are generated packaging output.

Features

  • Discover Android and iPhone devices automatically.
  • Pair Android 11+ devices using Wireless debugging.
  • Mirror and control Android through scrcpy, with audio, resolution, FPS, bitrate, fullscreen, and physical-screen options.
  • Mirror iPhone video and audio through AirPlay with an on-screen PIN.
  • Show connection status and device-specific actions in the Omarchy bar and panel.
  • Run without Ruby, mruby, or the omarchy-ui gem installed on the destination computer.

Install

Omarchy Phone is submitted for inclusion in the Omarchy Plugin Marketplace. Until the listing is approved, install directly from its public repository:

omarchy plugin add https://github.com/AdamMusa/omarchy-phone.git --enable

Review third-party plugin code before enabling it. Omarchy plugins run with your user account.

The repository is self-contained: it includes its QML bridge and prebuilt x86-64 mruby runtime. The current release supports x86-64 Linux systems running Omarchy with the Quickshell plugin host.

Capabilities and system tools

The plugin itself does not install system packages. Install only the tools needed for the features you plan to use:

Capability Command used Required tool
Android discovery, pairing, and Wi-Fi connection adb Android platform tools
Android mirroring and mouse/keyboard control scrcpy scrcpy
Trusted USB iPhone discovery and pairing idevice_id, ideviceinfo, idevicepair libimobiledevice
iPhone screen and audio mirroring uxplay UxPlay
Wireless Android service discovery avahi-browse Avahi tools

Android supports remote control through scrcpy. AirPlay mirrors an iPhone but cannot send touch or keyboard input back to iOS.

Android quick start

Android 11 or newer and the Omarchy computer must be on the same Wi-Fi network.

  1. On Android, enable Settings → System → Developer options → Wireless debugging.
  2. Tap Pair device with pairing code. Keep this popup open.
  3. In Omarchy Phone under Connect Android, enter the popup's complete temporary pairing address (IP:port) and its six-digit code, then click Pair before the code expires.
  4. The phone remains listed as Paired even while Android rotates its connection port.
  5. Click Connect on the paired phone; Omarchy Phone resolves the current wireless service.
  6. When it becomes connected, click Open Phone to start scrcpy and control it.

If the screen mirrors but you cannot control it

Some vendor Android builds refuse the INJECT_EVENTS permission that scrcpy's default sdk input mode relies on, and report this in the scrcpy log:

[server] ERROR: Injecting input events requires the caller ... to have the INJECT_EVENTS permission.
[server] ERROR: Make sure you have enabled "USB debugging (Security Settings)" and then rebooted your device.

The screen mirrors correctly but clicks and keystrokes are ignored. This has been reported on Xiaomi and POCO (HyperOS and MIUI), Oppo, and some Samsung devices. The suggested USB debugging (Security settings) toggle needs a vendor account and a SIM, and on some ROMs it is not present at all.

Omarchy Phone therefore starts scrcpy with --mouse=uhid alongside --keyboard=uhid, which simulates a physical HID device instead of asking Android to inject events, so control works without that permission. One side effect worth knowing: in uhid mode scrcpy captures the pointer, so press LAlt or LSuper to give the mouse back to the computer.

On a device that blocks injection you may still see one INJECT_EVENTS line at startup, from scrcpy's attempt to wake the screen. It is harmless and the session works normally.

Generate a new pairing popup if pairing reports that the code expired. Pairing establishes trust once. If Android changes its wireless connection port, pair again so the current service can be discovered and remembered.

iPhone quick start

For AirPlay mirroring, connect the iPhone and Omarchy computer to the same trusted network:

  1. Click Start AirPlay in Omarchy Phone.
  2. Note the four-digit PIN displayed in the panel and desktop notification.
  3. On iPhone, open Control Center, tap Screen Mirroring, and select Omarchy.
  4. Enter the PIN on the iPhone when prompted.
  5. Click Stop AirPlay when finished.

For USB discovery, connect and unlock the iPhone, accept Trust This Computer, and use the Trust action in Omarchy Phone if it appears. iOS permits mirroring but not remote touch or keyboard control.

AirPlay and firewall

UxPlay uses TCP and UDP ports 7100-7102; mDNS discovery uses UDP 5353. If UFW is enabled, allow those ports from the local network. Starting AirPlay displays a four-digit PIN in the panel and desktop notification. Active AirPlay sessions appear automatically in the device list.

Update or remove

omarchy plugin update izeesoft.omarchy-phone
omarchy plugin remove izeesoft.omarchy-phone

The plugin stores connection metadata and process logs in ~/.local/state/omarchy-phone-ruby. Removing the plugin leaves this local state in place so a future installation can remember paired Android devices. Delete that directory manually if you also want to forget the saved state.

Privacy and permissions

Omarchy Phone runs as the current user and starts only the local tools listed above. It communicates with phones through USB or the local network, does not provide telemetry, and does not send device information to an external service. Android pairing addresses and runtime logs remain in the local state directory. The bundled omarchy-ui-runtime is the x86-64 runtime-v0.1.4 release artifact.

Command output is limited before it reaches application state, discovery results have item and string ceilings, and runtime protocol messages are size-bounded before QML buffering. External device text is rendered as plain text. AirPlay shutdown verifies the saved PID, process start time, process group, and executable identity immediately before signaling; stale, replaced, symlinked, or non-regular state records are cleared without signaling a process.

Marketplace submission

The automated repository, manifest, README, license, and Quattro compatibility checks passed. The bundled runtime is disclosed for the marketplace's required manual executable review.

License

MIT.