Introduction

The design philosophy of DeepSeek Harness (dsh) is “everything is a plugin.” In development or operations scenarios, agent tasks often run in the background, and developers may not be at the terminal when a task completes. Knowing the task status as soon as possible is a common pain point.

The DSH ecosystem already has some remote monitoring plugins (such as dsh-pocket), which usually provide full UI interactions. This plugin reuses the same mature pattern, but focuses on a single core: notifications. It provides native desktop notifications for macOS/Windows/Linux and supports zero-config mobile PWA/Web Push pairing, syncing task completion status to the phone lock screen in real time.

Core Features

This plugin provides the following capabilities:
* Native desktop notifications: Displays system notifications on macOS, Windows, and Linux, including the task summary and duration.
* Mobile QR-code pairing: Uses PWA or Web Push protocols to pair a phone with a computer and receive lock-screen notifications.
* Cloudflare Quick Tunnel: Starts a public tunnel with one click, enabling mobile push even without a public IP or in non-LAN environments.
* Capability separation: Provides three independent modules: task-notify (desktop), mobile-push-notify-gateway (gateway/tunnel), and mobile-push-notify-push (push).

Installation and Enablement

Installing the plugin uses the dsh plugin command; no manual code download is needed.

  1. Install the plugin
    dsh plugin --profile web add dsh-mobile-push-notify
  1. Restart the Web service
    dsh web
  1. Check the logs
    After the plugin starts, it automatically opens a gateway. You can see the admin page address in the terminal startup logs, defaulting to http://127.0.0.1:3188/admin.

Usage

1. Computer Notifications (Zero Configuration)

After installation and running, no extra setup is required. When a task in DSH completes (for example, a turn/end event with status completed, or a goal/change with completion stage reached), the system automatically sends a notification.
* macOS: Notification Center banner + Glass alert sound.
* Windows: System Toast.
* Linux: notify-send.
* If the system notification service is unavailable, the terminal automatically rings as a fallback.

2. Phone Pairing

Access the gateway admin page from the phone to complete pairing.

  1. Open http://127.0.0.1:3188/admin in a browser on the computer.
  2. LAN pairing: Make sure the phone and computer are on the same WiFi network, then scan the “LAN pairing” QR code on the page.
  3. Public pairing: Click “Enable public tunnel” on the page. On first use, the cloudflared binary is downloaded automatically. Once the public QR code appears, scan it.

After successful pairing, the phone automatically opens the official DSH Web interface and keeps real-time sync.

3. Enable Mobile Push

  1. On the phone, enter the DSH Web interface.
  2. Click the “🔔 Enable task notifications” button in the bottom-right corner of the page, and allow the browser to send notifications.
  3. iOS users note: It is recommended to open it in Safari, tap the Share button “Add to Home Screen” to install it as a PWA, and then tap enable notification (iOS 16.4+ requires HTTPS).
  4. Android users: You can install the PWA directly in Chrome or Edge or allow notifications.

After that, when a task completes, the phone lock screen receives a notification containing the task title, summary, and duration. Tapping it directly returns to the DSH interface to view details.

Configuration Notes

The default plugin configuration covers most scenarios. To adjust it, use environment variables or modify the configuration file ~/.dsh/profiles/web/cordis.patch.yml.

Common Environment Variables

Variable Default Description
DSH_TASK_NOTIFY_ENABLED 1 Master switch; set to 0 to disable notifications.
DSH_TASK_NOTIFY_EVENTS completed,error,aborted,goal-completed Event types that should trigger notifications.
DSH_TASK_NOTIFY_SOUND Glass macOS alert sound name; set to none to mute.
DSH_TASK_NOTIFY_BELL 0 Whether to ring when system notifications fail.
DSH_TASK_NOTIFY_GATEWAY_PORT 3188 Gateway listening port.
DSH_TASK_NOTIFY_TARGET_PORT Auto-read DSH Web service listening port.
DSH_TASK_NOTIFY_VAPID_SUBJECT mailto:... VAPID email address strictly validated by iOS.

Advanced Push

The plugin supports extension to Bark or a generic Webhook.

Bark configuration (needs to be set in ~/.dsh/task-notify.json or environment variables):

{
  "barkKey": "你的 Bark Key",
  "webhookUrl": "https://example.com/hook/{{title}}"
}

Security Model

Understanding the plugin’s security mechanisms helps use it safely in public-network environments.

  • LAN isolation: The gateway reverse-proxies traffic to the DSH Web service on 127.0.0.1 by default. Therefore, there is no need to bind DSH Web to 0.0.0.0, and the local network remains safer.
  • Access control: The admin pages /admin* and the push-sending endpoints accept loopback requests only. Paired devices have full control permissions. Do not share the pairing QR code with others.
  • Pairing security: Pairing Tokens expire after 10 minutes. Pairing uses one-time Tokens. Devices can be revoked individually, or “Stop all pairings” can clear them.
  • Public tunnel risk: Enabling the Cloudflare tunnel exposes DSH, which can execute code, to the internet. Turn it off after use. If a long-term fixed address is needed, configure DSH_TASK_NOTIFY_PUBLIC_BASE_URL and use a Cloudflare named tunnel or your own reverse proxy.
  • Push encryption: Web Push uses standard aes128gcm encryption; the push service can only access ciphertext.

Compatibility

  • DSH version: dsh >= 0.1.0-rc.5
  • Node version: node >= 20
  • Required permissions:
    • exec: Requires tools such as osascript, notify-send, and powershell.
    • network: Requires webhook access permission and DNS resolution for domains such as github.com.

License

MIT