Skip to content

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/commands takes a batch from the head of the queue and marks it processing. There is no lease and no redelivery: taken means either executed or attempted. A node that dies mid command gets its command closed as lost after 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 sends state ("I am waiting, generation is this") and ping, the server answers state ("there is work, go fetch it") and pong. The server generation epoch is the identity token of a connection, and the client's own client_epoch keeps an older instance of a node from pushing out a newer one. Only announce with epoch: null closes 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/).