dsh-remote-control

English | 中文

Secure remote access to DeepSeek Harness (DSH) deployed on your own Mac or Linux server, from anywhere — Cloudflare Tunnel → password gate → DSH, with Feishu (Lark) notifications pushed to your phone whenever the entry URL or service state changes.

Browser ──HTTPS──▶ Cloudflare edge (Quick Tunnel: https://<random>.trycloudflare.com)
                        │  outbound-only connection, no inbound ports opened
                        ▼
                 cloudflared ──▶ Caddy (password gate, cookie session)
                        │  http://127.0.0.1:3080
                        ▼
                 DSH web profile (loopback only, zero modification)

Why

• No inbound ports — the machine only makes outbound connections through the tunnel.
• Password gate in front of DSH — login page + signed session cookie (7 days), per-IP lockout after 5 failed attempts. DSH itself stays untouched.
• Feishu notifications are a necessity, not a nice-to-have — Quick Tunnel assigns a new random URL on every start; without a push channel you lose the entry. Every start / URL change / failure / recovery is pushed as a card message, plus a separate copy-friendly password message.
• Survives DSH upgrades — the chain only talks HTTP to 127.0.0.1:3080; no DSH internal APIs are used.

Quick start

Requirements: macOS (x86_64 / arm64) or Linux (x86_64 / arm64), curl, python3. Windows is not officially supported — PRs welcome with real test evidence.

git clone https://github.com/oh-summy/dsh-remote-control.git
cd dsh-remote-control
scripts/install.sh     # downloads official cloudflared/caddy binaries, generates password

Install without git clone

Prefer a GitHub Release (no git):

# one-click install (latest release)
curl -fsSL https://raw.githubusercontent.com/oh-summy/dsh-remote-control/main/scripts/install-remote.sh | bash

# or a specific version
curl -fsSL https://raw.githubusercontent.com/oh-summy/dsh-remote-control/main/scripts/install-remote.sh | bash -s -- v0.3.0

The script downloads the official source tarball from GitHub Releases, verifies its SHA256 (integrity check — guards against corrupted downloads; it is not an authenticity proof, since the checksum ships from the same release), and runs install.sh (which fetches cloudflared/caddy for your OS/arch). All releases: https://github.com/oh-summy/dsh-remote-control/releases.

By default, dsh-web start auto-detects if DSH web is not running and starts it automatically. To disable this behavior, set RC_AUTOSTART_DSH=false in ~/.remote-control/rc.env. (If auto-start fails, check dsh-web logs dshweb or start DSH web manually with dsh web.)

DSH web (≥0.1.5) has its own signed-cookie authentication on top of the password gate. After you log in, remote-control automatically mints that cookie too — no extra step. If you ever see dsh web authentication required, the DSH credentials were unreadable at that moment (e.g. DSH just restarted): log in again once.

Then edit ~/.remote-control/rc.env:

• Primary notification channel (bot DM): set RC_FEISHU_OPEN_ID (your open id, ou_...). Requires lark-cli installed and configured with your Feishu app (lark-cli config init); the app's bot needs IM permission and must be able to DM you.
• Fallback channel: set RC_FEISHU_WEBHOOK (group custom-bot webhook) — works without lark-cli. If both are set, DM is used and webhook only on failure.

Start everything:

dsh-web start

start prints the URL and password, returns to the shell, and pushes a card + password to your Feishu DM. Open the URL, enter the password once — the cookie lasts 7 days.

Self-healing & process guard

• Resident watchdog: if caddy/auth die they are respawned in place (URL unchanged); if cloudflared dies the tunnel is rebuilt automatically (Quick Tunnel gets a new URL, a new card is pushed to Feishu). Retries back off 30s→600s; only after all attempts fail does it ask for manual intervention and enter a cooldown (no alert storm) — dsh-web start clears it.
• Boot autostart + guarded watchdog: dsh-web autostart uses launchd KeepAlive to guard the watchdog itself — the whole chain comes up at boot, and a killed watchdog is respawned at once. During a manual dsh-web stop the guard idles and never fights your commands.
• Upgrading: machines with autostart installed from ≤ v0.2.x keep the old launchd job after upgrading; run dsh-web install (or dsh-web autostart) once to switch it to the resident-watchdog mode. dsh-web autostart off also stops the watchdog.

Commands

Command	Purpose
dsh-web start	Start the chain, print URL + password (Feishu notified)
dsh-web stop	Stop everything
dsh-web restart	Restart (URL changes; new card is pushed)
dsh-web status	Component status + gate/upstream health
dsh-web logs [caddy|cloudflared|auth|watchdog|selfheal|notify|all]	Tail logs
dsh-web password	Print the access password
dsh-web url	Print the current entry URL
dsh-web install	Install / repair (binaries, config, credentials, CLI link)
dsh-web tunnel-setup	Guide to create Named Tunnel (fixed domain)
dsh-web rotate-password	Rotate access password (generate new + restart)
dsh-web autostart [off]	Install/remove launchd autostart (macOS)

Configuration — ~/.remote-control/rc.env

Variable	Default	Meaning
RC_UPSTREAM	127.0.0.1:3080	Upstream service to protect (any local HTTP service, not just DSH)
RC_LISTEN	127.0.0.1:4080	Caddy listen address (loopback only)
RC_FEISHU_OPEN_ID	—	Feishu open id for bot DM (primary channel)
RC_FEISHU_WEBHOOK	—	Group custom-bot webhook (fallback channel)
RC_NOTIFY_PASSWORD	full	full = password pushed as its own message; mask = last 4 chars only; any other value = no password message
RC_NOTIFY_NOTE	—	Custom text at the top of the notification card (above the URL); re-read on every notify, no restart needed
RC_TUNNEL_NAME	—	Named Tunnel name (optional, for fixed domain)
RC_TUNNEL_HOSTNAME	—	Named Tunnel hostname (optional, e.g. dsh.example.com)
RC_TUNNEL_PROTOCOL	http2	Tunnel transport protocol. Keep http2 if a proxy TUN (e.g. Clash Verge) runs on this machine — QUIC/UDP flaps with TUN routing and shows up as intermittent 502/530; switch to quic only on clean networks

Runtime data (password, token, logs) lives in ~/.remote-control/ with 600 permissions and never enters git.

Platform support

Platform	Status
macOS x86_64 / arm64	✅ developed & verified here
Linux x86_64 / arm64 (Ubuntu/Debian first)	✅ same installer, systemd units planned (M3)
Windows	❌ not officially supported; PRs welcome with real test evidence

Security notes

• DSH keeps binding to 127.0.0.1 only; the only public surface is the Cloudflare edge behind the password gate.
• Password: 128-bit random, stored locally with 600 permissions; failed logins lock the source IP for 5 minutes (HTTP 429).
• Session cookie is HttpOnly + SameSite=Lax, valid 7 days. To rotate: regenerate the password (scripts/gen-password.sh) and/or edit ~/.remote-control/session.secret, then dsh-web restart.
• Never commit rc.env, password, session.secret or rendered Caddyfile — .gitignore already covers them; CI plus review keep it that way.

Named Tunnel (fixed domain)

By default, Quick Tunnel assigns a random URL on every start. For a fixed domain:

# 1. Login to Cloudflare
cloudflared tunnel login

# 2. Create tunnel
cloudflared tunnel create my-dsh-tunnel

# 3. Route DNS
cloudflared tunnel route dns my-dsh-tunnel dsh.example.com

# 4. Edit ~/.remote-control/rc.env
RC_TUNNEL_NAME="my-dsh-tunnel"
RC_TUNNEL_HOSTNAME="dsh.example.com"

# 5. Restart
dsh-web restart

Or run dsh-web tunnel-setup for a guided setup.

Architecture

For system architecture, design decisions, and component interaction, see docs/architecture.md.

Roadmap

For milestone progress and what's next, see docs/roadmap.md.

Contributing

See CONTRIBUTING.md · 中文版. In short: CI must pass (shellcheck + syntax checks), scripts stay bash-3.2/POSIX compatible, platform-specific changes come with real test evidence.

License

MIT © 2026 Summy Wu (oh-summy)