Omarchy Ring Cameras

A native Omarchy Quattro bar plugin for Ring camera notifications, live views, and recent recorded events.

The bar icon opens a live view for the selected camera. Inline playback starts muted and includes a sound toggle. A doorbell or motion event is added to the camera's recent-events panel and creates an Omarchy notification that deep-links to the recording. Live video can be enlarged into mpv when needed, while right-clicking the bar icon refreshes the panel state.

This project is not affiliated with Omarchy, Ring, or Amazon.

Architecture

The plugin deliberately separates desktop UI from camera access:

• BarWidget.qml and Panel.qml run inside the existing Omarchy shell.
• omarchy-ring-bridge.service listens to local MQTT events, stores snapshots, and sends Omarchy notifications.
• upstream ring-mqtt handles Ring authentication, push events, and on-demand RTSP.
• a local-only Mosquitto broker connects the two services.
• Qt Multimedia displays the selected RTSP stream inside the panel only when requested; mpv remains available for enlarged and multi-camera views.

Everything runs natively as your user. Docker is not used.

Install

Find Ring Cameras in the Omarchy plugin manager, then install and enable it there.

Open the new Ring icon and choose Install backend. The panel shows setup progress and, only when system packages are missing, opens Omarchy's graphical system-authentication prompt. You do not need to type or run a terminal command.

The one-time setup installs official Arch packages (git, curl, nodejs-lts-jod, npm, mosquitto, jq, mpv, ffmpeg, and qt6-multimedia). It downloads the pinned upstream go2rtc 1.9.14 binary for the current architecture over HTTPS and verifies its published SHA-256 checksum before installing it for the current user. It also installs upstream ring-mqtt 5.9.3 under ~/.local/share/omarchy-ring/ and verifies the checkout against its immutable release commit before running npm ci.

After native setup, open the Ring icon in the bar and sign in there. The panel handles Ring's 2FA challenge and keeps any error visible so you can correct it without reopening a terminal. omarchy-ring authenticate opens the same sign-in panel.

Your password and 2FA code travel to the local authentication helper over standard input, never as command-line arguments. Neither value is saved or logged. The helper exchanges them directly with Ring and saves only the resulting refresh token in:

~/.local/share/omarchy-ring/ring-mqtt/ring-state.json

The file and parent service directory are user-owned. The installer sets the token file to mode 0600.

Remove

Remove Ring Cameras with the Omarchy plugin manager. No terminal command is needed.

Once the manager removes the plugin repository, its user-level cleanup watcher:

• stops and disables the three omarchy-ring-* services;
• removes the local Ring refresh token, configuration, cached snapshots, state, and pinned ring-mqtt checkout;
• removes the user-local go2rtc binary only when this plugin originally installed it; and
• leaves shared Arch packages installed so removal cannot break another application.

The cleanup is deliberately scoped to paths named omarchy-ring and the plugin's own systemd units. Removing or merely disabling another plugin does not trigger it.

Usage

• Left-click the camera icon to open the panel.
• Choose Sign in or Reconnect in the panel to authenticate with Ring.
• Select a camera to start its live view inside the panel.
• Choose Sound off on the video to enable audio; closing the panel mutes it again.
• Cameras reported offline by ring-mqtt are labeled before playback; unknown or stale status is protected by a 12-second live-start timeout.
• Choose Events to browse the latest motion and doorbell recordings reported by ring-mqtt, plus captured snapshots for up to five events of each type observed by the bridge. Opening a camera's event list clears its new-event count, and that viewed state persists across shell and plugin reloads.
• Choose View event to play a recording in the panel, then Back to live to return to the camera.
• Choose Embiggen to move the selected live view into mpv and close the panel.
• Choose Embiggen all, or middle-click the icon, to open the available cameras together in one centered mpv window and close the panel. The window appears immediately with a loading message while its streams initialize, and cameras reported offline are omitted. The 16:9-aware grid stacks two cameras vertically, uses 2×2 for four, and 2×3 for five or six cameras; incomplete final rows are centered.
• Right-click the icon to refresh state.
• Click a Ring event notification to open the originating camera and recorded event directly.

Useful commands:

omarchy-ring list
omarchy-ring status
omarchy-ring open [camera-id]
omarchy-ring view <camera-id>
omarchy-ring view-all
omarchy-ring test-notification
omarchy-ring logs bridge
omarchy-ring logs ring-mqtt
omarchy-ring restart

Configure

Run:

omarchy-ring configure

The file is ~/.config/omarchy-ring/config.json:

{
  "mqttHost": "127.0.0.1",
  "mqttPort": 1883,
  "mqttUsername": "",
  "mqttPassword": "",
  "topicPrefix": "ring",
  "rtspHost": "127.0.0.1:8554",
  "rtspUsername": "",
  "rtspPassword": "",
  "notifyDing": true,
  "notifyMotion": true,
  "notificationDelayMs": 1800,
  "cameraNames": {
    "camera-device-id": "Front Door"
  }
}

Restart the bridge after changing it:

systemctl --user restart omarchy-ring-bridge.service

If you add RTSP credentials, put the same values in the livestream_user and livestream_pass fields of ~/.local/share/omarchy-ring/ring-mqtt/config.json, then restart both services.

Existing ring-mqtt or MQTT installations

Advanced users can point ~/.config/omarchy-ring/config.json at an existing MQTT broker after completing the in-panel setup. The bridge subscribes to the standard ring/<location>/camera/<device>/... topics published by ring-mqtt. Set rtspHost to the externally reachable ring-mqtt RTSP host and port.

Update

Use the Omarchy plugin manager to update the plugin repository. When an update includes new local helpers or services, the panel detects the backend version mismatch and shows Update backend. Backend versions remain pinned, so an upstream release cannot silently change the authentication or streaming contract. A future backend version is adopted only after its version and checksum are reviewed in scripts/setup-native.sh.

Backend setup deliberately runs npm with the supported system Node.js runtime instead of a shell-specific Node override. Dependency install scripts are disabled: the plugin already supplies system FFmpeg, and protobuf's post-install script only emits a version-scheme warning. Setup also summarizes current production dependency advisories without automatically rewriting the verified upstream lockfile.

Security and privacy

• MQTT listens only on 127.0.0.1; it is not exposed to the LAN.
• Backend installation requires explicit consent from the panel; enabling the plugin alone does not install packages or execute privileged commands.
• Missing official packages are installed through a graphical Polkit prompt. The plugin never uses an embedded password or requests unrestricted root access.
• The downloaded go2rtc executable is pinned and checksum-verified before it is made executable.
• Ring credentials are passed privately over standard input to the installed helper and are never saved or placed in process arguments.
• Refresh tokens, plugin state, and cached snapshots are stored in user-only paths.
• Per-camera viewed-event IDs are stored in ~/.local/state/omarchy-ring/viewed-events.json (or $XDG_STATE_HOME/omarchy-ring/).
• Cached event snapshots live in ~/.cache/omarchy-ring/snapshots/.
• All Ring video still travels through Ring cloud servers. This is not a local-camera conversion.
• Review the upstream ring-mqtt, ring-client-api, and go2rtc sources before installing them.

External projects retain their own licenses and security policies: ring-mqtt, ring-client-api, go2rtc, Mosquitto, FFmpeg, and mpv.

Ring limitations

Ring cameras are designed for event-based and short interactive viewing. Do not use Embiggen all as a continuous monitor: live streaming can drain batteries, heat cameras, and suppress motion/ding events while a stream is active.

Camera availability uses Ring's health data as a practical proxy: a reported Wi-Fi network or signal means online, while explicit null Wi-Fi health fields mean offline. Wired health data is handled the same way. This device-health result takes precedence over ring-mqtt's generic online heartbeat, which prevents an unplugged camera from briefly appearing online during metadata refreshes. If Ring omits connectivity health entirely, the panel reports unknown instead of guessing. Live video reports a timeout if playback does not begin within 12 seconds.

The Ring API used by ring-mqtt is unofficial and can change without notice. End-to-end encrypted Ring cameras are not supported. Push notifications require an outbound connection to mtalk.google.com on TCP port 5228. Stored event playback requires an appropriate Ring Protect plan, although live view does not. Without a compatible recording, the event browser still retains the captured event snapshot and timestamp.

Validate

omarchy plugin validate .
qmllint -I "$OMARCHY_PATH/shell" BarWidget.qml Panel.qml
node --test tests/*.test.mjs
bash -n install.sh bin/omarchy-ring scripts/setup-native.sh scripts/remove-backend.sh

Publish

The repository follows the Omarchy marketplace contract with the permanent namespaced ID bitshaker.ring-cameras, a root-level manifest, public documentation, an MIT license, manager-based installation and removal, explicit dependency consent, and a reversible local backend lifecycle.

License

MIT. ring-mqtt, Ring client libraries, Mosquitto, go2rtc, FFmpeg, mpv, and Omarchy retain their own licenses.