DeepSeek Harness on a VPS: keep it private
Install the DeepSeek Harness on a Linux VPS, pin the npm version, understand what a plugin can do, and reach the port 3080 web UI over an SSH tunnel.
What the DeepSeek Harness is
The DeepSeek Harness (dsh) is a Node.js agent runtime you can run on a VPS (virtual private server), and the safe way to run it is bound to 127.0.0.1 with your browser reaching it through an SSH (secure shell) tunnel. It serves a web UI (user interface) on port 3080 instead of living in a terminal. In the 0.1.0-rc.6 release this guide pins, that web server asks for no password of its own, so a published port 3080 hands anyone who finds it an agent that reads your files and runs commands as your Linux user. Newer releases, from 0.2.0-rc.2 through 0.2.2-rc.2 of 11 November 2026, the newest release GitHub lists on 12 November 2026, print a startup URL carrying a fresh token for that process and swap it for a session cookie, but they still listen on loopback by default and still refuse to bind every interface.
DeepSeek publishes it under the MIT licence, as the npm package @deepseek-ai/dsh. The project describes itself as a developer preview and states that compatibility-breaking changes are expected. The pinned version below is the August 2026 release. On 12 November 2026 npm's latest tag names 0.2.2-rc.1. GitHub lists the newer prerelease 0.2.2-rc.2, tagged dsh-v0.2.2-rc.2 and released on 11 November 2026. Check the repository before you copy any of it onto a box that matters.
One idea runs through the whole design: everything is a plugin. The model adapter, the tool registry, the session log, the sandbox, the scheduler and the agent loop itself are plugins loaded into one shared context, and any of them can be replaced. There is no privileged core that plugins merely decorate. That is what makes the harness worth trying, and it is also where the one real risk lives. Whether that trade is the right one depends on what you are measuring it against, and how it stacks up against Claude Code and Omnigent sets the plugin-everything design beside two other answers on model coupling, licence and how much of a VPS each one asks for.
A harness is not a model
The harness runs the agent loop. The reasoning happens in a model somewhere else, so nothing works until you give it either an API (application programming interface) key or the address of a model endpoint you host yourself. Everything in this post is harness configuration rather than model behaviour, and the line between the two is worth having straight before you spend an afternoon debugging which side a problem came from.
You configure that in the UI under Settings and then Models. DeepSeek has its own card, and in current releases the "Add model provider" button below it opens two modes. "Third-party model provider" covers the providers the harness ships a catalog for, such as OpenAI and Anthropic, where you paste a key and the catalog supplies the endpoint and model list. "Custom model API" is the interesting option: it takes a lowercase provider ID, a display name, a base URL, an API protocol, a credential and at least one model. The protocol picker offers OpenAI Chat Completions, OpenAI Responses, Anthropic Messages and Gemini API, so you can configure a gateway or local server that speaks one of those; endpoints with request-format differences need compatibility settings. Custom providers can also query the OpenAI-compatible GET /models endpoint to fill in the model list for you.
That is how you point the harness at a model on the same VPS. Ollama exposes an OpenAI-compatible API at http://127.0.0.1:11434/v1/, and the API key field takes any string, ollama by convention, because the OpenAI-style client requires a value and Ollama ignores it. Ollama's own docs also describe ollama launch dsh, which installs @deepseek-ai/dsh if it is missing and starts it against an Ollama model, so check which version it installs before you rely on the pin below. Whether a model small enough to fit your VPS is good enough to drive an agent is the harder question, and the difference between Ollama and vLLM as a local model server decides how much of your RAM the answer costs.
Keys typed into the UI are write-only. The harness stores them in $DSH_HOME/.credentials.yaml, and the settings keep only a credential reference, which current releases write to the active profile's patch file, $DSH_HOME/profiles/<profile>/cordis.patch.yml (the profile is web for dsh web). $DSH_HOME defaults to ~/.dsh. Treat the credentials file as a password file, because it is one: anyone who reads it can spend your API budget. If you want to edit those files directly rather than clicking through Settings, the walkthrough of dsh config files, keys and model endpoints shows what each key does and what leaves your box in each mode.
What you need before you install
- a VPS running Ubuntu 24.04 or another current Linux, with SSH access
- Node.js 24.9 or newer, because the project's main branch and
0.2.2-alpha.2now declare>=24.9.0and its CI tests Node 24 with a compatibility check on Node 24.9 and Node 26, with no Node 22 job; tagged releases through0.2.1-rc.4still listed Node 22.19 as acceptable, but that is no longer the floor the project builds against - a normal user account, not
root, because the agent runs shell commands as whoever started the process pnpmon the PATH if you plan to install plugins, since the plugin command shells out to it- port 3080 closed on your firewall and on your provider's separate network firewall
Ubuntu 24.04's own nodejs package is older than the harness needs, so on that release install Node from NodeSource or nvm rather than reaching for apt install nodejs. Ubuntu 26.10's official repository lists Node 24.19.0, which exceeds the Node 24.9 minimum. If the VPS is fresh, hardening SSH before anything else is worth ten minutes, because the tunnel you are about to depend on is only as good as the SSH server behind it.
Install the DeepSeek Harness on a VPS, pinned to one version
node --version
npx @deepseek-ai/dsh@0.1.0-rc.6 webnpx downloads the package and runs its dsh binary. web is an alias for --profile web, which boots the browser application, and the process prints the address it is listening on. The default is http://127.0.0.1:3080. Those numbers are a binding decision rather than a cosmetic default, and why dsh prints a loopback address covers what the harness will and will not answer before you go looking for it from your laptop.
Pin the version. npx @deepseek-ai/dsh web resolves whatever the latest tag points at the minute you run it, unless the project you run it from already has a copy installed, in which case npx quietly uses that copy instead. Either way, you are not the one choosing the version, and the project has already shipped several release candidates and says breaking changes are coming. 0.1.0-rc.6 is the August 2026 version pinned here. On 12 November 2026 latest points at 0.2.2-rc.1, a release that prints a tokenized startup URL; GitHub lists the newer prerelease 0.2.2-rc.2, so moving to another version is exactly the kind of upgrade to make on purpose after reading the repository. A pinned version means the box you set up today behaves the same next month, so an upgrade becomes a decision you make instead of an accident you discover. When a pinned command still starts the wrong build or refuses to install at all, the usual dsh install and version errors cover clearing the npx cache and checking which npm your Node bundles.
For daily use, install it once instead of re-resolving on every start.
npm install -g @deepseek-ai/dsh@0.1.0-rc.6
dsh --profile web --helpThat second line is worth running, because the launcher and the web app carry separate flag sets. dsh --help shows the launcher's own options. dsh --profile web --help shows the flags the web application accepts, which is where --port, --host and the repeatable --trusted-host live.
Now confirm what it is listening on.
ss -tlnp | grep 3080The local address column should read 127.0.0.1:3080. If it reads 0.0.0.0:3080, the UI is listening on every interface, so only your firewalls stand between it and the internet, and you should stop the process before you do anything else.
Why you must never publish port 3080
The web server in 0.1.0-rc.6 has no authentication layer. Its configuration exposes a listen host and a listen port, and that is the whole surface. Access control for non-loopback deployments is a separate trusted-host setting, which is not a login screen.
Newer releases add one. From 0.2.0-rc.2 on, startup prints a URL that carries a fresh token for that process; the browser that opens it receives a signed session cookie and is redirected to the same address without the token. A Host/Origin fence in front of the /api routes only accepts loopback, the listener's own bind address and the authorities you name with --trusted-host. That is a real credential, but the project's own docs warn that the printed URL is a credential to share only with intended users, and that plain HTTP sends it without encryption. Since 0.2.1-alpha.2 the web app can also bind one concrete local address and serve HTTPS itself with --tls-cert and --tls-key. That fixes the plaintext problem, not the exposure one. It makes an exposed port harder to abuse. It does not make it something to publish.
Now add what sits behind that port. The agent edits files in the workspace and runs shell commands, and your provider credentials sit on disk next to it. So on the pinned release an open port 3080 is a remote shell with a chat interface, running as the user that started it, with your API key attached. Nobody needs an exploit for that. They need the port number. On a release with the launch token they also need the token, which anyone who can read your terminal, your service logs or your unencrypted traffic already has.
The CLI (command line interface) agrees with this. As of 0.1.0-rc.6 it deliberately does not support --host 0.0.0.0 and exits with a usage error instead of starting, and the newer 0.2.2-alpha.2 still rejects it at startup. That refusal is a feature, so do not go looking for a patch that removes it.
Two other deployments are reasonable when a tunnel does not suit you. Put the box on a private overlay network so it holds an address only your own devices can route to, which is what a self-hosted Headscale control server gives you. Or front it with a reverse proxy that authenticates the request before it reaches port 3080, for example an Authentik single sign-on server doing forward auth. A reverse proxy with no auth in front of it is not a security control. It is a longer URL.
Reach the web UI over an SSH tunnel
Run this on your laptop, not on the server.
ssh -N -L 3080:127.0.0.1:3080 you@your-server-L opens port 3080 on your laptop and forwards anything that connects to it through the encrypted SSH session. The 127.0.0.1:3080 part is resolved on the server, so the connection arrives at the harness from loopback, exactly as if you were sitting at the machine. -N says do not start a remote shell, because you want the forward and nothing else.
Then open http://127.0.0.1:3080 in your local browser. On a release with the launch token, open the full startup URL the server printed instead, token included; when the harness was started over SSH it still prints the startup line but does not try to open a browser for you. If port 3080 is already busy on your laptop, change the left-hand number: ssh -N -L 3180:127.0.0.1:3080 you@your-server, then browse to http://127.0.0.1:3180, changing the port in a tokenized URL the same way. The number on the left is local and the number on the right belongs to the server, so only the left one moves.
Save it in ~/.ssh/config and stop typing it.
Host dsh
HostName 203.0.113.10
User deploy
IdentityFile ~/.ssh/id_ed25519
LocalForward 3080 127.0.0.1:3080After that, ssh -N dsh starts the tunnel. A browser reporting that the connection was refused usually means the tunnel is up but nothing is listening on the far side, because SSH forwards the port whether or not the harness is running. Check the server with the ss command above.
Keep the harness running after you log out
An npx command dies with your shell. A systemd user service survives, and it brings the harness back after a crash or a reboot. The unit here is deliberately minimal; if you want the harness running under its own locked-down account, with the version pinned inside the unit and logs you can actually search, the headless systemd setup for dsh covers that in full.
loginctl enable-linger $USER
mkdir -p ~/.config/systemd/user
command -v dshenable-linger matters because user services normally stop when your last session ends, so without it the harness dies the moment you close the tunnel. Take the absolute path printed by command -v dsh and put it in the unit, because systemd does not search the PATH your login shell builds.
[Unit]
Description=DeepSeek Harness web UI
After=network-online.target
[Service]
Type=simple
WorkingDirectory=%h/projects/site
ExecStart=/usr/local/bin/dsh web
Restart=on-failure
RestartSec=5
[Install]
WantedBy=default.targetWorkingDirectory is not cosmetic. The dsh process uses its invoking directory as the default filesystem location, so a service started in the wrong place points the agent at the wrong folder. That directory is only a default, though: a fresh Web UI has no workspace selected until you add one under Choose workspace, and the project's guide tells you to add the directory you started dsh in. The guide carries no version marker, and the same wording is already there in 0.1.0-rc.7, so expect it on the pinned release too. Set the unit's directory to the project, then pick that workspace in the UI.
systemctl --user daemon-reload
systemctl --user enable --now dsh
systemctl --user status dshA unit that refuses to start is almost always a wrong ExecStart path or a Node version the binary rejects, and journalctl --user -u dsh -n 50 names which. On a release with the launch token, the journal is also where the tokenized startup URL lands, and every restart prints a new one. The same pattern covers keeping any coding agent alive on a VPS, and the failure modes are identical.
What a plugin is allowed to do
A plugin is a module that contributes services, typed events and reversible effects to a shared context. The extension points are the part worth reading closely:
- register a model provider on
ctx.llm - add model-facing tools on
ctx.tools - provide the shell backend behind
ctx.shell - provide filesystem access or policy behind
ctx.fs - register human commands on
ctx.commands - run background work through
ctx.jobs - wrap spawned processes with a
ctx.sandboxbackend - intercept requests and tool calls through the
agent/*andtools/*events - extend durable session state
- drive the UI through
ctx.agents
Read that list the way an attacker would. A plugin can supply the filesystem layer and the shell layer, and it can sit in the middle of every tool call the model makes. No permission dialog stands between a plugin and those seams, because a plugin is ordinary Node code loaded into the same process as everything else. Installing a plugin is running a stranger's code with your agent's permissions, and your agent's permissions are your Unix user's permissions.
This is the same trust decision you make when attaching an MCP server to an agent on a VPS, where MCP is the model context protocol. It is also why running a coding agent safely on a VPS starts with the account it runs under rather than with the model, and why npm supply chain attacks land so hard on servers: the install step is the compromise, and nothing prompts you.
Where plugins come from
Plugins live in profiles. A profile is a named composition stored under $DSH_HOME, which defaults to ~/.dsh, and each profile directory holds the out-of-tree plugins it installs. The CLI manages them by forwarding your arguments straight to pnpm, using the profile directory as the working directory.
dsh plugin --profile web add github:deepseek-harness/turtle-ui
dsh plugin --profile web remove turtle-uiBecause the arguments reach pnpm unchanged, add, remove, update and why behave the way they do in any pnpm project, and a plugin can be an npm package or a GitHub reference. pnpm must exist on the PATH first. On Node 24, corepack enable pnpm puts it there. Node 25 stopped distributing Corepack, so on Node 25 and newer install it with npm install -g pnpm instead.
Discovery works through a GitHub topic. Plugin authors add the dsh-plugin topic to their repository, and browsing that topic is how you find what exists. A topic is a label an author applies to their own repository. Nobody reviews it and nobody signs it, and the topic page ranks by stars, which measures popularity rather than safety.
Current releases also carry an experimental Custom plugin indexes bundle. Switch it on under Plugins and a Discover tab lets you add an index, which is a JSON file fetched from a URL you supply. The harness ships no index of its own, checks the file's format but not the titles, authors or sources a market claims, and anyone on the network path can rewrite an index served over plain http:. A market is a catalogue someone else wrote, not a review.
Four habits keep this manageable. Read the source before installing, since most plugins are small enough to read in ten minutes. Pin the exact version or commit instead of tracking a branch. Run the harness under a user that owns nothing else, on a VPS you would be willing to rebuild. Give the agent its own API key with its own spending limit, separate from the key your production services use. When you sit down to read a plugin and want to know which files carry the risk, the walkthrough of vetting a dsh plugin goes through the manifest, the entry point and the extension points a plugin registers.
If you would rather compare designs before committing to one, the Omnigent multi-agent harness answers the same problem with a different structure, and the trade-offs become obvious once plugins are in play. If you end up keeping two or three of them on the same box rather than picking a winner, putting every harness behind one self-hosted API spares you a tunnel per port, at the cost of one more service that has to be bound to loopback and given a real password on day one.
What breaks first
Node is too old. The project's main branch and 0.2.2-alpha.2 require Node 24.9 or newer, and its CI tests Node 24 plus a compatibility check on Node 24.9 and Node 26, with nothing on Node 22. Older tagged releases through 0.2.1-rc.4 listed Node 22.19 as acceptable, but the project no longer builds against it. An older runtime fails at startup because the code uses syntax and APIs it does not have. Run node --version before anything else.
Port 3080 is already taken. A second harness, a stale process, or an unrelated application that also likes 3080. Find it with ss -tlnp | grep 3080, then stop it or start the harness elsewhere with dsh web --port 3180. --port belongs to the web app, so it goes after web.
The browser cannot connect through the tunnel. Confirm you browsed to 127.0.0.1 and not the server's public address, because the forwarded port exists only on your laptop. Then confirm the harness is listening on the server, since SSH sets up the forward whether or not anything answers on the far end.
dsh plugin fails immediately. The command is a wrapper around pnpm, so a missing pnpm binary stops it before any plugin work begins. On Node 25 and newer that is the default state, because Corepack no longer ships with Node.
The agent cannot see your project. A fresh Web UI has no workspace selected until you add one, and the session composer stays unavailable until you do. The process uses the directory it started in only as its default filesystem location, so a unit whose WorkingDirectory is your home directory points the agent at your home directory. Choose the workspace in the UI, or fix the unit and reload it.
FAQ
Is it safe to expose the DeepSeek Harness web UI on port 3080?
No. In the pinned 0.1.0-rc.6 the web server has no login of its own, and the agent behind it edits files and runs shell commands as the user that started the process, with your provider API key stored on the same disk. From 0.2.0-rc.2 on, including 0.2.2-rc.1, npm's latest release on 12 November 2026, and the newer 0.2.2-rc.2 prerelease, the printed startup URL carries a launch token that the browser trades for a session cookie, but that URL is a credential that plain HTTP sends unencrypted, so the advice does not change. Keep the listener on 127.0.0.1 and reach it over an SSH tunnel. A private overlay network, or a reverse proxy that authenticates every request before it reaches the port, also works. As of version 0.1.0-rc.6 the CLI refuses --host 0.0.0.0 and exits with a usage error, and 0.2.2-alpha.2 still rejects it, which tells you what the authors think of the idea.
Do I need a DeepSeek API key, or can I use a local model?
Either works, because the harness is a runtime and not a model. Under Settings and then Models you can paste a key into the DeepSeek card or a catalog provider, or choose "Add model provider" and then "Custom model API" and give it a base URL that speaks OpenAI Chat Completions, OpenAI Responses, Anthropic Messages or Gemini API. A local Ollama server answers at http://127.0.0.1:11434/v1/ and accepts any string in the API key field. Keys land in $DSH_HOME/.credentials.yaml, which defaults to ~/.dsh/.credentials.yaml.
What does installing a DeepSeek Harness plugin actually give the plugin?
The permissions of the account running the harness. A plugin is Node code loaded into the same process, and the extension points include the shell backend, the filesystem layer, the tool registry and the events wrapping every tool call. Nothing sandboxes a plugin away from those seams unless a plugin supplies the sandbox itself. Read the source before you install, and run the harness as a user that owns nothing you care about.
Which version should I install, and will it keep working?
Install an exact version, for example npx @deepseek-ai/dsh@0.1.0-rc.6 web. That is the August 2026 version pinned here. On 12 November 2026 npm's latest tag points at 0.2.2-rc.1; GitHub lists the newer prerelease 0.2.2-rc.2, released on 11 November, and the current CLI requires Node 24.9 or newer. The project calls itself a developer preview and says compatibility-breaking changes are expected, so an unpinned command can behave differently from one day to the next. Check the repository before upgrading, and expect config keys and plugin interfaces to move while the version still starts with 0.