dsh-remote-server

Mention a server with @ in a DeepSeek Harness session and run commands on it over SSH.

Register a server once, then ask for what you need in plain language. Commands that only read run immediately; anything that changes state stops and asks you first.

Nothing is installed on the servers. No agent, no daemon, no inbound port. The plugin drives your own ssh client, so your existing ~/.ssh/config — jump hosts, agent forwarding, known_hosts — keeps applying unchanged.

---

What it looks like

Type @ and pick a server. The reference travels with your message; the model names the target explicitly on every command.

One page for every server. Reachability, a description you write, and the machine's own numbers — hostname, OS, CPU, memory, disk, uptime — collected in a single SSH round trip. A server you have not checked says so rather than showing a fabricated placeholder. The page heading also shows the installed plugin package version.

Bring in what you already have. Import reads ~/.ssh/config (or any path you name) and registers the hosts you pick. Re-scanning tells you what is already registered instead of showing a wall of disabled rows.

---

Install

dsh plugin --profile web add dsh-remote-server

Then start dsh as usual — dsh web, which is the same thing as dsh --profile web.

Nothing to hand-edit, and nothing to allow: the published tarball is already built.

--profile names which composition to install into. A profile is one bootable set of plugins under $DSH_HOME/profiles/, so you can keep a working setup and a clean one side by side; web is the one the quickstart boots.

Need the dsh command? The quickstart runs the harness through npx @deepseek-ai/dsh web without installing anything, so dsh may not be on your PATH. Either install it once with npm install -g @deepseek-ai/dsh, or prefix each command below with npx @deepseek-ai/dsh — npx @deepseek-ai/dsh plugin --profile web add dsh-remote-server. Keep the scope: a bare npx dsh pulls an unrelated package and fails with could not determine executable to run.

About the peer-dependency warnings

The install prints a list of "missing peer" warnings for @deepseek-ai/dsh-*, @deepseek-ai/cordis, and react. This is expected, and the plugin works.

pnpm manages only out-of-tree packages in your profile. Those peers are in-box bundles supplied by the dsh installation itself, so they are genuinely absent from the profile's node_modules and genuinely present at run time. Verified: with none of them installed there, the plugin loads, its routes answer, and its browser bundle is served.

They stay declared because the package really does require those seams. Deleting them would quiet the output by removing true information.

Installing from source instead

dsh plugin --profile web add github:MRZHUH/dsh-remote-server

A git install fetches sources, not build output, so pnpm has to run this package's prepare script to compile it. pnpm refuses that until you allow it: the first add fails and prints the key to add to your profile's pnpm-workspace.yaml.

onlyBuiltDependencies:
  - dsh-remote-server

Copy the key from pnpm's own message rather than from here — older pnpm called it allowBuilds, and the message is authoritative for the version actually running. Treat granting it for what it is: permission to execute this package's code on your machine at install time. Pin a commit (github:MRZHUH/dsh-remote-server#<sha>) so a later push cannot silently change what runs.

Treat that for what it is — permission to execute this package's code on your machine at install time. Pin a commit (github:MRZHUH/dsh-remote-server#<sha>) so a later push cannot silently change what runs. Installing from npm needs no such allowance, because the published tarball is already built.

Removing it takes one command, and your registered servers survive it:

dsh plugin --profile web remove dsh-remote-server

Publishing

Publishing a GitHub Release whose tag matches v<package.json version> runs .github/workflows/publish.yml. The workflow checks out that tag, builds and tests the package, verifies the tag/version pair, and publishes to npm with provenance through npm trusted publishing. Configure the npm package's GitHub trusted publisher for repository MRZHUH/dsh-remote-server and workflow publish.yml; no NPM_TOKEN secret is required.

Requires an OpenSSH client on the machine running dsh. If ssh is missing, the plugin fails at load with the install command for your platform rather than mounting in a state where nothing can run.

---

Register a server

Use Settings -> Servers -> Add a server, or write them into the remote-servers settings namespace:

remote-servers:
  servers:
    - alias: web-01
      host: 10.0.0.11
      user: ops
      tags: [prod, web]
      description: edge tier - start here
    - alias: db-01
      host: db-01.internal.example
      port: 2222
      identityFile: ~/.ssh/id_ed25519_db

alias is the name you type after @, so it carries no whitespace. Authentication is key-based only: identityFile is a path the SSH client opens, and the plugin never reads, copies, or stores key material. A password field is refused rather than stored.

If a server rejects your key, the page hands you the exact ssh-copy-id line with your own user, host, and port already filled in.

---

What the model can do

Tool	What it does
remote_exec	Runs one command on one registered server; returns stdout, stderr, and the exit code.
remote_server_info	Reads a server's collected facts, or re-probes the machine.

---

How approval works

Every command passes through a fixed sequence. The order is the point:

1. Unregistered alias - refused. No connection is attempted.
2. Full access - the harness danger-full-access + never permission combination runs registered-server commands without another prompt.
3. High-risk ruleset - a deterministic match forces a human decision. The classifier cannot override it.
4. alwaysAsk - when set, everything from here on goes to a human.
5. Read-only allowlist - a plain invocation of a configured prefix runs immediately.
6. Model classifier - answers auto or human for whatever is left.
7. Human approval - asked through the harness approval channel.

Anything that cannot reach a confident "clear" ends at a human, and a human that cannot be reached ends at a refusal. A classifier that times out, errors, or answers ambiguously is not a pass — the denying branch is the default path through the code, not an error handler.

The nine high-risk categories: recursive deletion, disk and filesystem writes, shutdown and reboot, service stop and restart, user and permission changes, package install and removal, writes into system paths, privilege escalation, and reads of credential or key paths.

Enabling model auto-approval

Auto-approval stays off until you name a model, because the plugin cannot know which provider routes your deployment composed. In your profile's cordis.patch.yml:

- id: remote-server
  config:
    classifier:
      provider: deepseek
      model: deepseek-chat

No API key is involved here — the plugin never sees one. It calls ctx.llm and the harness resolves the credential it already holds. Set both fields or neither; half of them fails at load.

---

Configuration

Key	Default	Meaning
connectTimeoutMs	10000	Bound on establishing the connection.
execTimeoutMs	120000	Bound on one command.
probeTimeoutMs	15000	Bound on one facts probe.
outputMaxBytes	65536	Retained bytes per stream; overflow keeps the tail and is reported as truncated.
strictHostKeyChecking	accept-new	Unknown-host-key policy (accept-new or yes).
alwaysAsk	false	Route every command to a human.
readOnlyAllowlist	[]	Command prefixes that skip the classifier.
classifier	unset	{ provider, model } for auto-approval.
classifyTimeoutMs	15000	Bound on one classification call.

---

Limits worth knowing before you rely on this

Full access bypasses this plugin's approval stages. That is the preset's explicit promise: registered-server commands run without another prompt, including commands matched by the high-risk ruleset and deployments configured with alwaysAsk. The SSH user's own permissions still apply.

The high-risk ruleset is a noise filter, not a security boundary. Outside Full access, it matches command text. An obfuscated rm, a base64-decoded payload, and a call into a script that does the damage all walk straight past it. What actually bounds damage is that the default leans toward asking you, and that the SSH user's own permissions on the target still apply. Give that user the least privilege the work needs, and set alwaysAsk: true where no automated clearance is acceptable.

accept-new trusts the first key it sees. A first connection to a host you have never reached records whatever key answers; a later change is refused. That is trust-on-first-use, and a first connection through a hostile network can be intercepted. Set strictHostKeyChecking: yes and pre-populate known_hosts where that matters. ask is not offered: authentication here is non-interactive, so a prompt could only ever fail.

A timeout or cancellation does not kill the remote process. It stops this side from waiting. The remote command may still be running, and results say so rather than claiming a kill. Run long work under nohup or tmux.

Exit code 255 is ambiguous, and the plugin says so. It is what the SSH client reports for its own failures and a legal exit code for your command. When stdout is empty and the stderr text matches no known client failure, the result is reported as ambiguous — carrying the client's own message — rather than asserting a remote exit that was never observed.

Credential redaction is best-effort. Recognized secret formats are replaced before anything reaches the session log, a tool result, or the screen. It reduces exposure; it does not guarantee none. The structural protection is that the plugin never reads key material itself.

Reading an SSH config reads a path you name, as you. The route serving import runs in your local dsh process. The web server binds 127.0.0.1 by default; binding it to a network address exposes that reach along with everything else.

---

Auditability

Every execution and every refusal appends one remoteServer/exec session event recording the target, the command (redacted), which gate stage decided, the reason, and the outcome. A refused attempt carries no exit code, because nothing ran. Whatever the model was told can be reconstructed from the log alone.

---

Development

npm install
npm test
npm run typecheck
npm run build

npm test builds first, so the suite always runs against fresh output.

Design documents — specification, plan, research, contracts, and a validation guide — live under specs/ and travel with the code.

---

License

MIT