# dsh-remote

Remote control for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness), in the style of Claude Desktop: one **master** and any number of **slaves**.

- **Every session on every device.** Sessions run on the machine that created them. From any device you can browse all of them, open them, and chat in them; the work still executes on the owning machine.
- **The full remote UI at `/r/<device>/`.** The whole DSH UI of another device is proxied over the link: HTTP, the Remote WebSocket, SSE, plugin bundles and terminals. Slave→slave goes through the master's relay.
- **Plugin and config sync, master → slaves.** Slaves get the master's npm/registry bundles, its local `link:` plugins (packed and shipped over the link) and its `cordis.patch.yml`. The config lands in a *managed* bundle layer, so each slave's own `cordis.patch.yml` still wins and slave-only plugins stay untouched.
- **Opt-in secrets.** A credential (`OMNI_API_KEY`, …) reaches a slave only if three places agree: the master offers it, the master enables it for that device, and the slave accepts it.
- **Devices UI.** A sidebar panel lists every device and its sessions (live running state, filter, "New session on <device>"). A "Remote devices" settings page handles pairing, revocation and per-device sync policy. You get a toast when a session on any device finishes.

No dependencies: the WebSocket, the multiplexer and the proxy are plain Node.

```
 slave (laptop) ──outbound WebSocket /dsh-remote/link──►  master  ◄── slave (ai-pc)
   own sessions + own local plugins                  plugins, config, relay hub
```

## Install

On every machine, register the plugin in the DSH web profile and restart DSH:

```bash
# master (this repo as a link: plugin, e.g. in Beast-Workspace)
#   profile package.json  →  "@local/dsh-remote": "link:/path/to/dsh-remote"  + bundle entry
# or use the helper (also creates the node_modules link and a config block):
node deploy/install-local.mjs --role master --name "Pelican-Node"
node deploy/install-local.mjs --role auto   --name "ai-pc"          # on a slave
systemctl --user restart dsh    # or restart `dsh web` however you run it
```

`deploy/dsh-web.user.service` is a ready-made systemd user unit for a rootless `dsh web` (127.0.0.1:3081).

## Pair a device

1. **Master:** Settings → *Remote devices* → **Create pairing code** (single use, valid 15 min).
2. **Slave:** Settings → *Remote devices* → enter the master URL (e.g. `http://192.168.0.111:3080` or `https://dsh.rizzy.dev`) and the code → **Pair**. Then restart the slave's DSH once: with `role: auto` it switches from master to slave.

The slave gets its own device key; the master stores only its hash. **Revoke** cuts the device off immediately: open links close with code 4401 and later connections are refused with 401.

## Use it

- **Sidebar → Devices:** every device, its sessions grouped by workspace, a running indicator, search. Click a session to open it. A local session opens in place. A remote one opens `/r/<device>/#/session/<id>`, the full UI of that device, with a "Remote: <device> · back to local" pill in the corner.
- **+ New session** on a device card creates a session in one of that device's workspaces and opens it.
- **Open DSH ↗** opens a device's whole UI.
- **Toasts:** "<device>: '<title>' finished", with an *Open* action.

## Configuration (`cordis.patch.yml`)

```yaml
- id: dsh-remote
  config:
    role: master            # master | slave | auto (auto = slave once paired)
    deviceName: Pelican-Node
    lanUrl: http://192.168.0.111:3080     # shown on the pairing page
    publicUrl: https://dsh.rizzy.dev
    sync:
      auto: true            # slave: sync on link-up and when the master pushes
      allow: []             # slave: only these bundles (exact or prefix*)
      deny: []              # slave: never these bundles (wins over allow)
      secrets: []           # slave: credential refs it accepts from the master
      offerSecrets: [OMNI_API_KEY]   # master: refs it may hand out (per-device opt-in on the Devices page)
      excludeBundles: []    # master: never sync these bundles
      excludePatchIds: []   # master: never sync these cordis.patch.yml entry ids
```

Never synced: the master's `dsh-remote` and `dsh-lanmode` entries, and `connection`/`webserver` settings, since these are machine-local.

## How sync works

| Master has | Slave gets |
| --- | --- |
| registry bundle `name@ver` | `pluginManager.installBundle(name@ver)` (pnpm in the slave profile) |
| `link:` local plugin | a tarball over the link, unpacked to `<profile>/dsh-remote/sync/plugins/<name>/` and linked into the profile. Its `@deepseek-ai/*` imports are re-linked to the slave's DSH install |
| `cordis.patch.yml` entries | `<profile>/dsh-remote/managed-bundle/cordis.patch.yml`, added as the **last bundle**. The slave's own `cordis.patch.yml` is applied after it and wins. `!!js` expressions are kept |
| offered secret (opted in on both sides) | `ctx.credentials.set(name, value)` on the slave |

Local plugins are compared by content hash and re-shipped only when they change. When the bundle list changes, DSH needs a restart to load host code; the sync result reports `restartRequired`. *Push sync to all devices* on the master triggers an immediate pull everywhere.

## Security model

- Browsers authenticate with DSH's own cookie. Every `/dsh-remote/*` and `/r/*` route checks `ctx.connection.requestRejection`.
- The link is authenticated with a per-device key, sent in the upgrade headers and stored as a SHA-256 hash on the master.
- The proxy strips the browser's DSH cookies. The **owning** device mints a short-lived cookie for its own loopback authority, signed with its own browser-session secret, and rewrites `Host`/`Origin`. A remote DSH therefore only trusts its own minted cookie, and credentials never leave the machine they belong to, except secrets you explicitly opted into.
- `/dsh-remote/enroll` is the only unauthenticated route. It accepts a single-use pairing code.
- Use TLS (`https://` master URL) whenever the link crosses an untrusted network.

## Public access via rizzy.dev

`dsh.rizzy.dev` is served by the edge Traefik behind **Authentik forward-auth**. Browsers log in through Authentik as usual. A slave's DSH can't do an interactive login, so the edge must let these two paths through without forward-auth (they carry their own device-key / pairing-code authentication):

```
/dsh-remote/link      (WebSocket upgrade)
/dsh-remote/enroll    (POST, one-time pairing code)
```

For example, add a second Traefik router with a higher priority, `Host(\`dsh.rizzy.dev\`) && (Path(\`/dsh-remote/link\`) || Path(\`/dsh-remote/enroll\`))`, that uses the same service but no Authentik middleware. Until that exists, pair and link slaves over the LAN (`http://192.168.0.111:3080`).

## HTTP API (used by the UI)

| Route | |
| --- | --- |
| `GET /dsh-remote/state` | role, self, link status, devices |
| `GET /dsh-remote/sessions` | sessions of every reachable device |
| `GET /dsh-remote/stream` | SSE: `session-finished`, `devices`, `sync` events |
| `POST /dsh-remote/pairing` | master: create a pairing code |
| `POST /dsh-remote/pair` | slave: `{masterUrl, code}` |
| `POST /dsh-remote/unpair` | slave: forget the master |
| `POST /dsh-remote/devices/<id>/{revoke,remove,sync}` | master: device management / sync policy |
| `POST /dsh-remote/sync` | slave: pull now · master: push to all |
| `GET /dsh-remote/sync/status` | manifest (master) / last result (slave) |
| `POST /dsh-remote/new-session` | `{device, workspaceId? , cwd?}` |
| `* /r/<device>/…` | that device's DSH |

## Development

```bash
npm test                                   # link, mux, proxy (HTTP + WS), cookie, allow/deny
node deploy/dshr-cli.mjs GET state         # call the local API as the DSH owner (loopback)
node deploy/e2e-ws.mjs ai-pc               # Remote WebSocket through /r/ai-pc/
node deploy/e2e-events.mjs 30              # watch the SSE event stream
node deploy/e2e-ui.mjs <chrome> /tmp/out   # headless UI check + screenshots
deploy/push-slave.sh agent@192.168.0.110   # copy to a slave + restart its dsh
```

## Known limitations

- **`/r/<device>/` needs relative URLs.** Plugins that call absolute URLs (`fetch('/x')`) miss the mount there. Currently that is `@liustack/modlens` (paste/config) and parts of `@goodandready/dsh-lanmode`'s own UI. Core DSH is fully relative.
- **Restart after plugin changes.** A sync that adds or removes plugins needs a DSH restart on the slave to load their host code, as the result reports. Config-only changes apply after a restart too: DSH's HMR doesn't watch bundle patch files.
- **Multiple devices on one origin.** Viewing several devices in one browser happens under one origin, so `localStorage`-based UI state (e.g. layout choices) is shared between them.