dsh-vps

dsh-vps

A VPS deployment tool for DSH: it puts stock DSH, behind a login page, on your own VPS so you can use it from any browser. Pick either way to install:

① From a form in the DSH on your own computer: install the dsh-vps plugin from the plugin market (or run dsh plugin add dsh-vps), open Settings → VPS Deploy, enter the server IP, SSH port and username, pick how to log in (password / private key / this computer's key), plus a domain if you have one, and click "Install on this VPS".

② With one command on the VPS:

curl -fsSL https://raw.githubusercontent.com/AIcivilization/dsh-vps/main/install.sh | sudo bash -s

With a domain, or behind the GFW, append arguments at the end, e.g. bash -s -- --domain dsh.example.com --mirror cn. See Install below.

Overview

DeepSeek Harness (DSH) trusts the operator's own browser only: its privileged interfaces — settings, API keys, plugin management — sit behind a browser-trust fence, and a plain reverse proxy to the public internet leaves those pages dead.

dsh-vps puts a zero-dependency login gateway (dsh-gate) in front of DSH: public requests pass a scrypt login gate first, then the gateway performs DSH session authentication server-side and proxies the rest. You open a browser anywhere and get the stock DSH web interface — settings, models, API keys and the plugin marketplace all working.

Capabilities

Screenshots

Install on a VPS from a form in DSH	Uninstall from a VPS	"This server" on the VPS

Install done	Setup wizard	Wizard filled

Setup complete	Login gate	Logging in

Native DSH UI	Settings (works on a public domain)	Plugin marketplace

Requirements

• Ubuntu 22.04+ / Debian 12+ (root)
• 2 vCPU / 2 GB RAM or better; ports 80/443 open
• A domain gives you automatic HTTPS (point its A record at the server first); a public IP with a self-signed certificate works too

Install

Option 1: fill in a form in the DSH on your own computer

Works with DSH on Mac, Windows and Linux:

1. Add the dsh-vps plugin to DSH: search the plugin market, or run dsh plugin add dsh-vps
2. Open Settings → VPS Deploy and enter the server IP, SSH port and username and pick how to log in; add a domain if its A record already points at the server, and tick "Server is in mainland China" if it is
3. Click "Install on this VPS"

• Three ways to log in: password; private key (paste or choose the .pem from your cloud provider or your own id_ed25519, passphrase optional); this computer's key (generate a dedicated key with one click, then copy the public key — or the ready-made command — into your provider's web console once; keys already in ~/.ssh are tried too). Use one of the key options when the server has password login disabled (common after an OS reinstall)
• Passwords and pasted keys are used once and never stored; the dedicated key's private half stays on your computer
• The page streams the install log and ends with the setup-wizard link
• The install runs in the background on the server, so closing the page or losing the connection does not stop it
• Needs an OpenSSH client on your computer: built into macOS and Linux; on Windows 10/11 add "OpenSSH Client" under Settings → System → Optional features

Option 2: run one command on the VPS

curl -fsSL https://raw.githubusercontent.com/AIcivilization/dsh-vps/main/install.sh \
  | sudo bash -s -- --domain dsh.example.com

Add --mirror cn if you're behind the GFW (Node and DSH come from npmmirror).

No domain yet? Drop --domain and use the public IP:

curl -fsSL https://raw.githubusercontent.com/AIcivilization/dsh-vps/main/install.sh | sudo bash -s

The certificate then comes from Caddy's internal CA, so the browser warns "Not secure / certificate not trusted". That is expected — proceed anyway. Add a domain in the wizard later and Caddy switches to a real certificate. (The same applies to option 1 without a domain.)

Or install through npm, running exactly the scripts shipped in this package (pinned, no network fetch; needs Node 22+ on the machine):

npx dsh-vps-install install --domain dsh.example.com

To pin a release instead of main, replace main with the version tag and point later gateway fetches at the same tag:

curl -fsSL https://raw.githubusercontent.com/AIcivilization/dsh-vps/v1.7.0/install.sh \
  | sudo DSHVPS_RAW_BASE=https://raw.githubusercontent.com/AIcivilization/dsh-vps/v1.7.0 bash -s -- --domain dsh.example.com

If the final self-check reports that DSH is not ready yet, the setup link is still printed; the page shows startup progress and the actual error. Troubleshoot with journalctl -u dsh-gate -n 80 --no-pager.

Update

New installs get the latest official DSH. The installer takes the newest official version on npm (same rule as the upgrade prompt below: the higher of latest and next, published at least 12 hours ago); if it fails to install or start, it falls back to the version verified by this project automatically. To choose a version, append --dsh <version> to the install command, or --dsh verified for the verified one.

DSH itself follows official releases. The gateway checks npm for the newest official version (the higher of the latest and next channels) every 6 hours. When a newer one exists, a prompt appears in the bottom-right corner of the DSH page (also available under Settings → VPS Deploy); click "Upgrade now" and confirm. It backs up, installs the new version and runs a self-check, rolling back to the previous version automatically if the check fails — about 1–3 minutes in all. "Later" silences that version. A release is offered only 12 hours after it is published — upstream sometimes publishes the main package hours before its sub-packages, and upgrading in that window just fails. From the server you can also run:

sudo dsh-vps upgrade            # the version verified by this project
sudo dsh-vps upgrade --latest   # the latest official release (same as "Upgrade now")
sudo dsh-vps rollback           # back to the previous version

Updating the gateway itself (login page, proxy):

sudo dsh-vps update-gate

Machines installed before v1.5.0: run the one-command install above once more to get the in-page upgrade prompt (it enters repair/update mode; accounts and data are kept).

Uninstall

curl -fsSL https://raw.githubusercontent.com/AIcivilization/dsh-vps/main/uninstall.sh \
  | sudo bash -s -- --yes

Uninstall from the DSH on your own computer: Settings → VPS Deploy → "Uninstall from a VPS", enter the server login details, choose whether to keep DSH data and whether to remove Caddy too, and click "Uninstall from this VPS". DSH data is kept by default.

Or run the command above on the server. It removes the service, install directory, Caddy site block and the DSH data directory, packing a backup (Caddyfile included) to /root/dsh-vps-uninstall-<timestamp>.tar.gz first. The Caddyfile you had before installing is restored. --keep-data keeps the DSH data, --purge-caddy removes Caddy as well. Uninstall then install again gives you a clean environment.

First run

Installation ends with a setup link carrying a one-time token (printed in the terminal for the command-line install, shown on the settings page for the form install) — open it to reach the wizard (opening the bare IP or domain only shows a "setup token required" page, by design): admin username/password → (optional) domain, DeepSeek API key & bundled plugins → log in. The wizard only answers to holders of the token, and the token is voided once setup completes. Lost the link? Print it again:

sudo dsh-vps setup-url

Skipping the API key is fine; you can add it later via the "Add API key" prompt or Settings → Models → DeepSeek.

The plugins install in the background (tens of seconds), always at their latest npm version, and DSH restarts to activate them. Three of them:

• dsh-vps (this project, required): the Settings → VPS Deploy page in DSH with three tabs — "This server" (DSH version with one-click upgrade, gateway status and access mode, common server commands), "Install on a VPS" and "Uninstall from a VPS" (install DSH on, or remove it from, another VPS over SSH). In the DSH on your own computer it shows only the last two. The page follows the language chosen in DSH under Settings → General → Language (DSH currently ships Chinese and English) and switches instantly; so does the in-page upgrade prompt

• dsh-market: browse, search and install community plugins and themes from Settings. Everything else is left to you — add whatever you want from the marketplace afterwards

• dsh-vps-manager: manage this very VPS from inside DSH — /vps- queries that skip the model and cost no tokens, a terminal in the conversation, AI operations confirmed by risk level, and a recipe library. Add this machine under Settings → VPS Manager (SSH key login)

Management

sudo dsh-vps status        # service status + health + version hints
sudo dsh-vps restart       # restart (DSH restarts and re-exchanges its session)
sudo dsh-vps upgrade       # upgrade DSH to the latest verified version (backup → self-check → auto rollback)
sudo dsh-vps update-gate   # pull and restart the gateway code itself (no git repo on the VPS)
sudo dsh-vps ownshost on   # apply the settings-page patch (restores settings on a public domain)
sudo dsh-vps selfcheck     # run the regression self-check (login / RPC / WebSocket / session)
sudo dsh-vps rollback      # switch back to the previous DSH version
sudo dsh-vps reset-admin   # emergency reset if you lose the admin password (re-runs the wizard, new token, signs out every session)
sudo dsh-vps setup-url     # re-print the setup link with its one-time token
sudo dsh-vps backup        # back up data (keeps the latest 3)

The Caddy site block is generated by gate/site-block.js — installation and domain changes share that one template.

How it runs

Both DSH and the gateway bind to 127.0.0.1 only, the user's browser never sees DSH's session cookie, and every request is proxied through after the gateway authenticates it.

• Self-healing startup: during first boot and plugin installs the page shows "DeepSeek Harness 正在启动", polls health every 3s and reloads itself as soon as the session is ready.
• Settings availability: DSH's frontend decides "is this the operator's own browser" from the page hostname and hides settings on a public domain. The gateway serves the officially supported __DSH_TRANSPORT__.ownsHost declaration alongside the page, which restores settings, models, API keys and permission policies. --trusted-host only opens the network fence — the two are separate gates.
• Marketplace restart: "restart now" is handled by the gateway — it strips Caddy's X-Forwarded-For (which trips DSH's loopback check and 403s) and restarts the DSH child process it owns, keeping session exchange intact.
• Troubleshooting entry points: sudo ss -ltnp | grep 3080 finds stale DSH processes; curl -s http://127.0.0.1:3100/gate/health on the server reports lastError, lastExit and crashStreak (that endpoint answers only to the server itself or an authenticated session).

Repository layout

License

MIT