omdsh-remctrl
English | 中文
Remote control for the DeepSeek Harness:
turn it on and this machine's own dsh window appears at a public address, behind
a passcode. Not a companion app and not a subset — the same sessions, the same
buttons, the same everything, because it is dsh, forwarded.
What it adds
| Surface | Where it comes from |
|---|
| A second listener, in front of the harness's own | A node:http server this plugin binds; the harness's webServer never moves |
| The whole interface, at a public address | An HTTP and WebSocket reverse proxy to 127.0.0.1:<webServer.port> |
| A passcode form at any path | The gate's own page, served in place of the app until a browser signs in |
| A session cookie | HttpOnly; SameSite=Lax, Secure under the tunnel; the only credential a foreign web app carries by itself |
An https:// address with no setup | A supervised cloudflared quick tunnel, spawned as a child process |
| One card in the Plugin hub | An entry in omdsh.plugin.card, @omdsh-plugins/omdsh-plughub's slot |
| The switch, the passcode, the browser list, the door's log | ctx.connection.rpc at authority: 'loopback' |
One way in
There is a single door and it is a reverse proxy. Requests arrive on a port this
plugin binds, the passcode decides whether they go any further, and the ones that
do are handed to the harness's own loopback port — HTTP and both WebSocket
downlinks, verbatim.
How that port becomes reachable is the only choice you have, and it has a
default:
- Leave
publicHost empty. cloudflared opens an outbound quick tunnel and
hands back an https://….trycloudflare.com name. Nothing to forward, no
firewall to open, no certificate to arrange. This is the case for every laptop,
and it is what happens if you change nothing but the switch.
- Set
publicHost when this machine already has a public address —
121.43.252.12, harness.example.com. The door binds every interface and
people reach it directly. That is plain HTTP, so it stays shut until you set
allowInsecure by hand.
Nothing else is configurable, because nothing else needs to be.
What the passcode is holding
Everything.
An earlier version of this plugin served a small purpose-built app through a
method allowlist, at a tier the desktop chose, and could honestly say a phone was
less powerful than the desktop. Forwarding the real interface ends that promise,
and ends it deliberately: the proxy rewrites the Host header to loopback, which
is what makes the harness's own trust fence pass, and which means a signed-in
browser reaches every loopback-fenced method the desktop can — settings,
credentials, tool approvals, a shell.
So the controls around the passcode are not features. They are the design:
- Off by default.
enabled is false. Installing this plugin changes
nothing about the machine until somebody opens its card and turns it on.
- Nothing is forwarded before the cookie resolves. Not the index, not an
asset, not a WebSocket handshake. A signed-out browser reaches the passcode
form and two files, and that is the whole of the public surface.
- Six tries a minute, per address. A ten-character passcode is fifty bits,
which is not a key — it is a passcode with a token bucket in front of it, and
the bucket is what makes ten characters enough to type on a phone.
- The provenance fence, re-imposed at the public boundary. The harness
refuses cross-site requests and mismatched
Origins, and rewriting Host
upstream would remove its copy of that check — so the gate asks the same three
questions first, about the address the browser actually used.
- A transport check. Under the tunnel a request that did not arrive over
HTTPS is refused with
421 before a credential is read off it, so a
misconfigured carrier is one refusal rather than a session cookie in the clear.
A sixth thing follows from the shape rather than being added to it: the controls
ride ctx.connection.rpc at authority: 'loopback', so they are the harness's
fence and not one written here. That fence now admits a signed-in browser too —
by design, and it cuts the useful way as often as not, because you can turn
remote control off from the phone you left the building with.
Signing in
The card shows three things: the address, a link with the passcode already on it,
and the passcode itself.
Send the link to your phone and tap it. The gate takes the passcode off the
query, sets the cookie, and redirects to the same URL without it — so it is gone
from the address bar, though not from that browser's history, which is what a
magic link costs. Type the passcode instead if you would rather; case does not
matter and neither do dashes, and the alphabet has no I, L, O or U in it
so nothing is ambiguous on a screen.
A browser stays signed in for sessionTtlDays. The card lists every one that is,
signs any of them out at once, and signs out all of them together behind a
two-step confirmation. Minting a new passcode changes only the way
in — browsers already signed in stay signed in, because a passcode read over
your shoulder and a phone left in a taxi are different problems with different
answers.
What happened at the door
The card keeps a log of it: every sign-in that worked, and every one that did
not, with the address it came from. A grant also prints a line the moment it
happens — a new browser signed in — iPhone from 203.0.113.9 — so a terminal
that is open says it out loud.
A record rather than a notification, and the distinction is the point: a
notification reaches whoever is looking, and the case worth catching is the one
nobody was looking at. The log survives a restart, holds the last 50 events, and
carries a count of what is new since you last read it.
Failed attempts from one address fold into a single row with a count on it —
otherwise a machine grinding at the passcode, throttled to six a minute, would
still push every real event out of a bounded log inside ten minutes. Nothing is
said out loud until the sixth failure from an address, which is the point at
which it stops looking like somebody mistyping and its throttle budget is spent.
The log can be cleared, and clearing it leaves one row saying so. Anyone who
can sign in can clear it — it is behind the same passcode as everything else —
so the question is not whether an intruder can erase their tracks but whether
the erasure is visible. One row naming the time and the count costs nothing and
is what keeps a wiped log from looking exactly like a log where nothing ever
happened.
On a phone
The harness's interface has no width media query anywhere in it. What it does
have is one breakpoint in JavaScript: below 1024px it collapses the sidebar to a
56px rail, so a phone already gets a rail plus a conversation rather than three
columns fighting over 390px.
Two things it does not handle, and this plugin adds both — to the forwarded copy
only, never to the window on your desk:
- The keyboard. The harness sizes itself at
height: 100%, which on iOS
resolves against the layout viewport — and the layout viewport does not shrink
when the on-screen keyboard appears, so the composer ends up behind it with no
page scroll to reach it. A few lines of script publish visualViewport as a
custom property and the app is sized from that instead.
- The expanded sidebar. Tapping the rail re-expands it to 280px and leaves
the conversation about 110px wide. On a narrow viewport it overlays the
conversation instead of taking a track from it.
Both hang off data-shell-overlay and data-sidebar-collapsed, the two
attributes the harness's frame writes deliberately — never a CSS-module class,
every one of which is a build hash. A harness that stopped writing them leaves
the page exactly as it ships rather than broken.
Configuration
Everything lives in the omdsh-remctrl settings namespace, and the card in the
Plugin hub is the form for it. Five fields, of which most people touch one.
| Field | Default | What it is |
|---|
enabled | false | The switch. Nothing listens until it is on. |
publicHost | '' | The address people reach this machine at, if it has one. Empty means cloudflared fetches one. No scheme, no port. |
port | 3081 | The port the door listens on — not the harness's own. |
allowInsecure | false | Serve a publicHost over plain HTTP. Required before one will open at all. |
sessionTtlDays | 30 | How long a signed-in browser stays signed in. 0 means forever. |
Three more are written by the plugin: passcode, minted the first time you turn
it on and declared .role('secret'); browsers, which holds a hash of each
session token and never a token; and access, the door's log.
Install
npx @omdsh-plugins/omdsh-plughub add omdsh-remctrl
That is the plugin hub's own
installer with argv instead of a button. It resolves this plugin through the
collection's registry, installs it
from its GitHub repository, and writes the pnpm build-allowlist entry — which a
bare dsh plugin add github:… leaves to you, and which carries a commit hash
pnpm resolves, so it can only be copied out of an error message afterwards.
dsh plugin --profile web add @omdsh-plugins/omdsh-remctrl is not that
command yet: this package is not on npm, and pnpm answers
ERR_PNPM_FETCH_404. The same install is also a button, on this plugin's card
under Settings → Plugins → Plugin hub, whenever the hub is already in the
profile.
Or from a checkout, which is what an unpublished build wants:
pnpm install && pnpm run build
dsh plugin --profile web add "$PWD"
Remove it the same way:
dsh plugin --profile web remove @omdsh-plugins/omdsh-remctrl
cloudflared is not bundled and is not installed for you. On macOS:
brew install cloudflared; otherwise see
Cloudflare's downloads.
The card says so when it is missing, and a machine with a publicHost never
needs it.
The off states, per CONVENTIONS rule 9. Without
@omdsh-plugins/omdsh-plughub the card has no slot to sit in and withdraws;
every value stays editable through the hub's generic form or the settings file.
Without a webServer — a TUI profile — there is no interface to forward, and the
plugin says so instead of opening a door onto nothing. Without settings the
passcode and the signed-in browsers live in memory until restart. A remove
leaves the settings section behind, so reinstalling keeps the passcode.
Commands
pnpm install
pnpm run build # tsdown bundles the host and browser halves
pnpm run typecheck
pnpm run test
pnpm run harness:local # point the harness dependencies at a local checkout
pnpm run harness:npm # point them back at the published versions
pnpm run check:harness-pin
Known limitations
- A signed-in browser is the desktop. There are no tiers and no read-only
mode. That is what forwarding the real interface means, and it is why the
passcode is the whole of the security.
- A quick tunnel's hostname changes on every restart. Cloudflare's
account-less tunnels are ephemeral and carry no uptime guarantee, so the card
shows the current address rather than a saved one, and a link you sent
yesterday will not work today. A named tunnel is not supported yet.
- Everything crosses Cloudflare. Under the default carrier the TLS is
theirs, so the traffic is in the clear on their side of it.
publicHost with
your own reverse proxy in front is the answer if that matters.
- The details pane is unreachable on a phone. The harness's column solver
closes it whenever the conversation would fall below 640px, which is always on
a phone, and nothing in the forwarded DOM distinguishes "closed because it
does not fit" from "closed because you closed it".
- The phone stylesheet is unverified on hardware. It is written from the
harness's own layout source and covered by tests that read it, not by a device.
- One tunnel, one door. Two harnesses on one machine need two ports, set by
hand; nothing here discovers a free one.
