dsh-pocket-relay

DSH Pocket Relay

English | 中文

Put DeepSeek Harness in your pocket: scan a QR code on your LAN, or reach it from anywhere through the relay on your own server — with per-device auth and multi-PC coexistence/failover.

Based on shaobeichen/dsh-pocket (GPL-2.0). This fork replaces the cloudflared public tunnel with a self-hosted relay (single Go binary server + web admin), and adds device authentication and multi-PC management.

⭐ A Star would make the author's day  ·  Here, take one

What is this

You want to use DeepSeek Harness on your computer, even when you're not at the computer.

• On your way home, the agent is running a task on your computer — pull out your phone and see where it is, what it produced.
• Out and about, you want the agent on your computer to look something up or write a snippet — no remote desktop, no SSH.
• The computer is at home or in the office, you're elsewhere, and you want to drive your DeepSeek Harness from your phone — send tasks, watch the output, tap approvals.

That's what DSH Pocket does: install it, scan a QR code, and your phone shows and controls the DeepSeek Harness UI in real time — from anywhere.

What it looks like — the phone shows the exact same UI as your computer, live:

✨ Features

🚀 Usage

Where the entry is: after installing and restarting dsh web, open Settings — the left sidebar shows "Phone access" at the top level (same level as General / Models):

Prerequisite: DeepSeek Harness installed. If your terminal says dsh: command not found, install it first:

npm install -g @deepseek-ai/dsh     # global install; verify: dsh --version
# No global install? Prefix every command with: npx @deepseek-ai/dsh

# 1. Install the plugin (everything in one package)
dsh plugin --profile web add dsh-pocket-relay -w

# 2. Restart dsh web
npx @deepseek-ai/dsh web

LAN (same Wi-Fi)

Settings → Phone access → scan the "📶 LAN" QR code → enter the LAN PIN (shown in the LAN block; hit Refresh to roll a new one, or Customize to set your own fixed 8 digits) → the phone opens the exact same DSH, in real time.

The "LAN access" switch is on by default and can be turned off/on with one click (a confirmation dialog shows each time). Off kills the LAN QR code and link instantly (phones can't open them); public access is unaffected. Tap "On" to restore it.

The LAN PIN is on by default (security-first). If you're the only user and find typing it every time annoying, flip "LAN access PIN" to Off in the LAN block — LAN scans then connect directly with no PIN (LAN-only devices; the public tunnel always requires a PIN, unaffected).

After logging in once, the phone won't ask again: as long as the computer's dsh web keeps running, reopening the phone needs no PIN (a dsh web restart/update asks for it once more).

Advanced option: auto-detection may not pick a reachable address for Tailscale/VPN setups. You can select a detected IP from the "LAN address" dropdown; normally no change is needed.

Public (from anywhere)

On the same page click "Enable anywhere" → a security disclaimer pops up every time — check "I understand and agree" to proceed (on a corporate/classified network, confirm compliance first) → wait for the tunnel (first run downloads cloudflared; macOS/Linux use the Tsinghua mirror, seconds) → scan the "🌐 Public" QR code → the phone opens the link and enters the 8-character PIN (shown in the settings page's public section; rotated on every tunnel start by default, or Customize it to a fixed PIN — letters and digits — that is never rotated) → works from outside (4G / office network).

Upgrading: dsh plugin --profile web update dsh-pocket-relay --latest -w (--latest is required across major versions — a ^0.x range won't auto-jump to 1.x).

Fixed public hostname (named tunnel, optional)

The default "quick tunnel" gets a new random URL on every restart. For a fixed public address, use a Cloudflare named tunnel (requires a Cloudflare account + your own domain):

1. In Cloudflare Zero Trust → Networks → Tunnels, create a Tunnel and copy the Tunnel Token
2. In that Tunnel's Public Hostname, point your domain (e.g. pocket.example.com) to http://127.0.0.1:3081
3. Back in the settings page's public section: switch the mode to "Named tunnel", paste the Tunnel Token, enter the fixed hostname, and save
4. Click "Enable anywhere" → the public address is now your own hostname and survives restarts

Note: in named-tunnel mode the public PIN is not auto-rotated (the address is fixed, so the PIN stays the same across restarts) — manage it proactively with a custom PIN. The Tunnel Token is stored locally only ($DSH_HOME/dsh-pocket/settings.json, readable by your user only) and is never echoed back in the UI.

⚠️ Security (read first)

• DSH can execute code on your computer. LAN QR/URL plus its own 8-character PIN is the key (PIN on by default, switchable off — then LAN scans connect directly, same-network devices only) — never share the LAN QR, URL or PIN.
• Read and accept the security disclaimer before enabling public access (the dialog shows on every enable; the server enforces it, so it can't be bypassed): public = exposing a code-executing DSH to the internet — use a strong PIN, turn it off when done, never on classified networks.
• Public access is protected by an 8-character PIN: the link is random, the PIN rotates on every tunnel start by default, and old links die instantly — even a leaked link can't get in. A custom PIN is never auto-rotated (your value stays stable; custom PINs may use letters and digits).
• Phone login state is tied to the computer's dsh web process: no re-entry while dsh web stays up; one re-entry after a restart/update.
• Login rate limiting (anti brute-force): 5 consecutive wrong PINs from the same IP lock it for 60s; a global failure threshold briefly locks everyone (blocks distributed IP-rotation scans); a successful login resets the counter.
• The public URL is randomly assigned by cloudflared and changes on every restart (old links die automatically — a natural key rotation); in named-tunnel fixed-hostname mode the address stays and the PIN is not auto-rotated — manage it with a custom PIN.
• Public detection is fail-closed (issue #66): everything except loopback and private LAN addresses is treated as public and PIN-gated — including any self-hosted tunnel / reverse proxy pointing at the local port with its own hostname. There is no "change the domain to bypass the PIN" hole.
• LAN mode exposes nothing publicly; only devices on the same network can reach it.
• Built for personal use; the public PIN lives in $DSH_HOME/dsh-pocket/token (re-rolled per tunnel start unless customized), the LAN PIN in $DSH_HOME/dsh-pocket/token-lan (refreshed manually in Settings), and switches/custom flags in $DSH_HOME/dsh-pocket/settings.json.

💻 DSH Desktop

• In the desktop app, QR screen-mirroring works; update/restart are managed by the desktop app (auto-disabled here).
• ⚠️ The desktop advanced mode doesn't support phone access yet (it disables the web layout; the phone gets no layout service → blank screen). Switch back to compatibility mode and restart; phones opening an advanced-mode page will see a clear notice overlay.

🩹 Troubleshooting (traps users step on)

⚠️ Public tunnel troubleshooting (read first)

Symptom: after clicking "Enable anywhere", the public URL shows error 1033 (Tunnel error) on the phone.

Most common cause: a local proxy/VPN (Clash, Surge, v2ray, sing-box, etc., especially in TUN mode). Such tools take over all traffic and often cut cloudflared's tunnel-edge connections (*.argotunnel.com, Cloudflare edge IPs), so the tunnel registers but the data plane never connects.

Fix (try in order, lightest first):

1. First just turn off the proxy's TUN mode — no need to quit the proxy; this is enough in most cases:
   • Clash: turn off the "TUN mode" toggle in Settings (or right-click the menu-bar icon → uncheck TUN mode)
   • Surge: turn off "Enhanced mode"; v2ray/sing-box: turn off "virtual NIC / route takeover"
   • Then go back to the settings page and click "Enable anywhere" again
2. If that's not enough, temporarily fully quit the proxy (not just close the window: quit Clash from the menu-bar icon; if a background service is installed, stop it in the service manager and confirm with ps aux | grep clash), then retry.
3. Add DIRECT rules to the proxy for the tunnel domains and Cloudflare edge (Clash example):

   - DOMAIN-SUFFIX,argotunnel.com,DIRECT
   - DOMAIN-SUFFIX,trycloudflare.com,DIRECT
   - IP-CIDR,198.41.192.0/24,DIRECT,no-resolve
   

4. If the network really can't reach the tunnel, use LAN mode: turn on the phone hotspot → connect the computer to it → scan the LAN QR. Same experience, from anywhere.

Other causes: corporate firewalls / campus networks blocking outbound — ask IT to allow it, or use a hotspot.

First run: "Downloading cloudflared" fails or hangs:

• macOS/Linux: the plugin first downloads from the Tsinghua mirror (measured ~3MB/s, done in seconds); falls back to official GitHub + acceleration mirrors if it fails.
• Windows: no Tsinghua mirror (Homebrew doesn't support Windows) — downloads the ~50MB exe from GitHub directly; single-threaded, so it's slower — that's expected, wait a few minutes, or use a proxy.
• If all sources fail, the settings page shows a hint. Alternatives (any one):

1. Install the cloudflared command and retry (the plugin then uses the PATH binary, no download):
   • macOS: brew install cloudflared; Linux: sudo apt install cloudflared or from the official site
   • Windows: winget install cloudflared or from the official site
   • Any platform: npm i -g cloudflared
2. Enable a proxy (system proxy / Clash etc.) and click "Enable anywhere" again
3. Manually download the binary into $DSH_HOME/dsh-pocket/bin/ ($DSH_HOME is usually ~/.dsh, on Windows %USERPROFILE%\.dsh; name it cloudflared (add .exe on Windows) or the release asset name — both are recognized)

🗂 Architecture (single package)