SSD Nodes Learn Hosting plans →
Guides Matt ConnorBy Matt Connor

Run dsh headless on a VPS with systemd

Run dsh, the DeepSeek Harness, as a systemd service on a VPS: dedicated user, pinned version, Restart rules, journalctl logs, and an SSH tunnel to the UI.

Run dsh headless on a VPS, not in a terminal

Running dsh headless on a VPS is one systemd unit file plus a dedicated user to own it. dsh is the command line launcher for DeepSeek Harness, DeepSeek's agent runtime, published under the MIT licence in developer preview in August 2026. A harness is the program around the model rather than the model itself, so what you are putting under systemd is the loop, the tools and the permissions, not DeepSeek's inference. The quickstart tells you to type npx @deepseek-ai/dsh web, which is correct, and which also dies the moment you close your SSH (secure shell) session.

A unit file fixes four things at once. The service comes back after a reboot. Its output goes to the journal instead of scrolling past you. It runs as an account that is not root. And the version it runs is the version you picked, which matters more here than usual, because upstream says so in capital letters:

DeepSeek Harness is currently in developer preview and is iterating rapidly. THERE WILL BE COMPATIBILITY-BREAKING CHANGES.

This guide assumes dsh already works for you by hand. If it does not, start with installing DeepSeek Harness on a VPS and come back once npx @deepseek-ai/dsh web serves a page.

Node first, because npm warnings are not enough

node -v

Ubuntu 24.04's own package is Node 18 (18.19.1 as of August 2026), which is old for a package published this year. npm itself does check Node versions: its documentation says a package's engines field "will only produce warnings" unless you enable engine-strict. The published @deepseek-ai/dsh manifests carry no engines field at all (checked on 27 October 2026 for 0.1.0-rc.7, 0.2.1-rc.2 and 0.2.1-rc.4), even though the repository declares one, but npm also checks dependencies' engine requirements. The pinned 0.2.1-rc.2 release declares commander: ^15.0.0, and Commander 15 requires Node >=22.12.0, so installing it on Ubuntu's Node 18 produces an EBADENGINE warning under normal npm settings. That warning does not stop the install by default, so check Node before you reach a runtime failure.

The repository's floor has also moved. The 0.2.1-rc.2 source accepts ^22.19.0 || >=24.0.0, but the CLI package on the master branch now declares >=24.9.0, which Node 22 does not satisfy. Install Node 24 from NodeSource. It is a long term support (LTS) line, in maintenance since 20 October 2026, and its current builds meet both ranges. Node 26 became LTS on 28 October 2026, according to the Node.js release schedule.

curl -fsSL https://deb.nodesource.com/setup_24.x -o /tmp/nodesource_setup.sh
less /tmp/nodesource_setup.sh
sudo -E bash /tmp/nodesource_setup.sh
sudo apt install -y nodejs
node -v

node -v should now print a v24 version, 24.9.0 or newer. The less line is there because piping a remote script straight into bash runs code you never read.

Prove it runs before you write a unit

npx @deepseek-ai/dsh@0.2.1-rc.2 web

Leave that running. From a second SSH session:

curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3080/

Any HTTP status code means the web profile is listening on loopback, which is where it binds by default. Expect a 401, and treat it as a pass: the UI authenticates browsers with a launch token in the printed URL, which it trades for a signed session cookie, and a request that carries neither gets a 401. 000 together with curl: (7) Failed to connect to 127.0.0.1 port 3080 means it is not listening, and the first terminal is telling you why. Stop the manual run with Ctrl+C before you go further: a unit that tries to bind a port something else already holds fails with Error: listen EADDRINUSE: address already in use 127.0.0.1:3080.

0.1.0-rc.7 was the published version on 18 August 2026, and it predates the browser authentication this guide relies on: its Connection README says the fence is a reachability policy and "the Web carrier provides no authentication layer". On 11 October 2026 the latest tag pointed at 0.2.0-rc.2. On 27 October 2026 latest pointed at 0.2.1-rc.2 and next at 0.2.1-rc.4, so the commands here pin 0.2.1-rc.2. On 4 November 2026, npm's version listing shows both latest and next at 0.2.1-rc.5; the commands here keep the existing pin. Check what is current with npm view @deepseek-ai/dsh version, then pin whatever you decide to run.

Install the version you pinned, globally

npx is the wrong tool inside a unit file. Without a version or a matching local installation, it resolves the package version when the process starts, so a restart three months from now can bring up a different build of a preview-stage agent with no change on your side. Missing packages or cache data also require the npm registry, so a slow registry can delay or fail startup; npm supports cached and offline execution too. Install once, at a version you wrote down:

sudo npm install -g @deepseek-ai/dsh@0.2.1-rc.2
command -v dsh
npm ls -g --depth=0 @deepseek-ai/dsh

command -v dsh prints /usr/bin/dsh when npm came from NodeSource, and /usr/local/bin/dsh when it came from Ubuntu's own package. Use the path it actually printed in the unit file. npm ls -g prints the exact version, which is the answer you want in six weeks when behaviour changes and you cannot remember what you installed. If the install fails, or command -v dsh prints nothing afterwards, or the version you get back is not the one you asked for, work through the usual dsh install and version failures before you write the unit file.

A user that owns the service and nothing else

The agent runs shell commands. That is its job. Running it as root makes every tool call a root tool call, so give it its own account with no login shell.

sudo useradd --system --create-home --home-dir /var/lib/dsh --shell /usr/sbin/nologin dsh
sudo install -d -o dsh -g dsh -m 750 /var/lib/dsh/harness /var/lib/dsh/workspace
id dsh

/var/lib/dsh/harness becomes DSH_HOME, the directory dsh keeps profiles in. A profile is a named stack of plugin bundles with your own patch layer on top, and the web and headless profiles build themselves from shipped templates the first time you boot them. Anything you add to that stack later runs as this user with the agent's own file and shell access, so vetting a plugin before you install it belongs to the same job as creating the account. That first boot writes files and may fetch bundles, so do it by hand where you can watch it.

sudo -u dsh env HOME=/var/lib/dsh DSH_HOME=/var/lib/dsh/harness /usr/bin/dsh --profile web

Set HOME explicitly rather than trusting what sudo does with it, because whether sudo preserves or rewrites HOME depends on settings including env_reset, env_keep and always_set_home in /etc/sudoers. Get it wrong and the first run tries to use your home directory for caches and state, causing permission errors or putting state somewhere the service later will not use. Stop it with Ctrl+C once the curl check prints a status code.

The unit file

Write /etc/systemd/system/dsh.service:

[Unit]
Description=DeepSeek Harness (dsh) web profile
Documentation=https://github.com/deepseek-ai/deepseek-harness
After=network-online.target
Wants=network-online.target
StartLimitIntervalSec=300
StartLimitBurst=5

[Service]
Type=exec
User=dsh
Group=dsh
WorkingDirectory=/var/lib/dsh/workspace
Environment=HOME=/var/lib/dsh
Environment=DSH_HOME=/var/lib/dsh/harness
ExecStart=/usr/bin/dsh --profile web
Restart=on-failure
RestartSec=5s
TimeoutStopSec=30s
SyslogIdentifier=dsh
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=full
ProtectHome=true

[Install]
WantedBy=multi-user.target

ExecStart= takes the absolute path you got from command -v dsh. systemd will search a fixed path list for a bare command name, but that list is not your shell's PATH, so an absolute path removes the guess.

WorkingDirectory= is where relative paths resolve, and it is where a tool call that runs ls with no arguments starts. Point it at the workspace you hand the agent. If the directory is missing or the service user cannot enter it, the unit fails with status=200/CHDIR before dsh runs at all.

ProtectHome=true hides /home and /root from the process. That is safe here because everything the service touches lives under /var/lib/dsh. Point the workspace at a path under /home and the agent will report that the directory does not exist, which is confusing until you remember this line. ProtectSystem=full makes /usr, /boot and /etc read-only, which the service never needs to write.

Going further is tempting and usually wrong. ProtectSystem=strict makes the whole filesystem read-only apart from the kernel pseudo-filesystems and, with this unit's PrivateTmp=true, /tmp and /var/tmp, so writes to the workspace fail with EROFS: read-only file system. If you want that level, add ReadWritePaths=/var/lib/dsh in the same edit.

Which Type= belongs here

Type=exec, because dsh stays in the foreground and never forks. What that buys you over the default is a real error message. With Type=simple, systemd calls the start successful as soon as it has forked, before it knows whether the binary even exists, so systemctl start dsh returns cleanly and the failure shows up only in the journal. With Type=exec, systemd waits for execve() to succeed, so a typo in ExecStart= fails the command you just typed, where you will see it.

The two wrong answers both hang. Type=forking tells systemd to wait for a parent process to exit, and dsh never exits, so the start blocks until TimeoutStartSec expires (90 seconds by default) and then reports Job for dsh.service failed because a timeout was exceeded. Type=notify waits for a READY=1 message over sd_notify, and a Node process that never sends one stalls the same way. The full comparison of systemd service types covers the rest, including when wiring up notify is worth the effort.

Restart rules that fail loudly

Restart=on-failure restarts on a non-zero exit or an unclean signal, and leaves the unit alone after a clean exit; systemd treats SIGHUP, SIGINT, SIGTERM and SIGPIPE as clean signals for this service type. That is the behaviour you want from a preview build. If dsh ever exits 0 because it read a config it did not like, the unit stops and stays stopped, and systemctl status dsh shows inactive (dead) where you can see it. Restart=always turns that same event into a restart loop that looks healthy from a distance.

The rate limit is the part people leave out. systemd's defaults are five starts inside ten seconds, and with RestartSec=5s you never reach five starts inside a ten second window, so a unit that crashes on startup restarts forever and only the journal knows. StartLimitIntervalSec=300 with StartLimitBurst=5 allows five starts in five minutes, then refuses another start within that interval. systemd gives up and parks the unit in failed, logging Start request repeated too quickly. Clear that state with sudo systemctl reset-failed dsh once you have fixed the cause. Both settings belong in [Unit], not [Service]; unrecognized options produce warning logs rather than being ignored silently.

Start it, then check it

sudo systemctl daemon-reload
sudo systemctl enable --now dsh
systemctl status dsh

enable --now does two jobs. enable is what brings the service back after a reboot, and --now starts it in this boot. A bare systemctl start is gone after the next reboot, and kernel updates mean reboots.

systemctl status dsh should show Active: active (running), a Main PID, and a Memory: line. Then confirm where it is listening:

sudo ss -lntp | grep 3080

You want 127.0.0.1:3080. If you see any other address, a --host flag has moved the listener onto the network that address belongs to, serving plain HTTP unless TLS is set. The process name in that output is node, not dsh, because the dsh binary is a Node script, so pgrep -x dsh finds nothing. Use systemctl show -p MainPID dsh instead.

Then reboot once. A service that has never survived a reboot is not a service yet.

sudo reboot

Reconnect and run systemctl is-active dsh. It prints active.

Reading the logs with journalctl

Everything dsh writes to stdout and stderr lands in the journal under the unit name.

journalctl -u dsh -f
journalctl -u dsh -n 200 --no-pager
journalctl -u dsh --since "10 min ago" -p err

-f follows new lines, -n shows the last N, -p err filters by priority. SyslogIdentifier=dsh in the unit is why those lines are tagged dsh rather than node, which matters the first time you read journal output that is not filtered by unit.

Check the journal survives reboots before you need it to:

journalctl -u dsh -b -1

If that prints Specifying boot ID or boot offset has no effect, no persistent journal was found, the journal lives in /run and every reboot throws it away. With Storage=auto, create the directory and restart the daemon; if Storage=volatile is configured, change it to persistent first:

sudo mkdir -p /var/log/journal
sudo systemctl restart systemd-journald

Run sudo journalctl --flush to switch to persistent storage and flush the current boot's logs to disk.

Reach the UI over an SSH tunnel, not a public port

dsh serves the web UI (user interface) on 127.0.0.1:3080 by default. Loopback is the default, not the only choice: --host accepts one concrete IPv4 or IPv6 address of a local interface, and any address other than loopback serves the network it belongs to over plain HTTP, with a warning at startup, unless you also pass --tls-cert and --tls-key. What dsh refuses is a wildcard. Ask for --host 0.0.0.0 and the error starts like this:

webserver: host "0.0.0.0" is an unspecified (wildcard) address, which is not supported:

It goes on to say that "binding every interface would expose remote code execution to the network" and tells you to "bind one concrete IPv4 or IPv6 address of a local interface instead". A value that is not an IP literal at all, such as a hostname, fails with is not a concrete IPv4 or IPv6 address literal instead.

Keep the default anyway. The web API (application programming interface) drives the agent, and the agent runs shell commands. dsh does put authentication in front of that API: Host and Origin checks, plus a launch token in the printed URL that the UI trades for a signed session cookie. Over plain HTTP, though, that token crosses the network in cleartext, and upstream's own docs say the Host check does not protect the listening port itself. If you need the UI on a real hostname, DeepSeek's public deployments guide covers a reverse proxy with --public-url and --trusted-host, or native TLS with --tls-cert and --tls-key. What that 127.0.0.1:3080 line in the startup output actually means is worth reading before you try to move it. For a box only you use, forward the port from your own machine instead:

ssh -N -L 3080:127.0.0.1:3080 you@203.0.113.10

-L 3080:127.0.0.1:3080 opens port 3080 on your laptop and sends anything arriving there to 127.0.0.1:3080 as resolved on the VPS. -N means run no remote command, so the session only holds the tunnel open. Leave it running, find the URL dsh printed at startup with journalctl -u dsh -n 100 --no-pager, and open it in your browser. That URL carries the launch token. Open the bare http://127.0.0.1:3080/ in a browser that has not signed in and you get a 401. The token belongs to the running process, but the session cookie it buys outlives it: the cookie is signed with a secret dsh keeps in $DSH_HOME/.credentials.yaml and lasts 30 days by default, so a browser that has already signed in can open the bare URL again, even after a restart. You need a fresh URL from the journal only for a new browser, or once that cookie has expired. Treat the URL as a credential: upstream says to share it only with intended users, and anyone who can read the system journal can read it. Once you are in, that is where you enter the DeepSeek API key, under Settings then Models, and where you pick the workspace directory. Point the workspace at /var/lib/dsh/workspace, the directory the service user owns, or the agent's file tools fail with EACCES: permission denied.

If port 3080 is busy on your laptop, ssh says so:

bind [127.0.0.1]:3080: Address already in use
channel_setup_fwd_listener_tcpip: cannot listen to port: 3080

Pick a different local port with ssh -N -L 3081:127.0.0.1:3080 you@203.0.113.10, then open the printed URL with 3080 changed to 3081. Save the typing in ~/.ssh/config on your own machine:

Host dsh-vps
  HostName 203.0.113.10
  User you
  LocalForward 3080 127.0.0.1:3080

After that, ssh -N dsh-vps is the whole command. This tunnel is now the only door to your agent, so the SSH daemon is the thing protecting it: keys only, no password authentication, and the rest of hardening SSH on your VPS applies with more force than usual. If that VPS grows into a small private network of its own, with a database or a staging box behind it, advertising those addresses to your tailnet with a subnet router saves you a forward per service, though with dsh on its loopback default the UI itself still arrives through a tunnel.

The key does not belong in the unit file. Environment= values are printed by systemctl show dsh -p Environment, which any user on the box can run. If a plugin you install needs a key in the environment, put it in /etc/dsh.env with mode 600 owned by root and reference it with EnvironmentFile=/etc/dsh.env. systemd reads that file as root at exec time, and systemctl show does not print its contents. Which file on disk each setting actually lands in, and what leaves your box when you point dsh at a local Ollama endpoint instead of DeepSeek's API, is the subject of configuring dsh's keys, models and endpoints.

What it costs to run

Inference happens at DeepSeek's API, not on your VPS. Your box pays for the Node process, the UI it serves, and every command the agent decides to run. The first two are steady and small. The third is bounded by nothing in this unit file.

Measure the floor on your own box instead of trusting a figure from someone else's:

systemctl show dsh -p MemoryCurrent
systemd-cgtop -1 --depth 2

MemoryCurrent is in bytes. Watch it while the agent is working, not while it idles.

Tool calls are children of the service, so they land in the same control group and count against the same limits. An agent that runs npm install or a test suite inside the workspace can use more memory than the harness itself by a wide margin. On a 1 GB VPS that is where things break: the kernel picks a process and kills it, and journalctl -k | grep -i "out of memory" shows the Out of memory: Killed process line naming whatever it chose. That process is often not the one that caused the problem.

The fix is a limit you set on purpose. MemoryMax= and CPUQuota= in the [Service] section keep the damage inside the unit, so a runaway build is killed instead of the whole box locking up. Capping memory and CPU with systemd covers the numbers and the failure behaviour. Disk grows too, from session history under DSH_HOME and from whatever the agent writes in the workspace, so put du -sh /var/lib/dsh in whatever you already use to watch disk.

If what you want is an interactive agent you attach to and detach from, a service is the wrong shape, and running an agent in a persistent tmux session fits better. Run dsh as a unit when you want it always up and reachable through a tunnel.

Failure modes and the strings you will see

status=203/EXEC. systemd could not run the file, and logs Failed to locate executable /usr/local/bin/dsh: No such file or directory. The path in ExecStart= does not match what command -v dsh printed. This is the failure Type=exec reports at systemctl start time instead of hiding.

status=217/USER. systemd failed to determine or change the user credentials from User= and Group=, or to set up user namespacing. For this unit the usual cause is an account that does not exist. Confirm with id dsh.

status=200/CHDIR. WorkingDirectory= is missing, or the service user cannot enter it. sudo -u dsh ls /var/lib/dsh/workspace reproduces it directly.

Error: listen EADDRINUSE: address already in use 127.0.0.1:3080. Something already holds the port, usually the npx run left open in another terminal. sudo ss -lntp | grep 3080 names the process.

EACCES: permission denied followed by a path. Ownership under /var/lib/dsh is wrong, normally because a first run happened as root or with the wrong HOME. sudo chown -R dsh:dsh /var/lib/dsh fixes it.

Start request repeated too quickly. The unit hit the start rate limit and gave up. The real error is in the lines above it. Run sudo systemctl reset-failed dsh before trying again.

Unit is active (running) but the browser shows nothing. Run the check on the VPS: if curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3080/ prints a status code there, the listener answers on the VPS, so look at the port forward next. That code does not prove everything loaded: upstream says optional plugin failures do not suppress readiness, so read journalctl -u dsh -n 200 --no-pager for plugin errors as well. A 401 in the browser means it has no valid session cookie and the URL carried no valid launch token, either because you opened the bare URL or because the token is from before the last restart. Open the URL the current process printed.

Upgrading on purpose

Pinning means an upgrade is something you do, not something that happens to you. Read the release notes first, because upstream's own warning about compatibility-breaking changes is the entire reason for the pin. Back up the state directory, then swap the version:

sudo systemctl stop dsh
sudo tar czf /root/dsh-home-$(date +%F).tgz -C /var/lib/dsh harness
sudo npm install -g @deepseek-ai/dsh@0.2.1-rc.2
sudo systemctl start dsh
journalctl -u dsh -n 50 --no-pager

Rolling back is the same npm install -g with the old version, plus restoring that tarball, which only works if you took it. A preview-stage agent runtime is exactly the software where an upgrade rewrites a config format underneath you.

FAQ

Why does dsh stop when I close my SSH session?

Because npx @deepseek-ai/dsh web is a foreground process owned by your login session, so it is torn down when the session ends. A systemd unit is owned by the init system instead, which is why it keeps running after you disconnect and starts again after a reboot. sudo systemctl enable --now dsh is the pair of steps that gives you both: enable for the reboot, --now for this boot.

Should I use Type=simple or Type=exec for dsh?

Type=exec. dsh runs in the foreground and never forks, so both work, but Type=exec makes systemd wait for execve() to succeed before it calls the start successful. A wrong path in ExecStart= then fails systemctl start with status=203/EXEC in front of you. With Type=simple the same mistake returns success and hides in the journal. Type=forking and Type=notify are both wrong here, and both hang until TimeoutStartSec expires after 90 seconds by default.

How do I open the dsh web UI from my laptop?

Forward the port over SSH: ssh -N -L 3080:127.0.0.1:3080 you@your-vps, then open the URL dsh printed at startup, which you can find with journalctl -u dsh, in your browser. That URL carries the launch token, and a browser that has not signed in gets a 401 without it. Once signed in, the session cookie lasts 30 days by default and survives a service restart. Leave the service on its loopback default. dsh rejects a wildcard such as --host 0.0.0.0 as an unspecified address, and although it accepts one concrete local address, a non-loopback bind serves plain HTTP unless you set up TLS, which sends the launch token for an agent that runs shell commands across the network in cleartext.

Can I run dsh as root to keep permissions simple?

No. The harness exists to run commands and write files, so whatever privileges the service has are privileges the agent has. Create a system account with useradd --system --shell /usr/sbin/nologin dsh, own /var/lib/dsh with it, and add NoNewPrivileges=true to the unit. If you hit EACCES: permission denied afterwards, the usual cause is an earlier run as root leaving root-owned files behind, and sudo chown -R dsh:dsh /var/lib/dsh clears it.

Which version of dsh should I pin in the unit?

Whatever npm view @deepseek-ai/dsh version reports when you set the service up, installed with npm install -g @deepseek-ai/dsh@<that version> and recorded somewhere you will find it. 0.1.0-rc.7 was current on 18 August 2026, 0.2.0-rc.2 on 11 October 2026, and 0.2.1-rc.2 on 27 October 2026, with next already at 0.2.1-rc.4. On 4 November 2026, both latest and next point at 0.2.1-rc.5. Builds as old as 0.1.0-rc.7 have no browser authentication, so do not pin one of those for the web profile. The point is not the number, it is that npx with no version resolves the package at start time, so an unattended restart can silently move you onto a build with a different config format.

Was this article useful?