DSH-Remote-plugin-akhyui

简体中文 | English

DeepSeek Harness plugin: connects the machine running DSH to your own relay over an outbound WSS, so the mobile app can list sessions, send messages, and answer approvals and questions from anywhere. Zero runtime dependencies.

What it is

• Installed on the DSH host (not on the relay server) and loaded by DSH as a plugin.
• Path: mobile app → relay → this plugin → DSH. The plugin is always the side that dials out.
• What it exposes: list sessions, follow the live event stream, send messages (text / inline images / uploaded files via receiptId), switch models, cancel a turn, and answer approvals plus ask_user_question prompts.
• Requires a deployed relay (DSH-Remote-backend) and a connector token issued by it.
• Security boundary: whoever holds the phone token can run commands on this machine. Treat the relay and the phone token as equally sensitive.

Architecture

Mobile app ──HTTPS/WSS──▶ relay ◀──outbound WSS── dsh-remote-bridge ──▶ DSH host (sessions, tools, models)

The plugin only makes outbound connections (wss://<relay-host>:<port>/api/v1/attach), so the host needs no inbound port open in its firewall and works behind home NAT or without a public IP. The relay only authenticates, rate-limits, forwards and audits; it never parses or stores session content.

Requirements

Deployment

Four steps: issue a token → install the plugin → write the config → restart DSH.

1. Issue a connector token on the relay

cd /opt/dsh-backend
sudo -u dshrelay env DSH_RELAY_DB=/opt/dsh-backend/var/relay.db \
  .venv/bin/python -m app.cli issue-connector --name home-pc

• dshrelay is the backend repository's default service account; substitute your own service user. DSH_RELAY_DB points at the relay's SQLite database.
• The token in the output is your connectorToken; the --name value (home-pc above) is normally reused as deviceId.
• The token is shown once. Store it in a password manager; if it leaks, revoke it with revoke-connector and issue a new one.

2. Install the plugin

sudo mkdir -p /opt/dsh-remote-bridge
sudo chown "$USER" /opt/dsh-remote-bridge
git clone https://github.com/AKHYui/DSH-Remote-plugin.git /opt/dsh-remote-bridge
dsh plugin --profile desktop add link:/opt/dsh-remote-bridge

• The link: path is the repository root (where package.json lives), not a subdirectory of it.
• Installation inserts a remote-bridge entry into that profile from the patch layer the package ships in cordis.patch.yml. Its config is empty at that point, so the plugin does not start; the next step overrides it by id.

Windows: any directory works (e.g. D:\dsh-remote-bridge); point link: at it.

3. Write the config

Append to ~/.dsh/profiles/desktop/cordis.patch.yml (key names match DEFAULT_CONFIG in src/config.js):

- id: remote-bridge
  name: dsh-remote-bridge
  config:
    serverUrl: 'wss://relay.example.com:58443/api/v1/attach'
    connectorToken: '<connector token>'
    deviceId: 'home-pc'
    deviceName: 'home-pc'
    tlsCaFile: '/etc/dsh-remote-bridge/ca.crt'
    autoConnect: true
    reconnect: true
    heartbeatMs: 30000
    approvalTimeoutMs: 90000
    allowedSessions: []
    hideArchivedSessions: true
    allowInsecure: false
    logLevel: info
    debugLog: '/tmp/dsh-remote-bridge.log'

• serverUrl must be the relay's attach endpoint; https:// or http:// is rewritten to wss:// or ws:// automatically.
• tlsCaFile points at the CA that signed the relay certificate (PEM), in a location the DSH process can read. The plugin adds it to the process trust store before dialing.
• connectorToken is a secret: you can keep it out of the file entirely by setting DSH_REMOTE_BRIDGE_TOKEN instead (the environment wins over this key).
• Any key can be overridden by its DSH_REMOTE_BRIDGE_* environment variable; see Configuration below.
• debugLog must point at a file the DSH process can write; write failures are ignored silently.

Windows: use Windows paths, e.g. tlsCaFile: 'D:\dsh-remote-bridge\certs\ca.crt' (backslashes are literal inside single quotes).

4. Restart DSH

Restart DSH the way you started it: systemctl --user restart for your DSH service, quit and reopen it in a desktop session, or Ctrl-C and rerun it in the foreground.

Changes to src/ only take effect after DSH restarts. The host does no HMR, and Node's ESM module cache survives disabling, enabling and reinstalling a plugin. Config in the profile patch is live: within seconds the plugin is recreated and reads the new values, with no restart.

5. Confirm the link is up

tail -n 5 /tmp/dsh-remote-bridge.log    # this file exists only when debugLog is set

DSH's own output (console or log) should also show connected to wss://… as device "home-pc" (relay protocol v1).

Verifying without installing into DSH

Run the real plugin against a real relay with a stub context — no DSH involved:

cd /opt/dsh-remote-bridge
node tools/simulate.mjs --server wss://relay.example.com:58443/api/v1/attach \
  --token '<connector token>' --device-id dev-sim --ca /etc/dsh-remote-bridge/ca.crt

Useful flags: --ask raises one simulated approval after three seconds; --events <ms> synthesizes a session event every <ms> milliseconds (0 disables it, default 5000); --seconds <n> exits after n seconds; --log <level> sets the log level; --no-demo-ops skips the demo Remote handlers. Full list: node tools/simulate.mjs --help.

Configuration

Keys can live in the profile patch's config: or in the matching environment variable (the environment wins).

Boolean keys accept 1/true/yes/on and 0/false/no/off (case-insensitive); allowedSessions accepts an array or a comma-separated string; heartbeatMs and approvalTimeoutMs below their floors refuse to start.

Operations and troubleshooting

Tests

cd /opt/dsh-remote-bridge
node --test                      # 155 cases across 8 test files
node --test test/ops.test.js     # a single file
npm test                         # same thing (zero dependencies, no npm install needed)

Repository layout

Related repositories

• DSH-Remote-plugin — this repository, the DSH desktop plugin
• DSH-Remote-backend — the relay service (FastAPI + SQLite)
• DSH-Remote-app — the Flutter mobile client

License

MIT, see LICENSE.