dsh-nodes
Verified@dr-co/dsh-nodes Β· v0.3.25 Β· MIT Β· Web UI
Run commands on remote machines from a DSH session: sandboxed (ro/rw/full), policy-controlled, audited
Install
dsh plugin add @dr-co/dsh-nodes Confirm the layer applied with dsh --profile default --dump-config β see the install guide.
Source
Tags
Readme
dsh-nodes
Remote execution for DSH: nodes anywhere (a laptop, a router, a CI box) announce their own APIs, and the model calls their methods through a small set of tools.
The server keeps a registry of nodes and a catalog of APIs, so adding a node does not cost context: the model sees four tools, not every method of every machine.
nodes_list() β nodes: aliases, online, uptime, which APIs they hold
nodes_catalog() β catalog: id, name, methods
nodes_api(api) β methods of one API with their argument schemas
nodes_call(node, api, method, data, timeout?, sandbox?)
The pair is two packages: this plugin (server side) and a client that runs on the node. Two clients are shipped and both speak the same protocol β pick whichever machine you want to reach:
| Client | What it runs on | Where it lives |
|---|---|---|
@dr-co/dsh-node-client |
a desktop or a server: Linux, macOS, systemd, bwrap sandbox, shell jobs, file transfers, approval dialogs |
GitHub Β· npm |
dshnc for Android |
a phone: shell with the app's own permissions, files, camera, apps, notifications, and questions to the person (dialog.ask) |
GitHub |
Install the desktop one with npm install -g @dr-co/dsh-node-client; the Android
one is an APK from the releases page of its repository.
How it works
model ββnodes_callβββΆ plugin ββqueueβββΆ client on the node βββΆ sandbox βββΆ shell
β² β
βββββ result ββββββββββ
- The command is handed out once.
GET /v1/commandstakes a batch from the head of the queue and marks itprocessing. There is no lease and no redelivery: taken means either executed or attempted. A node that dies mid command gets its command closed aslostafter the timeout, so the model gets an answer instead of silence. - Results are accepted late. A model that already saw a timeout does not break anything.
- Presence rides a WebSocket (
/v1/ws) and speaks exactly two frames each way: the client sendsstate("I am waiting, generation is this") andping, the server answersstate("there is work, go fetch it") andpong. The server generationepochis the identity token of a connection, and the client's ownclient_epochkeeps an older instance of a node from pushing out a newer one. Onlyannouncewithepoch: nullcloses in-flight commands. Command data always travels over HTTP.
Install
Not published to npm; install from the checkout:
npm install /path/to/dsh-nodes
Default config ships in cordis.patch.yml. State lives in
$DSH_HOME/storages/dsh-nodes.sqlite; the admin token sits next to it in
dsh-nodes-admin.token (0600) unless configured.
Connect a node
Open /api/dsh-nodes/admin (behind the DSH login) and generate a pairing link
https://host/dsh-nodes/pair?v=<code>, valid for 10 minutes. On the node:
dshnc connect 'https://host/dsh-nodes/pair?v=<code>'
dshnc daemon
The client exchanges the code for a token itself β nothing to approve in the
panel. The code is stored hashed only: reuse gives 409, an expired code
410.
Access control on a node
The owner of the machine decides how much the server may do there. Three values,
set on the node (dshnc policy), not on the server:
| value | meaning |
|---|---|
base |
mode a command starts in; a confirmed command is not lowered by it |
max |
absolute ceiling; nothing goes wider, not even with approval |
approver |
who may answer a question about a wider mode: local, server, none |
Modes are ro (read only), rw (write inside allowed roots), full (no
sandbox). If a command is denied and approver is not none, the node is asked
in its own way β a dialog on that machine (zenity and friends), or the DSH
approval dialog on the server side.
approver: local is a promise: the node must announce the session.approve
method. The server checks this and falls back to none, otherwise it would queue
an approval command the node cannot execute.
Approval covers exactly one command and one step (ro β rw β full, up to two
steps). The command is then re-run from the beginning, which the dialog says
explicitly: a command that already did half the work before the denial will do
that half again.
Audit
Two places, two purposes:
- the journal β one line per event with a syslog priority (
<6>info,<4>warning), rotated by systemd. Long memory:journalctl --user -u dsh-server | grep 'audit:'; - the database β a ring buffer (2000 rows, 7 days, command text up to 1000 chars) that feeds the admin panel. Bounded on purpose: an audit nobody reads must not grow to gigabytes.
Three kinds of events: exec (ran, in full or with approval), denied (the
kernel refused) and approve (what the human answered).
Uptime
The client sends uptimeSeconds β time since its process started. The server
converts it to its own clock at the moment of the message and only adds its own
delta afterwards, so a node with a wrong clock cannot produce a negative or
absurd uptime.
Routes
Public: POST /v1/enroll, GET /v1/enroll/{uuid}, POST /v1/pair.
Node (Bearer): PUT /v1/announce, GET /v1/catalog, GET /v1/state,
GET /v1/commands, POST /v1/commands/{seq}/result, GET /v1/ws (upgrade).
Admin: /api/dsh-nodes/* β private, behind the DSH session.
The client-facing protocol is in spec/openapi.yaml (English, like
this file); the Russian translation is kept in
docs/openapi.ru.yaml.
The admin API is deliberately not in the spec: it is private and no third-party
client should depend on it.
Development
node --test test/*.test.mjs
Tests start a real http.createServer with the plugin handler β no cordis, no
mocks of the protocol.
Design notes and open questions live in docs/plan.md (Russian,
as are the other documents in docs/).