dsh-zen-remote

One DeepSeek Harness plugin, two roles. The host turns DSH into a phone-reachable PWA (mobile UI, pairing gateway, lock-screen push) and shares chosen sessions to paired desktops. The client runs inside another DSH desktop app and puts the host's shared sessions right into its own sidebar — full history, live progress, messages, approvals, terminal, everything executes on the host.

中文文档

Session list home	Session page	Session info card

Composer permission sheet	Pairing page a public visitor sees

Screenshots are a 390×844 phone viewport in the light theme; both themes are supported. The pairing page is drawn by the gateway in DSH's official style, following the system light / dark appearance.

Contents

1. Install
2. Quick Start (Unified Setup & Pairing Wizard)
   • Scenario A: Set up as Host (Phone & Desktop Access)
   • Scenario B: Set up another computer as Desktop Client
3. Daily Usage: Session Sharing & Cross-Device Workflow
4. Lock-Screen Push: When Notifications Fire
5. Features
6. Advanced Settings & Field Reference
7. Security Model, Version Tolerance & Known Notes

1. Install

Install from the UI (Recommended, Desktop App & Web UI)

Open the Plugins page in the DSH sidebar → click Add plugin → type dsh-zen-remote → click Enable now when the install finishes, then restart the DSH desktop app (or dsh web).

Install from the CLI (Headless dsh web server)

dsh plugin --profile web add dsh-zen-remote
# then restart dsh web

dsh plugin requires --profile to name the target profile. The desktop app's desktop profile is managed exclusively by the app (--profile desktop is refused on the CLI), so use the UI install above on the desktop app.

// ~/.dsh/profiles/desktop/package.json
{
  "dependencies": {
    "dsh-zen-remote": "^2.3.2"        // for local development: "link:/path/to/dsh-zen-remote"
  }
}

cd ~/.dsh/profiles/desktop && pnpm install
# For a link: checkout, also run `npm install --omit=dev` inside the repository so the gateway subprocess can resolve `web-push`.

2. Quick Start (Unified Setup & Pairing Wizard)

The same plugin supports two roles:

• Server (role: host, default): runs your sessions, spawns the local security gateway and Web Push service, and lets your phone (PWA) or another computer connect.
• Desktop Client (role: client): runs inside another computer's DSH desktop app, connects to the host, and mounts the host's shared sessions directly into its own sidebar (without spawning a local gateway or fighting for port 3088).

Open Plugins → dsh-zen-remote in DSH. The Remote Access & Device Pairing card sits right at the top of the page:

Scenario A: Set up as Host (Phone & Desktop Access)

Click Start Setup Wizard (or Reconfigure Wizard if already configured) to complete setup in three guided steps:

Step 1: Choose "Act as Server (Host)" & an Access Method

Pick one of the four access methods based on your network environment (switching methods automatically stops any managed process from the previous mode and updates the gateway bind address):

Step 2: Fill in Connection Parameters

• Managed Caddy / Cloudflare Tunnel: enter your public domain (e.g. dsh.example.com) and paste your Cloudflare API Token (click "How do I get an API token?" for step-by-step instructions and required permissions, or "Domain not on Cloudflare yet?" for onboarding steps).
• Existing Reverse Proxy: enter the external https:// URL of your proxy and copy the generated Nginx / Caddy / Lucky configuration snippet.
• LAN / Tailscale Direct: the wizard automatically detects and pre-fills http://<your-LAN-or-Tailscale-IP>:3088.

Step 3: Verify Connectivity & Pair Devices

1. Start Ingress Service & Auto-Probe:
   • For Managed Caddy or Cloudflare Tunnel, click Start Caddy or Create & Start Tunnel in the service bar.
   • The wizard automatically probes Local gateway ready and Access URL reachable (verifying that / serves the 401 pairing page and /lan-gate/admin returns 403).
2. Pair Phone / Browser (Web App):
   • On the Pair Phone / Browser (QR) tab, click Generate Pairing QR.
   • Scan the QR code with your phone camera or browser, enter the 8-character pairing code, and use "Add to Home Screen" to install DSH as a standalone PWA with lock-screen push notifications.
3. Pair Another Computer (Desktop Client):
   • Switch to the Pair Desktop Client tab, click Generate Desktop Pairing Code, and click Copy Server URL & Code to send to your other computer.

Quick actions after setup: once configured, you can directly click Pair Phone (QR), Pair Desktop Client, or Manage Devices (rename devices, switch device roles, revoke one or all devices, or send a test push) right from the overview card footer without re-running the wizard.

Scenario B: Set up another computer as Desktop Client

On the second computer running the DSH desktop app:

1. Open Plugins → dsh-zen-remote and click Start Setup Wizard.
2. Step 1: select Act as Desktop Client and click Next.
3. Step 2: enter a name for this computer (e.g. Living-Room-Mac), the host's gateway URL (https:// for public URLs, or http://192.168.x.x:3088 / http://100.x.x.x:3088 for LAN / Tailscale), and the 8-character desktop pairing code from the host, then click Pair & Connect.
4. Step 3: once all three status lights (Pairing token, Server connection, Session & plugin sync) turn green, the host's shared workspaces and sessions appear in your left sidebar immediately.

3. Daily Usage: Session Sharing & Cross-Device Workflow

Enabling or Disabling Remote Access on a Session

Remote access is controlled per session (or automatically enabled for new sessions if you turn on Auto-share new sessions in Step 2 of the wizard). You can toggle it from four places:

1. Host sidebar: open a session's "…" menu and click 开启远程 / 关闭远程 (Enable / Disable remote);

   

2. Host session header: click the globe icon in the session title row (hover to see remaining idle time; a dot indicates a desktop client is currently viewing it);

3. Phone (Web App) session info card: open the info card at the top right of a session and toggle 远程访问 (Remote access);

   

4. Host settings page: view and close shared sessions individually or all at once under the shared sessions list.

Working in Remote Sessions on a Desktop Client

• Sidebar groups: once a host workspace has at least one remote-enabled session, a "Server Name · Workspace Name" group appears in the client's sidebar. Click any session to view full history, stream responses, approve tools, use the server terminal, browse files and diffs, download deliverables, or drag-and-drop files to upload.

  

• Closing & idle sleep: a shared session automatically closes remote access after 48 hours (idleHours) of inactivity (mid-turn sessions or sessions waiting on approvals/questions never sleep). When remote access is closed—or when the client unpairs or its token is revoked—remote sessions are automatically archived/hidden from the sidebar; an actively open session displays a "remote closed" banner and recovers automatically if re-shared.

  

4. Lock-Screen Push: When Notifications Fire

Notifications fire only when you are actually needed, along two independent paths (all payloads are end-to-end encrypted with aes128gcm):

1. System-triggered (always on, never suppressed by debounce):
   • Tool waiting for approval: pushes "DSH needs your approval" with the tool name. Waits DSH_PUSH_APPROVAL_GRACE_MS (default 5s) before sending so fast auto-approver plugins can answer first without buzzing your phone.
   • ask_user_question waiting for your answer: pushes "DSH is waiting for your answer".
   • Works for both top-level sessions and subagent sessions across Web and Desktop hosts.
2. Model-triggered (push_notify tool):
   • Called by the agent when you asked to be notified upon completion, or when it hits a blocker that requires your decision.
   • Ordinary turn completions do not push by default (enable pushTurnEnd in advanced settings if you want a push after every turn; enable pushSummary to include up to 120 characters of the final reply in the notification body).

5. Features

• Mobile PWA UI (Host):
  • Two-level page stack (session list home + standalone session page with left-edge swipe back, Android back-gesture support, first-frame boot skeleton, and immutable asset caching)
  • Home-screen plugin entry chips (auto-discovered per installed plugin, individually toggleable)
  • Compact mobile composer with bottom sheets for permissions/models and direct phone attachment uploads
  • Session info card (6-tile stats, log export, rename, fork, archive, one-tap full-conversation PNG share image, and remote access switch)
• Unified Setup & Pairing Wizard (2.3):
  • Top-of-page 2×2 live overview card and 3-step modal wizard covering all four host ingress modes (Managed Caddy, Existing Reverse Proxy, Cloudflare Tunnel, LAN / Tailscale Direct) and Desktop Client pairing
  • Automatic download of prebuilt Caddy + caddy-dns/cloudflare and cloudflared binaries with mainland China network auto-detection, mirror acceleration (gh-proxy.com / ghfast.top), connect/stall failover watchdogs, and daily upstream release tracking via GitHub Actions
  • Automatic LAN / Tailscale IPv4 discovery and local network probing, backed by the gateway's private-IP wall (403 public-direct-forbidden) against accidental public exposure
  • Dedicated Manage Devices modal and automatic sidebar cleanup on client unpair/revocation
• Cross-Desktop Remote Sessions (Client):
  • Full-featured remote sessions in the sidebar: history, streaming, approvals/questions, server model catalog, file tree, changes summary/diff, server-side terminal, windowed artifact downloads, server-side LibreOffice PDF preview, up to 500 MiB file uploads, and drag-and-drop file upload interception
• Plugin Bridge:
  • Cooperative plugins and built-in adapters (such as dsh-better-sidebar) route their panel requests in remote sessions to the host machine (with explicit owner consent for whole-machine data). See Plugin Bridge Guide.

In depth: Interface Design · Public Access & Relay Protocol

6. Advanced Settings & Field Reference

Day-to-day setup and device management are handled entirely by the Remote Access & Device Pairing Wizard at the top of the dsh-zen-remote page. To fine-tune individual low-level fields, click dsh-zen-remote a second time under Included components on the plugin detail page.

View underlying component settings screenshots & full field reference table

Each field resolves in order: environment variable > plugin row settings > ~/.dsh/lan-gate.config.json > default. Saving a field that requires a gateway/push restart reloads the plugin row automatically without restarting the app.

Host Role & Pairing Cards	Shared Sessions List	Client Settings & Diagnostics

Field	Default	What it does
role	host	host runs gateway + push + sharing; client connects to a remote host
serverName	computer name	Device name (≤ 40 chars): sidebar group title on a host, registered device name on a client; syncs both ways automatically
port	3088	Gateway port; retries upward (up to +20) if occupied
host	127.0.0.1	Gateway bind address (127.0.0.1 for local proxy/tunnel, 0.0.0.0 for LAN/Tailscale direct)
targetPort	(auto)	Local DSH Web UI port; leave empty to auto-discover the host's listening port
rateLimit	120	Per-minute cap on unpaired requests per client IP
trustedProxies	empty	Comma-separated trusted proxy IPs when the reverse proxy runs on another machine
vapidSubject	mailto:admin@localhost	Web Push contact (must be a real mailto: or https:// URL for iOS delivery)
lang	auto	Gateway & notification language: auto (browser Accept-Language), zh, or en
pushTurnEnd	off	Also send a push when an ordinary turn finishes (approvals/questions always push)
pushEvents	agent/turn-stopping	Comma-separated events that count as turn end when pushTurnEnd is on
pushDebounceMs	15000	Minimum interval (ms) between automatic pushes
pushSummary	off	Include up to 120 chars of the final reply in notification bodies
pushTool	on	Register the model-callable push_notify tool
idleHours	48	Idle-sleep window in hours for shared sessions; range (0, 8760]
autoShareNewSessions	off	Automatically enable remote access on new sessions created on the host
pluginBridgeConsent	{}	Whole-machine data consent map (pluginName -> boolean) for the plugin bridge
serverUrl (client)	empty	Remote server gateway URL (https:// required for public hosts; http:// allowed on private LAN/Tailscale ranges)
deviceToken (client)	empty	Paired client token (secret field, redacted everywhere)
turnFoldDesktop	off	Enable turn-process folding on desktop widths as well as mobile
keyboardLiftRatio / keyboardLiftMaxPx / keyboardSafetyPadPx	0.42 / 400 / 15	Soft-keyboard lift calibration fallback for environments where the OS hides keyboard height
maxUploadBytes	20 MB	Mobile attachment upload cap

Legacy environment variables (outrank row settings): LAN_GATE_PORT, LAN_GATE_HOST, LAN_GATE_TARGET_PORT, LAN_GATE_RATE_LIMIT, LAN_GATE_TRUSTED_PROXIES, LAN_GATE_VAPID_SUBJECT, LAN_GATE_LANG, DSH_PUSH_TURN_END, DSH_PUSH_EVENTS, DSH_PUSH_DEBOUNCE_MS, DSH_PUSH_SUMMARY, DSH_PUSH_TOOL, DSH_PUSH_LANG, DSH_PUSH_APPROVAL_GRACE_MS.

7. Security Model, Version Tolerance & Known Notes

Security Model

• A paired desktop client is a trusted device: the remote session terminal runs as the host's OS user, file-preview endpoints can read files accessible to the host process, and the client can create sessions in any host workspace.
• Unshared sessions are strictly isolated at the relay: list rows, history, live events, approvals/questions, and embedded dsh-session: references for unshared sessions are filtered or refused server-side.
• Public direct-connection guard on 0.0.0.0: even when the gateway binds 0.0.0.0 for LAN / Tailscale mode, isPrivateOrLoopbackIp only admits direct connections from loopback, RFC1918 LAN ranges, link-local, and Tailscale (100.64.0.0/10 / fd7a:115c:a1e0::/48); any unproxied direct connection from a public internet IP is rejected with 403 public-direct-forbidden.
• Admin actions are local-only: minting pairing codes, changing device roles, running the setup wizard, and revoking devices are only permitted directly on the host machine.
• Data & privacy: the plugin reports nothing to any third party. Pairing state lives in ~/.dsh/lan-gate-state.json, shared sessions in ~/.dsh/zen-remote-shares.json, and Cloudflare tokens in 0600 files under ~/.dsh/zen-remote-ingress/.

Version Tolerance

1. Relay protocol version: both host and client must run the same dsh-zen-remote version.
2. DSH host version: DSH versions may differ between host and client. Normalized interface fingerprints are compared during handshake; any differing group is annotated "（版本有差异）" and degrades only the affected panel.

Known Limitations & Third-Party Plugin Support

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