- Home
- Plugins
- Integrations & Remote
- dsh-nodes
dsh-nodes
unera/dsh-nodes
Run commands on remote machines from a DSH session: sandboxed (ro/rw/full), policy-controlled, audited
Install
dsh plugin --profile web add github:unera/dsh-nodesREADME
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
The released package is on npm (npm view @dr-co/dsh-nodes version — 0.3.25 at the time of
writing, and this checkout is ahead of it; CHANGELOG.md lists what came after):
npm install -g @dr-co/dsh-nodes
To install exactly this checkout instead:
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.
What a device sends to the host
The full vocabulary — command, voice, new-session, voice-warmup, notify-button,
notify-session, bug-report, form — lives in docs/device-events.md,
and the same list is machine-readable in x-device-events of the schema. A test compares the
two, so neither can quietly fall behind. The reference is the single source of truth for
messages a device starts itself; everything else here is a command the host sends.
Calling a node from another plugin
The tools above are for the model. A plugin that needs to ask a device something gets the
nodes service instead, which is the same queue and the same audit trail without the
approval dialogue a tool call goes through:
const nodes = ctx.get('nodes') // or declare `nodes` in your own inject map
const answer = await nodes.call('phone', 'voice', 'record', { mode: 'ptt' }, { timeout: 45 })
if (answer.status === 'ok') use(answer.payload)
call(node, api, method, data, options) accepts an alias or a node id, an API name or id,
checks the arguments against the declared schema, and returns {status, code, message, results, payload} — payload being the parsed JSON of the device's last result block.
devices() answers the roster without touching a single device — a settings page must not
wait for hardware that is asleep:
nodes.devices()
// [{ id: 19, name: 'Телефон', alias: 'A059P', online: true, version: 'android-0.10.22' }]
Audio pushed by a device
POST /v1/upload-file?type=voice&filetype=wav&id=take-1
authorization: Bearer <node token>
x-seconds: 4.8 (optional)
<wav bytes>
→ 202 {"accepted":true,"id":"take-1","path":"…/cache/voice/incoming/take-1.wav","bytes":N,"seconds":4.8}
Optional measurement headers, all epoch milliseconds: x-record-start, x-record-stop,
x-sent-at (a nonsense value is ignored, never a reason to refuse a recording). They arrive in
the event as at: {recordStart, recordStop, sentAt, receivedAt}, where receivedAt is stamped
by the server before the first byte.
synth=device|host tells the host which side speaks the answer: device (default, and what a
typo becomes) means the phone reads the text itself and the host does no synthesis at all;
host means the host renders the audio and the device only plays it.
No seq, no command: the device pushes, the host receives. filetype is one of
wav ogg opus mp3 m4a flac; the path is chosen by the server, never by the device; the write
is atomic (.inprogress → rename) and bounded by maxTransferBytes. After the file is stored
the host emits dsh-nodes/voice {node, nodeName, id, path, bytes, seconds}.
Event types
POST /v1/events names what happened in type — notify-button, notify-session,
new-session, voice-warmup, bug-report, or form (reserved, answered 501). Anything else
is 400 bad_type. Only the first two are delivered into a session: a warm-up, a report about
the app and a request for a new conversation are facts for the plugin that listens, and nothing
reaches a session with them. Each type, its fields and its answer are in
docs/device-events.md.
An event without type (and the old type: "notify") is still read by its fields and logged
once as a guess: an installed app cannot be updated in the same minute as the server.
Devices can also ask the host for attention without producing a message: POST /v1/events
with { "voice": { "want": "record", "mode": "ptt" } } and no type answers 202 and emits
dsh-nodes/voice-want for whoever listens. Nothing is delivered to a session, and no session
is required. The shape is deprecated but supported — see the same reference.
Are events allowed at all?
Events are a privilege the owner grants, not something a paired device gets for free. The node
row carries events_enabled INTEGER NOT NULL DEFAULT 0: a node that was never allowed sends
nothing. The switch is on the node's page in the panel ("Events allowed"), and the admin API
sets the same flag either as {"op": "update", "id": N, "body": {"events_enabled": true}} or as
{"op": "events", "id": N, "body": {"enabled": true}}; the flag is also read in nodeView
as eventsEnabled.
Off means off for the event routes only. POST /v1/events answers 403 events_disabled for
notify-button, notify-session, new-session, voice-warmup, bug-report and the legacy
voice.want. Everything else keeps working: the socket stays up, GET /v1/state and
GET /v1/commands serve the node, commands run, and a recording still arrives at
POST /v1/upload-file?type=voice — the microphone is not the switch, and the panel says so
next to the checkbox.
Upgrading from 0.3.x turns events off on every existing node, because that is the default.
The device is not broken: it stays connected and commands go through, only the event routes
answer 403 until the owner flips the switch. A voice plugin therefore stops receiving
voice-warmup and new-session — the first thing to check after an upgrade.
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.
Who is in charge. Three of these four values (access, base, allowEscalation,
approver) can be written by two sides: the owner in the admin panel, and the node in its own
PUT /v1/announce. The owner wins. An announcement can narrow those rights and never widen
them — a node whose panel says ro stays ro even if it announces full, and
allowEscalation: false is not switched back on. What was refused comes back in the answer's
warnings (and into the log as policy-narrowed), so a client author sees it instead of
guessing. Only a field the owner has never set (none, or empty) is filled in by the node
itself.
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/state, GET /v1/commands,
POST /v1/commands/{seq}/result, GET /v1/ws (upgrade), POST /v1/events,
POST /v1/upload-file, POST /v1/download-file
(the last three are the device side: events a device starts, and files in both directions).
There is no /v1/catalog route: the API catalog is read through the admin side.
Admin: /api/dsh-nodes/* — private, behind the DSH session.
The client-facing protocol is in spec/openapi.yaml (English, like
this file). It is the source of truth; the Russian translation in
docs/openapi.ru.yaml lags behind it (it does not describe the device
routes yet), so a client author should read the English one.
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/).
Related plugins
dsh-web (dsh-ssh)
zhu1090093659/dsh-web
dsh-web (dsh-remote-web-ui)
zhu1090093659/dsh-web
dsh-purge
kingcharleslzy-ai/dsh-purge
dsh-web-ui (dsh-ssh)
zhu1090093659/dsh-web-ui