dsh-remote

Securely expose the DeepSeek Harness Web UI to remote browsers with a login gate, MFA/TOTP, role-based access, and an in-browser remote file panel. Users sign in from an external browser and get the full DSH experience without native dialogs on the host machine.

Designed for environments where dsh web already works locally. The plugin keeps the service on loopback by default; public access still requires an HTTPS reverse proxy or a secure tunnel.

Contents

• Features
• Screenshots
• Getting started
• Remote access
• Install as an app
• Configuration
• Headless servers
• FAQ
• Documentation
• Development and tests
• Uninstall
• Known limitations

Features

• Login gate: unauthenticated requests to every path are sent to the login page; /api and WebSocket traffic require a valid session. Passwords are scrypt-hashed, failed logins are rate limited, and the first admin is loopback-only.
• MFA / TOTP: works with Google Authenticator, 1Password, Authy, and other standard authenticators; supports QR binding and 10 one-time backup codes. An admin can disable MFA for an account.
• Sessions and roles: signed session cookies; admin-only mode by default, with optional admin / user / guest roles.
• Remote file panel: preview code, Markdown, images, PDF, video, audio, text, directories, and extracted .docx text in a right-side panel. Unsupported files download directly. Only the DSH home and working directories are readable by default; admins can add allowed roots.
• Remote access: works behind nginx, SSH tunnels, Tailscale, Frp, Cloudflare Tunnel, and similar transports with end-to-end WebSocket events.
• Installable as a desktop or phone app: the manifest, Service Worker, and icons are served before sign-in, so DSH installs into its own window on desktop and mobile, with the cookie repaired on a cold launch. See Install as an app.
• Browser-native workspace flow: selecting or creating a workspace uses an in-browser directory dialog instead of opening a host OS file picker.
• Localized and lightweight: follows DSH light / dark theme and language, with English and Chinese UI; remote responses are gzipped by default and hashed assets work well with edge caches.

Screenshots

Login gate (unauthenticated access)	Settings → Auth & Accounts

Getting started

1. Install

dsh plugin --profile web add @xgone/dsh-remote

2. Restart dsh web

Patches cannot hot-reload, so restart after installing or upgrading:

dsh web

3. Create the first admin

Open http://127.0.0.1:3080 in a local browser. The first visit enters bootstrap mode: enter a username and password (at least 6 characters) to create the first admin, then you are signed in automatically.

Server without a local browser? See headless servers.

4. Bind MFA (recommended)

Go to Settings → Auth & Accounts → Two-factor authentication (MFA) → Enable, scan the QR code with your authenticator, and enter the 6-digit code. Save the 10 backup codes first.

5. Enable remote access

Verify local login and MFA first, then configure a reverse proxy or tunnel as described in Remote access. External access must forward WebSockets; HTTPS deployments must also set session.secure: true.

Remote access

dsh web listens on the loopback address by default. Expose it through a reverse proxy or tunnel, and do not publish an unencrypted service port directly to the Internet.

The following nginx example preserves the WebSocket upgrade headers:

server {
  listen 8443 ssl;
  server_name dsh.example.com;
  ssl_certificate     /etc/letsencrypt/live/dsh.example.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/dsh.example.com/privkey.pem;

  location / {
    proxy_pass http://127.0.0.1:3080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header Origin $http_origin;
  }
}

SSH reverse tunnels, Tailscale, Frp, and Cloudflare Tunnel work the same way. For HTTPS deployments, set session.secure to true in the configuration.

Install as an app (PWA)

Since 0.3.6, DSH installs as an app in its own window — from the launcher, dock, or taskbar on desktop, from a home-screen icon on mobile — much like a native app.

Prerequisite: serve it over HTTPS. A Service Worker only registers in a secure context, so a plain http:// LAN address (an unencrypted domain, a bare IP) will not install; localhost / 127.0.0.1 is the one exception. The same applies to desktop and mobile alike.

Steps: open the deployed HTTPS URL in a browser and sign in once, then pick the entry point for your environment.

Firefox does not support manifest-based PWA installation, on desktop or mobile; with Firefox, just use DSH in a regular tab.

A separate route, unrelated to this section: Chrome / Edge on desktop and Safari on desktop can install any site as a standalone window without reading its manifest. That is not the same as the manifest-plus-Service-Worker PWA install above — don't conflate the two when troubleshooting.

Once installed, launching from the app icon runs it in its own window. The plugin already serves the manifest, Service Worker, and icons before sign-in, with the right MIME types, worker scope, and no-store; the dsh-auth cookie is re-minted only on authenticated page responses and injected into that same request, so a cold launch does not stop at the login page.

No nginx snippet is needed. All of the above is handled by the plugin itself, so keep the reverse-proxy config above as-is; just confirm the HTTPS certificate and session.secure.

Configuration

Edit the config of the remote row in ~/.dsh/profiles/web/cordis.patch.yml:

- id: remote
  config:
    enabled: true          # false = disable the gate (escape hatch if locked out)
    session:
      secure: false        # set true for HTTPS deployments
    adminOnly: true        # false = enable admin/user/guest roles
    bootstrap:             # optional: only while the account store is empty
      username: admin
      password: 'replace-with-a-strong-password'

See docs/REFERENCE.md for sessions, MFA, rate limiting, gzip, the file panel, allowed roots, and all other options.

Headless servers (no local browser)

Add the bootstrap block above to cordis.patch.yml and restart. The first admin is provisioned at startup, equivalent to local bootstrap. Remove the plaintext password after the first login and bind MFA.

FAQ

Documentation

• Changelog: CHANGELOG.md — version changes and upgrade compatibility fixes.
• Technical reference: docs/REFERENCE.md — architecture, implementation details, full configuration, and endpoint reference.
• Cloudflare Tunnel deployment: docs/CLOUDFLARE-TUNNEL.en.md — tunnel access without a public IP or open inbound ports.
• npm package: @xgone/dsh-remote.

Development and tests

pnpm install
pnpm check
pnpm test

pnpm test runs Node syntax checks and the complete test suite. GitHub Actions runs the same tests on Node.js 20, 22, and 24.

Uninstall

dsh plugin --profile web remove @xgone/dsh-remote

Restart dsh web to remove the gate. Account data remains in $DSH_HOME/auth/store.json; delete that file separately for a complete reset.

Known limitations

• Configuration changes require restarting dsh web; HMR is disabled on the web surface.
• All accounts share the same workspaces and session data. DSH core is single-tenant, so the plugin cannot isolate data; run one profile instance per person when isolation matters, for example dsh --profile alice --port 3081.

License

MIT