dsh-network

DSH Network

English | 简体中文

Securely connect to one DeepSeek Harness Host over your LAN, Tailnet, or public HTTPS route.

dsh-network is an independent DSH Host plugin. It keeps DSH bound to 127.0.0.1, places an authenticated gateway in front of it, and gives every Host a persistent hostId so clients can merge multiple routes to one Host.

What it gives you

• One Host, multiple routes — use a local address at home, a private Tailscale

address away from home, or your own public HTTPS endpoint without creating duplicate Hosts in the client.

• Scan-to-pair access — create a short-lived, single-use QR code from the

terminal or the DSH Settings page.

• Credentials designed for clients — access and refresh credentials rotate;

only hashes are persisted by the Host.

• Smaller long-session responses — optional history chunk trimming removes

redundant streaming deltas while preserving the messages rendered by DSH.

• No public exposure of DSH itself — the core Web server stays on loopback;

remote traffic goes through the authenticated gateway.

Quick start

dsh plugin --profile web add dsh-network@next
dsh web

The plugin starts its authenticated gateway on port 3081. DSH itself remains on loopback port 3080.

In another terminal, run the setup assistant. With no mode supplied it always asks which route to place in the QR code; it never silently selects one:

dsh plugin --profile web exec dsh-network setup

# 1. LAN / home network
# 2. Tailscale / Tailnet
# 3. Custom address

Scan the generated QR code with your client. For LAN setup, the phone and Host must be able to reach each other on the same trusted network.

Optional iOS download card

Once the iOS app has a real App Store or TestFlight HTTPS URL, set iosAppDownloadURL in the dsh-network plugin config. The local Web client then shows one small, dismissible download card on its first eligible browser launch. It uses DSH's additive shell.overlay slot and never replaces or reflows the application shell. With no URL configured, no card is shown.

# ~/.dsh/profiles/web/cordis.patch.yml
- id: dsh-network
  config:
    iosAppDownloadURL: https://apps.apple.com/app/id6802863224

History chunk trimming

Long agent turns emit a huge number of streaming assistant/chunk frames (a single turn can produce 95k+ deltas), and every history read serializes all of them — a 50-message tail can weigh tens of megabytes. dsh-network shadows /api/session.history and /api/subagents.history with exact routes and removes the chunks that never surface as display rows: settled steps are fully replaced by their final assistant/message, so only the in-progress step's partial and each settled step's first token-delta (for first-token timing) are kept. The response is otherwise byte-identical, hasMore/projections are untouched, and both the Web GUI and the iOS client fold the trimmed page the same way they fold the full one — typically 80–95% smaller over the wire.

Enabled by default; disable it or tune the fence in the plugin config:

# ~/.dsh/profiles/web/cordis.patch.yml
- id: dsh-network
  config:
    gatewayPort: 3081
    historyChunkTrim: false        # set false to serve the untrimmed page
    # historyTrustedHosts:         # mirror client-connection trustedHosts when
    #   - 192.168.1.5:3080         # the web server binds 0.0.0.0 and clients
    #                             # reach it directly by LAN address

The trim routes reuse the same Host/cross-site/origin fence as the core /api route; requests that would have been refused there are refused here too.

Settings page

The plugin also contributes a Network page to DSH Settings (via the settings.section slot). It shows the Host identity, gateway address, and paired-device count, and can mint a fresh pairing QR right from the browser — no terminal needed. Leave the address field empty to auto-detect the LAN URL, or paste a Tailnet / public HTTPS URL to place that route in the QR code.

Choose a connection route

Pair on the LAN

With the DSH Host running, generate a QR containing a private LAN address and scan it in the iOS app:

npx dsh-network setup lan

Use --url http://HOST:3081 if the machine has multiple private interfaces and the automatically selected address is not the one the phone can reach. LAN mode authenticates the client but uses the trusted local network for transport; do not use its HTTP URL over the public internet.

Configure a Tailnet

Tailscale must already be installed and signed in. This command configures Tailscale Serve to forward the private MagicDNS HTTPS URL to the authenticated gateway, then prints a pairing QR code:

npx dsh-network setup tailscale

The QR code supplies the MagicDNS URL to the iOS app once; the app then remembers the route.

Custom address

Choose option 3 in the setup assistant and paste an address that already reaches the authenticated gateway, or provide it explicitly:

npx dsh-network setup custom --url https://dsh.example.com

Public HTTPS Host

Public discovery is intentionally unsupported. Put port 3081 behind a trusted HTTPS reverse proxy, then generate a QR code containing that URL:

npx dsh-network pair --url https://dsh.example.com

Do not expose DSH port 3080 itself. Public mode requires TLS and should also use provider firewall and rate-limit controls.

The plugin does not install or edit a reverse proxy, container, firewall, certificate, DNS record, or hosting panel. It only accepts the working HTTPS address that the user already operates. See docs/internet-compatibility.md for the public Host boundary.

Credential lifecycle

1. The QR contains a random, single-use pairing ticket valid for five minutes.
2. Pairing issues a device refresh credential and a one-hour access token.
3. The client refreshes automatically and both credentials rotate.
4. Only credential hashes are stored under ~/.dsh/network/state.json.
5. Pairing links are generated on demand and are never broadcast.

When an authenticated iPhone browser opens DSH, the web client can mint a new one-minute, app-only ticket and hand the same Host to the DSH iOS app. Browser cookies and iOS Keychain credentials remain separate.

The gateway rate-limits pairing attempts. Device listing and revocation will be exposed in the DSH settings UI before a stable release.

Platform support

LAN setup uses ordinary HTTP addressing and Tailnet setup uses Tailscale's HTTPS Serve. Linux and Windows may require allowing the DSH process through the host firewall for TCP 3081 on trusted private interfaces.

Troubleshooting

• The phone cannot open the LAN address: make sure both devices are on the

same network, allow inbound TCP 3081 in the Host firewall, and rerun setup with --url http://HOST:3081 if auto-detection chose the wrong interface.

• Tailscale setup fails: install Tailscale, sign in, and confirm that

tailscale status works before running setup tailscale again.

• A public URL does not connect: verify that the reverse proxy forwards both

HTTP and WebSocket traffic to port 3081, and that its TLS certificate is trusted by the client.

• A QR code expired: generate another one. Pairing tickets are deliberately

single-use and valid for five minutes.

For the exact public deployment boundary, see docs/internet-compatibility.md.

Development

npm test
npm run check

License

MIT © Xiang Bai