dsh-3301
> Formerly published as dsh-proxy; the project and package are now dsh-3301.
Proxies your DeepSeek Harness (DSH) port to http://:3301 with added security, so you can access DSH from anywhere on the LAN — including your phone.
> ~~⚠️ DSH 1.1 only. DeepSeek Harness 1.2 added a local token verification
> that breaks this reverse-proxy approach (the proxy can no longer pass through
> to the GUI). This project targets DSH 1.1. If you're on 1.2+, a different
> access method is required.~~
>
> ✅ Updated: that limitation is solved. The project now also ships as a DSH plugin
> (identity dsh-3301) that works on current DSH — see
> Plugin form below. The standalone proxy remains supported.
English · 中文
Password-protected reverse proxy (HTTP + WebSocket) — and now also a DSH plugin (dsh-3301) — in front of a
DSH Web GUI.
DSH stays bound to 127.0.0.1 (loopback only, safe). This proxy binds to
0.0.0.0 so a phone on the LAN can reach it — behind a password. The plugin form starts with no password: set one, or leave the entry open. The plugin form starts with no password: set one, or leave the entry open. The plugin form starts with no password: set one, or leave the entry open.
> Zero-install dependencies — the standalone CLI is pure Node built-ins and the plugin reuses packages DSH already ships. Cross-platform (macOS / Linux /
> Windows × x86 / ARM) — verified on Windows; macOS/Linux follow from the platform branches in the code, but have not been tested on real hardware yet.
For agents (TL;DR)
A password-protected reverse proxy in front of DSH. DSH stays loopback-only;
this binds 0.0.0.0:3301 and forwards HTTP + WebSocket to it. Auth is a
signed cookie (30-day session), optional HTTPS, rate-limited. To run:
DSH_PROXY_PASS= node lib/cli.js. To stop on macOS:
launchctl bootout gui/$(id -u)/com.dsh.lan-proxy. See below for details.
> Plugin form — preferred on current DSH: node tools/deploy.mjs dsh-3301 (or
> dsh plugin --profile web add dsh-3301), restart DSH, then open http://:3301.
> There is no default password, and the settings card lives at
> Settings → Plugins → Plugin configuration → dsh-3301. Details below.
Plugin form (dsh-3301)
The standalone proxy below still works, but the supported way to run this on current DSH is as a
plugin, and the package/plugin identity is dsh-3301 (the npm name dsh-proxy is taken by
an unrelated LLM-gateway plugin).
- DSH itself stays bound to
127.0.0.1— it never listens on the LAN. - The plugin opens the LAN entry (
0.0.0.0:3301by default) inside the DSH process: no
separate daemon, no scheduled task, it starts and stops with DSH. - No default password. Until one is set the entry does not authenticate at all; leaving the
password field empty when saving clears it again. - The password is stored only as a salted scrypt verifier in
$DSH_HOME/dsh-3301/auth.json—
no plaintext is written — and changing or clearing it is loopback-only. - Login is a form (the password crosses the wire once per login, unlike Basic) with per-IP
failure lockout and a signed session cookie (30 days by default). - The session comes from the official
ctx.connection.authenticatedUrl()API — the plugin no longer
reads your credential file — and the client bootstrap is injected with
ctx.webServer.tapIndex(), i.e. before compression, so no HTML rewriting.
> ⚠️ Until you set a password, anyone who can reach port 3301 gets into DSH. Set one before
> exposing the machine: Settings → Plugins → Plugin configuration → dsh-3301, or
> http://127.0.0.1:3301/__gate/setup from the host itself.
# Today: clone and deploy (there is deliberately no npm package yet — see the note below)
git clone https://github.com/Aztech-Lab/dsh-3301
cd dsh-3301
node tools/deploy.mjs dsh-3301
> The first line people reach for — dsh plugin --profile web add dsh-3301 — needs an npm package,
> and none is published (by choice: the repository is the install source, and it has no build step).
> Use the clone-and-deploy path above until that changes.
> The deploy target is your DSH profile ($DSH_HOME/profiles/), which normally lives
> outside this repository. If the write is refused (EACCES: permission denied), grant that
> directory write access, or run the command as the user that owns $DSH_HOME.
Restart DSH afterwards, then open Settings → Plugins → Plugin configuration → dsh-3301:
| Field | Meaning |
|---|---|
| Enabled | turning it off releases the listening port |
| Bind host | 0.0.0.0 (LAN reachable) / 127.0.0.1 (host only) |
| Port | default 3301 |
| Username | login name on the gate form, default dsh |
| Session lifetime | session-cookie validity, default 30 days |
| Failure limit / lockout | per-IP lockout after repeated failed logins |
| Inject client bootstrap | adds __DSH_TRANSPORT__.ownsHost so a LAN page keeps host-backed settings |
| Password | write-only input: empty = clear; changing it requires the current password |
For first-run setup you can also open http://127.0.0.1:3301/__gate/setup on the host, and
http://127.0.0.1:3301/__gate/health reports the entry's state without authentication.
The card follows the shipped DSH plugin cards; its styling uses the declarations and theme
variables of DSH's own dsh-client-ui-settings-plugins package (BSD-3-Clause). All implementation
code here is original.
> The standalone CLI (node lib/cli.js, DSH_PROXY_* environment variables) is unchanged and still
> supported for running a proxy outside DSH.
Why
> This section describes the standalone CLI form; the plugin form above differs in auth (form login + scrypt) and needs no TLS of its own.
- DSH stays loopback-only — never exposed directly.
- Cookie-session auth — avoids the repeated Basic-Auth re-prompt that breaks
WebSocket/SSE-heavy apps. First request passes Basic Auth, then a signed
session cookie is issued; later requests (incl. WebSocket upgrades) are
accepted by the cookie. The session cookie persists 30 days (Max-Age), so
you don't re-authenticate on every browser restart. The proxy appends its
cookie to DSH's own Set-Cookie (e.g. language prefs) instead of overwriting
it, so DSH settings persist. - HTTPS (optional) — a self-signed cert encrypts the password/session on
the wire. - Rate limiting — locks out an IP after too many failed logins.
- Zero-install dependencies — the CLI is pure Node built-ins; the plugin reuses packages DSH already ships.
Run (standalone CLI)
> Running it as a DSH plugin is the path above.
DSH_PROXY_PASS=yourpassword node lib/cli.js
# or after installing the bin
DSH_PROXY_PASS=yourpassword dsh-3301
Then open http://:3301 from any device on the LAN.
Env (standalone CLI only — the plugin is configured from its settings card)
| var | default | meaning |
|---|---|---|
DSH_PROXY_PORT |
3301 |
listen port |
DSH_PROXY_HOST |
0.0.0.0 |
listen host |
DSH_PROXY_USER |
dsh |
basic-auth username |
DSH_PROXY_PASS |
(required) | basic-auth password |
DSH_UPSTREAM |
127.0.0.1:3080 |
upstream DSH host:port |
DSH_PROXY_SECRET_FILE |
os.tmpdir()/dsh-3301-secret |
session-signing secret file |
DSH_PROXY_CERT |
/tmp/dsh-3301-cert.pem |
HTTPS cert (enables TLS if present) |
DSH_PROXY_KEY |
/tmp/dsh-3301-key.pem |
HTTPS key |
HTTPS (recommended, standalone CLI only)
> The plugin's 3301 entry is plain HTTP — put TLS or a tunnel in front of it if the network is untrusted.
Generate a self-signed cert once, then the proxy serves HTTPS:
openssl req -x509 -newkey rsa:2048 -nodes \
-keyout /tmp/dsh-3301-key.pem -out /tmp/dsh-3301-cert.pem \
-days 365 -subj "/CN=dsh-3301"
Browsers will show a one-time self-signed warning — accept it once. The
password and session are then encrypted on the wire.
macOS launchd (auto-start, standalone CLI only)
> The plugin starts and stops with DSH, so no launchd entry is needed.
See com.dsh.lan-proxy.plist (template). Load it with:
launchctl bootstrap gui/$(id -u) /path/to/com.dsh.lan-proxy.plist
Manual stop / start
# stop (turn the proxy off)
launchctl bootout gui/$(id -u)/com.dsh.lan-proxy
# start again
launchctl bootstrap gui/$(id -u) /path/to/Library/LaunchAgents/com.dsh.lan-proxy.plist
# check status
launchctl list | grep dsh.lan-proxy
Security notes & risks
What's hardened:
- DSH stays loopback-only (never exposed directly).
- Auth is a HMAC-SHA256 signed cookie with constant-time comparison and
HttpOnly — tamper-proof and resistant to timing attacks.
- Rate limiting (5 failures → 5 min lockout) is on by default.
- HTTPS (when enabled) encrypts the password and session on the wire.
Known risks / things to be aware of:
- Weak / plaintext password — the default example uses a short numeric
password stored in plaintext in the launchd plist. Anyone who can read the
plist (or the process env) sees it. Use a strong, random password and
keep it out of plaintext config where possible.
- Self-signed cert — browsers show a one-time warning. The encryption is
real (RSA 2048), but the cert isn't from a trusted CA, so a MITM on first
connect is theoretically possible if the user blindly accepts without
verifying the fingerprint.
- LAN exposure — the proxy binds to 0.0.0.0; anyone on the LAN can
attempt access. The password is the only gate. On an untrusted network this
is not sufficient.
- No per-IP allowlist — access is password-only. If you need stricter
control, put this behind a VPN (e.g. Tailscale) or add an IP allowlist.
Recommended deployment:
1. Use a strong password (≥12 chars, mixed).
2. Enable HTTPS (self-signed is fine for a trusted LAN).
3. Put it behind a VPN (Tailscale/WireGuard) if the LAN isn't trusted.
4. Keep the password out of plaintext config (use a secret file with 0600
perms, or an env from a secure source).
Contributing
Contributions are welcome! Ideas that would help:
- IP allowlist / per-user access control.
- OAuth2 / SSO login (replace the password with an existing account).
- Proper TLS via mkcert or Let's Encrypt.
- Brute-force hardening (exponential backoff, persistent lockout state).
- Tests and CI.
- Better docs / translations.
Open an issue or PR — see the GitHub repo.
Acknowledgement
This work is conducted by Aztech Labs with DeepSeek Harness (Deepseek-V4.1-Flash).
License
MIT
