dsh-mobile-pwa

Turn DeepSeek Harness (DSH) into a complete mobile PWA: secure remote access to your own DSH, install-to-homescreen, offline capable, touch gestures, agent-done notifications.

Built on the MIT dsh-mobile-gate gateway base.

Current version 0.3.0 — targets DSH 0.2.x (engines.dsh: ">=0.2.0 <0.3.0").

Features

Architecture

phone ──> gateway (standalone Node child process · 0.0.0.0:3088)
           ├─ unapproved  -> "waiting for approval" page (polls /lan-gate/admin)
           ├─ approved    -> reverse proxy to the DSH Web UI (local host:port)
           │      └─ HTML injection: manifest link + PWA bootstrap + touch CSS + randomUUID polyfill
           ├─ /pwa/*      -> manifest / sw.js / app.css / icons / offline.html
           ├─ /pwa/push/* -> subscribe / send (real encrypted push)
           └─ over limit  -> 429 page
laptop 127.0.0.1:3088/lan-gate/admin -> approve / deny / revoke, pick phone / desktop / auto

• The gateway is an isolated child process: if it dies the harness keeps running, and it is terminated when the plugin unloads.
• Since DSH 0.2 rejects a wildcard bind address (--host 0.0.0.0 fails at load), the Web UI always listens on one concrete local address. This gateway is the remote door: it owns the exposed port and the approval gate.
• The target address is not hardcoded: the plugin reads the real host/port from the webStartup service, so dsh web --port 0 and --host <addr> keep working.

Install

npm add @zylzyqzz/dsbot@0.3.0
dsh plugin --profile web add @zylzyqzz/dsbot

From a checkout:

git clone https://github.com/zylzyqzz/dsbot.git
cd dsbot
dsh plugin --profile web add ./dsbot

Environment variables

When no VAPID keypair is supplied, one is generated once and stored in ~/.dsh/lan-gate-vapid.json (mode 600) so subscriptions survive restarts.

How DSH 0.2 browser authentication is handled

Since DSH 0.2 a browser needs a signed session cookie, and the first issue of that cookie needs a process launch token that changes on every restart. This plugin removes that step for the user:

1. The plugin reads the launch token from ctx.connection.authenticatedUrl() inside the DSH process and hands it to the gateway child.
2. The gateway forwards the browser-facing Host unchanged (DSH's Host/Origin fence and the cookie's authority both depend on it) and, when the browser has no session cookie yet, exchanges the token upstream and passes the cookie straight to the browser.
3. The user therefore opens a plain URL — no tokenized link to copy from the startup log.

DSH must trust the public authority for this to work: set LAN_GATE_TRUSTED_HOSTS to the public host or host:port (the bundle's connection row merges it into the --trusted-host list), or pass --trusted-host <public authority> on the command line.

Flow

1. Server: start DSH with the plugin; look for [dsbot] listening on 0.0.0.0:3088 -> <host>:<port> (pwa=on).
2. Phone: open http://<server-ip>:3088 → "waiting for approval".
3. Laptop: open http://127.0.0.1:3088/lan-gate/admin → approve the device, choose "phone".
4. Phone: pull to refresh → the DSH Web UI, PWA injected.
5. Install: browser menu → "Add to Home Screen".
6. Optional: allow notifications when the page offers it.

Bot browser (real Chrome, one command)

ds-bot ships 12 browser tools but no browser, its launch args are hardcoded, and it has no proxy setting. One command fills the gap:

# on your DSH server
node scripts/setup-browser.mjs --proxy http://127.0.0.1:7890
sudo systemctl restart dsh-web

It downloads Chrome for Testing, installs the system libraries (including the Ubuntu 24.04 libasound2t64 rename), installs playwright-core, drops in the proxy shim, opens a real page to verify, then writes the - id: bot row into your profile patch (with a backup).

Your Bots then get browser_open / browser_snapshot / browser_click / browser_screenshot / browser_handoff and seven more — and a screenshot arrives as an image in the conversation, not a tool log line.

node scripts/setup-browser.mjs --verify-only      # doctor at any time
node scripts/setup-browser.mjs --print-config     # just print the YAML
sudo node scripts/xray-split-route.mjs            # split route: China direct, rest proxied

Why the shim exists, how proxy selection works, troubleshooting → docs/browser.md

How agent-done is detected

DSH 0.2 renders [data-chat-running] while the agent is working. The injected script watches it with a MutationObserver; when it disappears the turn is over, so the page raises a local Notification and reports it to the gateway, which pushes it to the other subscribed devices.

The 0.1-era host plugin dsh-push.mjs was removed: it depended on DSH 0.1's conversation/http services, which no longer exist in 0.2. Browser-side detection is more accurate (DSH's own DOM is the source of truth) and keeps the host process clean.

Local test

npm test

Boots the real gateway behind a mock upstream and asserts /pwa asset serving, HTML injection, status reporting and a full Web Push encrypt/decrypt round-trip.

Layout

Notes for contributors

• Isolation: the gateway is a child process. Never import its server code into the DSH process.
• Pass the environment explicitly: DSH 0.2's ctx.subprocess scrubs ambient credentials and DSH_* facts before applying the caller's env, so every LAN_GATE_* value, DSH_HOME and the VAPID keys must be handed over in the spawn request.
• Scope the mobile CSS: every rule belongs under html[data-lan-device="phone"] (or the @media(max-width:820px) fallback that excludes desktop). The desktop must never be affected.
• Stable selectors: prefer [data-slot]/[data-*]/ARIA over hashed build class names. When DSH renames a slot the mobile layout silently stops applying — re-check the slot list against upstream packages/client after a DSH upgrade.
• Push must be encrypted: a push service rejects a plain-text body. Use lib/web-push.cjs.

License

MIT. lib/lan-gate-server.cjs extends dsh-mobile-gate and keeps the original MIT copyright and licence — see LICENSE.