dsh-remote-hub

dsh-remote-hub

Multi-host remote workspace hub for DeepSeek Harness — extended from KyoMio/dsh-zen-remote (v2.4.2, MIT). Combines the mobile PWA gateway & multi-host session relay with a desktop Local / Remote / All workspace scope switcher, remote folder browser & workspace creation, model & API credential sync, and bidirectional cross-host @ session reference bridging.

中文文档

Coexistence Note & Attribution: dsh-remote-hub builds upon KyoMio/dsh-zen-remote (v2.4.2, MIT) and preserves full wire & state compatibility (~/.dsh/zen-remote*) so existing paired hosts and shared sessions work without re-pairing. Disable or uninstall dsh-zen-remote before enabling dsh-remote-hub (only one zenRemote provider can run per DSH profile).

Key Enhancements over dsh-zen-remote

• Host-Scoped Sidebar Switcher: Switch cleanly between Local, individual paired remote hosts (with live online/connecting/offline status dots), and All unified view; scopes the top New Session button to the active host and keeps 0-session workspaces visible immediately.
• Remote Directory Browser & Workspace Manager: Intercepts Add Workspace (Ctrl+O) to browse remote host directories, toggle hidden folders, create subdirectories (mkdir), and open/rename/delete remote workspaces directly from the desktop client.
• Bidirectional Cross-Host @ Session References: Query and @-mention sessions across your local machine and paired remote hosts (dsh-session: URI surface staging), with automatic host-tag labeling and plain-text UUID mention upgrading.
• Model Provider & Credential Sync: Edits to custom LLM providers, endpoints, and API credentials on the client automatically mirror to connected remote hosts (adapting loopback/LAN gateway addresses) and trigger live model catalog refreshes.

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 as Desktop Client (Connect up to 8 Hosts)
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

If you previously installed dsh-zen-remote, disable or uninstall it first — dsh-remote-hub reuses your existing ~/.dsh/zen-remote* state and pairings automatically.

Install from the UI (Desktop App & Web UI)

Open the Plugins page in the DSH sidebar → search dsh-remote-hub in the Plugin Market (or click Add plugin and paste the GitHub Release tarball URL https://github.com/reshdh/dsh-remote-hub/releases/download/v1.0.0/dsh-remote-hub-1.0.0.tgz) → click Enable now, then restart DSH.

Install from the CLI (Headless dsh web server)

dsh plugin --profile web add https://github.com/reshdh/dsh-remote-hub/releases/download/v1.0.0/dsh-remote-hub-1.0.0.tgz
# then restart dsh web (or run `dsh-remote-hub setup` to configure and pair)

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.

Headless Server CLI Wizard (dsh-remote-hub)

The plugin ships a bundled CLI tool so remote VPS / headless servers (dsh web) can complete the entire setup, ingress configuration, three-light verification, and QR / desktop pairing flow in a terminal without opening a browser:

dsh-remote-hub setup            # 3-step interactive wizard: role → ingress → verify + terminal QR & desktop pairing
dsh-remote-hub status           # current role, gateway & connection state (--json; --debug exports redacted diagnostics)

# Host commands (when role is host)
dsh-remote-hub host device pair --device-role web              # mint a phone/browser pairing code + terminal QR (or desktop-client)
dsh-remote-hub host device list                                # list paired devices (--json supported)
dsh-remote-hub host device revoke <id|--all> [--yes]           # revoke one or all paired devices
dsh-remote-hub host ingress start --mode lan                   # configure & start ingress (caddy | cloudflared | external | lan)
dsh-remote-hub host ingress stop [--yes]                       # stop managed Caddy / Cloudflare Tunnel processes
dsh-remote-hub host ingress verify [--no-wait]                 # three-light check + mint web QR & desktop pairing codes
dsh-remote-hub host ingress snippet [--proxy nginx|caddy|lucky] # print reverse-proxy config snippets

# Client commands (when role is client, up to 8 paired hosts)
dsh-remote-hub client pair http://192.168.1.2:3088 --code 12345678 [--name My-Mac]
dsh-remote-hub client list                                     # list all paired hosts (up to 8) and connection states
dsh-remote-hub client unpair <hostUrl|entryId|--all> [--yes]   # remove one or all paired hosts

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

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 up to 8 hosts simultaneously, and mounts their 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 (or run npx dsh-zen-remote setup on a headless server):

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

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

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

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.
• Existing Reverse Proxy: enter the external https:// URL and copy the generated Nginx / Caddy / Lucky configuration snippet.
• LAN / Tailscale Direct: confirm the auto-detected http://<your-LAN-or-Tailscale-IP>:3088 address.

Step 3: Verify Connectivity & Pair Devices

1. Start Ingress Service & Auto-Probe: click Start Caddy or Create & Start Tunnel if applicable; the wizard automatically checks Local gateway ready and Access URL reachable.
2. Pair Phone / Browser (Web App): on the Pair Phone / Browser (QR) tab, click Generate Pairing QR, scan with your phone, enter the 8-character code, and use "Add to Home Screen" to install DSH as a standalone PWA with lock-screen push.
3. Pair Another Computer (Desktop Client): switch to the Pair Desktop Client tab, click Generate Desktop Pairing Code, and click Copy Server URL & Code.

Quick actions after setup: once configured, you can directly click Pair Phone (QR), Pair Desktop Client, or Manage Devices right from the overview card footer without re-running the wizard.

Scenario B: Set up as Desktop Client (Connect up to 8 Hosts)

On another computer running the DSH desktop app (or via dsh-zen-remote client pair <hostUrl> --code <8-char-code> on the CLI):

1. Open Plugins → dsh-zen-remote and click Start Setup Wizard (or + Add Server if already in client mode).
2. Step 1: select Desktop Client and click Next.
3. Step 2: enter this computer's display name (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.
5. Multi-Server Management (up to 8 hosts):
   • Click + Add Another Server in Step 3, + Add Server on the overview card, or Manage Servers to view per-server status, Reconnect, Re-pair, Remove, or Remove All (when all 8 / 8 slots are full, a red limit notice appears; re-pairing an existing URL still overwrites in place).
   • Sidebar groups from all paired hosts merge in pairing order after your local workspaces. Duplicate host names are automatically numbered Name-1, Name-2; model pickers, connection status icons, read-only banners, plugin bridges, and file uploads are strictly isolated per host serverId.

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). 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 green 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 (up to 8 paired hosts, stacked in pairing order). Click any session to view full history, stream responses, approve tools, use the server terminal, browse files and diffs, preview inline images, download deliverables, or drag/paste/pick files to upload.

  

• Closing & idle sleep: a shared session automatically closes remote access after 48 hours (idleHours) of inactivity (running or waiting sessions never sleep). Closed or unpaired 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; toggle pushEnabled to disable all notifications and unregister push_notify, or enable pushSessionName to show Session: <name> on the first line of the notification body):

1. System-triggered (always on when pushEnabled is on, never suppressed by debounce):
   • Tool waiting for approval: pushes "DSH needs your approval" with the tool name after DSH_PUSH_APPROVAL_GRACE_MS (default 5s, so fast auto-approvers can answer first without buzzing your phone).
   • ask_user_question waiting for your answer: pushes "DSH is waiting for your answer".
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 if wanted; enable pushSummary to include up to 120 characters of the final reply).

5. Features

• Mobile PWA UI (Host): two-level page stack (session list home + session page with swipe-back and Android back-gesture support, first-frame boot skeleton, immutable asset caching), auto-discovered plugin entry chips, compact mobile composer with bottom sheets and phone attachment uploads, and a session info card (6-tile stats with tok/s output speed, log export, rename, fork, archive, one-tap full-conversation PNG share image, and remote access switch).
• Unified Setup Wizard & Headless CLI (dsh-zen-remote): top-of-page 2×2 live overview card, 3-step modal wizard, and a full-featured terminal CLI (setup / status / host / client) covering all four host ingress modes (Managed Caddy, Existing Reverse Proxy, Cloudflare Tunnel, LAN / Tailscale Direct with private-IP wall) and client pairing.
• Cross-Desktop Remote Sessions & Multi-Server Pool (Client): connect up to 8 main servers simultaneously in pairing order; supports full history & live streaming, approval/question sync, per-server isolated model catalog, file tree & Git diffs, duplex server-side terminal (terminal/attach), inline Markdown image & media forwarding, windowed artifact downloads, server-side LibreOffice PDF preview, up to 500 MiB file uploads (drag-and-drop, paperclip picker, and paste), and one-click redacted diagnostics export.
• Plugin Bridge: cooperative plugins and built-in adapters (such as dsh-better-sidebar 0.25.0–0.30.1) route their panel HTTP and WebSocket 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 (or npx dsh-zen-remote setup). To fine-tune individual low-level fields, click dsh-zen-remote a second time under Included components on the plugin detail page.

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

7. Security Model, Version Tolerance & Known Notes

• Trusted client & strict session isolation: a paired desktop client runs terminals and file previews as the host's OS user, while unshared sessions are strictly filtered and refused at the relay layer. Even when binding 0.0.0.0 for LAN/Tailscale, the gateway's private-IP wall rejects any unproxied public internet IP (403 public-direct-forbidden), and all admin/wizard mutations are restricted to the host machine itself.
• Version tolerance: both ends must run the same dsh-zen-remote version; DSH host versions may differ (interface fingerprints are compared at handshake and degrade only mismatched panels).

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