@ignotuss/dsh-desktop-bridge
经过令牌身份验证的回环 HTTP API，允许任何本地程序驱动正在运行的 DSH（DeepSeek Harness）主机的会话
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:ignotuss/dsh-desktop-bridge#8b28926c09e609a2ff004527cf4976c5d6dbdb2dDesktop Bridge 以 @ignotuss/dsh-desktop-bridge 发布，当前版本为 0.1.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
A token-authenticated HTTP API on 127.0.0.1 that drives the sessions of a
running DSH (DeepSeek Harness) host — the desktop app, or a dsh web
server. Any local program can call it: a script, a build tool, an agent from
another vendor, curl.
Security-sensitive. While this plugin is enabled, any process that can read
<DSH_HOME>/desktop-bridge.jsoncan list your sessions, read their events, send messages into them, and create new ones — each new session starting an agent that runs with your permissions. Read SECURITY.md before installing, and disable the plugin when you are not using it.中文文档见 README.zh.md。
DSH keeps session control inside the host process, as the sessionController
service. That is deliberate, and it is why the usual routes do not reach an
already-running app:
dsh --profile desktop … refuses outright — error: profile "desktop" is managed exclusively by the Electron application. The CLI can neither boot nor
install into the profile the desktop app owns.This plugin runs inside that host and republishes its sessionController on a
loopback port behind a bearer token. Nothing else changes: no second profile, no
session file is written by the bridge itself, no remote access.
| Package | Mechanism | Who can drive DSH with it |
|---|---|---|
| this plugin | loopback HTTP + bearer token | any local process, any language, curl |
dsh-session-bridge | agent-facing tools registered inside DSH | only a DSH agent, from its own prompt |
dsh-agent-bridge | spawns coding-agent CLIs through recipes | other agent CLIs, not arbitrary programs |
dsh-desktop-bridge (npm, another author) | read-only fetch route | read-only, no create/send |
The npm name dsh-desktop-bridge is taken by an unrelated read-only package,
which is why this one is published under a scope.
@deepseek-ai/dsh-web-app (both the
desktop app and dsh web do). That bundle mounts
@deepseek-ai/dsh-api-session-controller, which provides the
sessionController service this plugin injects.If your session runs the cordis agent preset, the agent has a plugin-management
tool and can do the whole thing itself — just say:
安装插件 @ignotuss/dsh-desktop-bridge
The standard and ptc presets switch that tool off; on those presets the agent
has no way to install anything and must fall back to the commands below. In the
desktop app, switch the preset under Settings → Agent preset first if you want
the by-chat route.
web, tui, headless)dsh plugin --profile web add @ignotuss/dsh-desktop-bridge
The package is a bundle: its cordis.patch.yml mounts the plugin, so installing
is also enabling. Restart the profile (or rely on HMR where it is switched on),
then confirm the plugin is listed as active under Settings → Plugins.
The desktop app owns its profile, so the CLI refuses it by design. Use Plugins → Add plugin in the sidebar with the package name (or a local checkout path) and choose Enable now. To pick up an edited source file later, toggle that plugin's switch off and on again — a live profile recomposes in place, no app restart needed.
Installing the package also installs a dsh-desktop-bridge command:
dsh-desktop-bridge list
dsh-desktop-bridge create ~/projects/demo "Release triage"
dsh-desktop-bridge events session-1f0e…-… 50
dsh-desktop-bridge send session-1f0e…-… "Please summarise the failing tests."
Every request needs the bearer token from <DSH_HOME>/desktop-bridge.json, which
the plugin writes on mount and deletes on unmount:
{
"version": 1,
"address": "127.0.0.1",
"port": 63339,
"token": "…64 hex characters…",
"pid": 30820,
"startedAt": "2026-10-02T02:31:07.114Z"
}
The port and the token are regenerated on every mount, so re-read the file after a reload instead of caching it.
| Method | Path | Body / query | Result |
|---|---|---|---|
GET | /v1/sessions | — | 200 {items: […]}, the host's session list with live projections |
POST | /v1/sessions | {cwd, title?} | 201 with the created session, 400 on a bad cwd/title, 403 when disabled or outside the allowlist |
GET | /v1/sessions/{id}/events | ?limit=1..100 (default 30) | 200 {sessionId, events: […]} — the tail of the event log |
POST | /v1/sessions/{id}/messages | {text} (1–4096 bytes) | 200 {accepted, requestId}; the text is appended as a user turn |
With curl:
read -r PORT TOKEN < <(node -e '
const d = require("node:fs").readFileSync(process.env.DSH_HOME + "/desktop-bridge.json", "utf8")
const j = JSON.parse(d); console.log(j.port, j.token)')
curl -s -H "Authorization: Bearer $TOKEN" "http://127.0.0.1:$PORT/v1/sessions"
curl -s -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
-d '{"cwd":"/home/me/projects/demo","title":"Release triage"}' \
"http://127.0.0.1:$PORT/v1/sessions"
Requests carrying a browser Origin header are refused, and Host must name the
loopback address and port, so a web page cannot reach the bridge even by DNS
rebinding.
The plugin reads an optional config block from its patch row; every key is
optional and the permissive value is the default:
- id: desktop-bridge
config:
allowCreate: false # default true — false rejects POST /v1/sessions
auditLog: true # default true — one JSON line per request
cwdAllowlist: # default [] — no restriction
- 'C:\work'
allowCreate — false leaves listing, reading and messaging working while
removing the ability to start new agents.auditLog — appends one JSON line per request to
<DSH_HOME>/desktop-bridge.log: time, method, path, route, status, duration and
the target directory or session id. Never the token, never the message text.cwdAllowlist — when non-empty, a new session may only be created inside
one of these directories (subdirectories included).Paths given to POST /v1/sessions must already exist as directories; the bridge
does not create them.
Verified against DSH 0.2.0-rc.2 (desktop profile, Windows). The plugin is a
thin layer over five sessionController methods — list, inspect, prompt,
create, rename — and depends on no other internal API. If a DSH release
renames them, the affected route answers 500 DSH request failed and the real
message is written to the audit log; nothing else in the app is disturbed.
An install that fails for a missing service reports
sessionController is unavailable in the plugin's startup log rather than
mounting a half-working bridge.
node --test # 23 tests: routing, policy, audit, descriptor lifecycle
The tests bind ephemeral loopback ports and use a stub controller, so they need no DSH running.
MIT — see LICENSE.