dsh-zen-remote

Turn DeepSeek Harness into a phone app you can safely reach from the public internet: a mobile UI, a pairing-code gateway, install-to-home-screen, and lock-screen push.

中文文档

Screenshots are a 390×844 phone viewport in the light theme; both themes are supported. The pairing page is drawn by the gateway itself and is always dark.

Install

dsh plugin add dsh-zen-remote

Restart dsh web afterwards. The mobile UI and the gateway both come up — there is no config line to hand-write.

Compatibility — one build, both runtimes. Verified live on DSH 0.1.1-rc.2 and 0.1.2-rc.1 (web profile), 2026-09-04.

0.1.2 removed @deepseek-ai/dsh-client-runtime and put the web UI behind a signed cookie, which would have broken the mobile UI and locked the phone out of the gateway. The plugin carries its own store engine instead of importing that package, probes for the services 0.1.2 moved (uiWorkspace, uiSession) and falls back to the 0.1.1 shapes when they are absent, reads a turn's events through either session.events or session.snapshotEvents(), and lets the gateway do the browser-token handshake on the phone's behalf — all of it inert on 0.1.1, where the token endpoint does not exist.

One thing to know on 0.1.2: the web UI now rejects requests whose Host is not trusted. Reaching DSH through this plugin's gateway is unaffected (the gateway presents every request as 127.0.0.1), but pointing a browser straight at http://<LAN-IP>:3080 returns 403 unless you start dsh web --trusted-host <host>.

To uninstall: dsh plugin remove dsh-zen-remote (or delete the two lines from your profile's dependencies and bundles) and restart dsh web. To also wipe the pairing data, delete ~/.dsh/lan-gate-state.json and ~/.dsh/lan-gate.config.json.

{
  "dependencies": {
    "dsh-zen-remote": "^1.1.13"        // for local development: "link:/path/to/dsh-zen-remote"
  },
  "dsh": { "profile": { "bundles": [
    "@deepseek-ai/dsh-base",
    "@deepseek-ai/dsh-web-app",
    "dsh-zen-remote"
  ] } }
}

cd ~/.dsh/profiles/web && pnpm install
# restart dsh web

Setting up public access

Once installed, the mobile UI already works at 127.0.0.1:3080 on the machine itself. To reach it from outside, three steps.

1. Put a reverse proxy in front for HTTPS

The gateway listens on 127.0.0.1:3088 only — exposing it is your reverse proxy's job. If your home connection has no public IP, or you'd rather not open a port on your router, skip nginx/Caddy and jump to the third block (Cloudflare Tunnel).

# once, inside the http {} block
map $http_upgrade $connection_upgrade { default upgrade; '' close; }

server {
    listen 443 ssl http2;
    server_name dsh.example.com;

    ssl_certificate     /etc/letsencrypt/live/dsh.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/dsh.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3088;
        proxy_http_version 1.1;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;

        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_buffering off;
        proxy_read_timeout 3600s;
    }
}

dsh.example.com {
    reverse_proxy 127.0.0.1:3088
}

For Lucky (routers/NAS), see docs/remote-access.en.md. When the proxy and the gateway are on different machines, put the proxy's egress IP in LAN_GATE_TRUSTED_PROXIES.

2. Self-check

From mobile data (not your home Wi-Fi), open https://your-domain/lan-gate/admin. The correct result is a 403.

If you can see the admin page, your proxy isn't sending the X-Forwarded-* headers and public requests are being treated as local ones. Go back and fix the forwarded headers before continuing.

3. Pair a device

# on the machine running DSH, in a browser on that machine
open http://127.0.0.1:3088/lan-gate/admin

1. Click "Generate pairing code" for an 8-character code (valid 10 minutes, single use);
2. On the phone, open your HTTPS domain and enter the code on the pairing page;
3. Once paired you land in DSH. Identity lives in a long-lived cookie, so switching networks doesn't log you out;
4. Use the browser's "Add to Home Screen" to install it as an app;
5. Grant notification permission, and the agent reaches your lock screen when it needs you.

The admin page can also rename devices, change a device's type, and revoke devices one at a time or all at once.

Optional configuration

Environment variables, or ~/.dsh/lan-gate.config.json (keys are the variable names minus the prefix, camelCased — port, trustedProxies; an explicit env var wins). Restart dsh web after changing anything.

The upload size limit (20MB by default) is config.maxUploadBytes on the plugin row.

To enable turn-process folding on desktop too (it only applies at phone widths by default), set config.turnFoldDesktop to true on the plugin row — that is, add this to the profile's cordis.patch.yml:

- id: dsh-zen-remote
  config:
    turnFoldDesktop: true

Restart dsh web afterwards. Without touching the server config, a single browser can also turn it on for itself by visiting ?mobile-nav-turn-fold=1 once (=0 turns it off; remembered per browser).

Three calibration values for the soft-keyboard lift. On a few phones the system never tells the browser how tall the keyboard is (measured: certain third-party IMEs plus Chrome; the PWA shell Xiaomi's browser installs). With no measurable signal at all, the plugin has to lift the input box by estimate. The estimate is tuned to one reported device, so it may be too high or too low on yours — all three numbers are adjustable on the plugin row:

- id: dsh-zen-remote
  config:
    keyboardLiftRatio: 0.45
    keyboardSafetyPadPx: 30

How to tune: if the box is lifted too little (the keyboard still covers part of it), raise keyboardLiftRatio in steps of 0.03; if it's lifted too far (a gap opens between the box and the keyboard), lower it. If it's off by only a little (tens of pixels, on Android), reach for keyboardSafetyPadPx first. Leaving all three unset keeps today's behaviour exactly; out-of-range values are clamped to the table above, so the input box can never be pushed off-screen. Phones that report properly take the measured path and none of these values affect them.

When notifications fire

By default only when you are actually needed, along two independent lines.

1. Decided by the system (always on, never suppressed by the debounce)

Neither looks at session depth — a subagent stuck on an approval still calls out, because it's still you it's waiting for. Neither is suppressed by DSH_PUSH_DEBOUNCE_MS either: "something needs your nod" is the one notification that must never be swallowed.

Timing when a machine answers: approval events arrive as "record asked → consult the answerer → record decided", so the push doesn't fire the moment asked appears — it waits DSH_PUSH_APPROVAL_GRACE_MS (5 seconds by default) and skips anything answered within it. That window used to be 1.5s, designed around "every answerer settles in the same tick". True for a synchronous answerer, not for a model-backed one (measured: 2.4s average), and the result was a "needs your approval" push for a request that was auto-allowed — notification delivered, dialog never shown. Raise it if you switch to a slower judge.

Approvals a policy waves through don't disturb you: after the request lands, the push waits 1.5s and cancels if the matching "decided" arrives. Only genuinely unattended ones go out.

2. Decided by the model

The push_notify tool. The model should call it when you explicitly asked to be told when something finished, when it needs you to continue, or when something unexpected happened that you'd probably want to know right away. The tool description also spells out when not to call it (routine turn ends, progress reports, anything it can push forward on its own) — listing only the former turns it into a per-turn reflex. The same guidance is injected as standing session context, from one shared constant, so the two cannot drift apart.

What does not fire by default

• A plain finished turn does not push (changed in 1.0.3; before that every turn did). Getting work done isn't the same as needing you. Set DSH_PUSH_TURN_END=1 for the old behaviour.
• A subagent finishing never pushes, regardless of that switch.

What's in a notification: by default the title only, with no conversation content. With DSH_PUSH_SUMMARY=1 the body carries this turn's final reply — prose only, never the reasoning; a turn that produced no prose falls back to "Last executed: " rather than padding it out with thinking text. The push payload is aes128gcm end-to-end encrypted.

Features

• Two-level page stack — session list home plus a standalone session page, pushed in and out horizontally
• Plugin entry chips on the home screen, appearing automatically for what you have installed, individually hideable
• Reworked composer: controls become icons, the permission and model menus become bottom sheets
• Session info card: six stats plus export log / rename / fork / archive
• Reasoning and tool calls within one turn fold into a single "process · N steps" row by default
• Gestures: swipe right from the left edge to go back, swipe down to dismiss a bottom sheet. Android's system back gesture is taken over as "close the overlay → back to the list → leave the app", instead of quitting the PWA on the first press
• Local attachment upload from the phone: files land in the session's working directory under .dsh-uploads/ and an @ reference is appended to the composer — sending it is still your call
• A pairing code buys a long-lived device token; identity follows the token, not the IP, and can be revoked at any time
• The admin surface (generate a code / manage devices / trigger a push) only accepts direct local connections; anything through the proxy gets a 403
• A real PWA: manifest plus service worker, installable to the home screen, opens offline
• Real Web Push: VAPID plus aes128gcm, no conversation body by default; fires only for approvals and questions, no longer on every turn end (see above)
• The push_notify tool: the model can push at a moment that matters, rate-limited
• The "internal testing notice" dialog gets a "don't show again" option: remote access re-shows the notice on every reload, and one click makes this device remember and dismiss it from then on

In depth: interface · public access

Third-party plugins with mobile support

The mobile UI has specific adaptations for the plugins below. Every adaptation is anchored on that plugin's own DOM markers: if you don't have it installed the rules simply don't match, and installing a plugin that isn't listed here can't be caught in the crossfire.

The technical detail behind each adaptation — anchor selectors, breakpoints, what was traded away — is in the "compatible plugins" section of the interface doc.

Known issues

iOS 26.x standalone PWA viewport shrinkage: after adding to the home screen, the viewport loses a status-bar's height at the bottom; an ordinary Safari tab is fine. This is an iOS defect — the missing region is outside the document and CSS cannot reach it. The plugin ships three layers of mitigation (light manifest background, safe-area compensation, forced reflow) which reduce it without guaranteeing a fix. Only quitting and reopening the whole app restores it fully.

In a few environments the soft keyboard is completely invisible to the browser, and the lift falls back to an estimate: in some combinations (measured: certain third-party IMEs plus Chrome; the PWA shell installed by Xiaomi's browser) the system never tells the page the keyboard's height when it opens or closes — the viewport doesn't change and no event fires (visualViewport and the VirtualKeyboard API both fail; both ruled out by measurement). The fallback: probe for about 1.2s after focus, and if the keyboard is judged invisible, lift the input box by the estimated height (the verdict is remembered per browser, so later focuses lift immediately). Two costs: the lift is an estimate and can be tens of pixels off the real keyboard, and there's no signal for the keyboard closing either, so the box only drops back once you tap or scroll outside it. Normal environments never take this path. If the lift is visibly off you don't need to change code — keyboardLiftRatio / keyboardLiftMaxPx / keyboardSafetyPadPx on the plugin row are there to be tuned to your device; see the configuration section above.

Settings pages don't open through the reverse proxy (the plugin config list is blank, model cards report "settings are unavailable in this browser"): connecting directly to 127.0.0.1:3080/3088 works fine.

The root cause is DSH's own design, not the gateway: settings RPCs are loopback-only. The client decides from location.hostname (isLoopback in dsh-client-connection), and off-loopback dsh-client-ui-settings degrades persistence to memory, so the settings mirror starts out unavailable — the upstream source comment reads, verbatim, "remote browsers remain process-local because settings RPCs are loopback-only". Every card that depends on that mirror (models, plugin config) goes blank together. Nothing to do with this plugin or with service worker caching (verified 2026-08-20 by USB-debugging a real device against a local control).

Workaround: change settings from a browser on the machine running DSH. The config lives in the backend, and nothing else on the phone side is affected. Making settings remotely editable requires upstream to relax that restriction.

Permissions and data

• Network: the gateway listens on the local machine only (127.0.0.1:3088 by default); what gets exposed is entirely up to your reverse proxy or tunnel. Push travels through the browser vendor's push service (the content is aes128gcm end-to-end encrypted, so the vendor can't read it). The plugin itself reports nothing to any third party.
• Files: attachment uploads are written only to .dsh-uploads/ inside the current session's working directory; pairing state and config live in ~/.dsh/lan-gate-state.json and lan-gate.config.json.
• Credentials: no account or password is ever collected or stored; a device's identity is a random token this plugin issues itself, in an HttpOnly cookie.

Troubleshooting: runtime logs are in ~/.dsh/logs/web.log (gateway and push lines are prefixed [dsh-zen-remote-*]); the phone UI has a debug badge for self-checks (tap the home screen's top bar five times to toggle it). Please report security issues privately through GitHub Security Advisories rather than opening a public issue.

Upstream credits

This plugin's interface layer derives from mexiaosqwq/dsh-web-mobile, and its channel layer from zylzyqzz/dsh-mobile-pwa (itself derived from Bernardxu123/dsh-mobile-gate), both MIT. The original copyright lines are preserved in LICENSE.

License

MIT