dsh-desktop

Languages: English | 简体中文

DSH desktop surface: one command starts DSH + a native Electron window with no local HTTP server, reusing the DSH Web UI with zero customization.

Overview

dsh-desktop is a DSH bundle patch plugin (cordis.patch.yml) that provides a desktop surface. Starting with DSH 0.1.5, the desktop profile name is reserved for the official Electron application and the CLI rejects boot, config-dump, and plugin-management requests for it; this project therefore uses the non-reserved dsh-desktop profile. The plugin disables DSH's node:http web server, provides a non-listening webServer-shaped service, and launches a native Electron window that loads the DSH Web UI through a custom dsh-desktop:// protocol.

Unlike dsh web, which starts a local HTTP server and requires you to open a browser manually, dsh --profile dsh-desktop reuses the entire DSH Web frontend and Cordis services with no TCP listener: Electron loads the frontend through a custom protocol, and fetch plus the event streams are bridged over IPC to the host process.

Features

• One command, ready to use: dsh --profile dsh-desktop opens the desktop window automatically — no need to visit the browser.
• Terminal released immediately: launched from an interactive terminal, the plugin hands the desktop instance to a detached child process, so the command returns to the shell prompt at once while the window and agent keep running in the background; logs land in ~/.dsh/desktop.log.
• No local HTTP server: no node:http and no TCP listening port; static assets, APIs, and event streams all travel over Electron IPC / custom protocol.
• Full DSH Web reuse: the frontend UI, session/workspace persistence, agent, and tools are all provided by DSH's existing Cordis services.
• DSH-styled title bar: the OS title bar is hidden, but a preload script injects a visible title bar styled with DSH's theme tokens, while the native minimize/maximize/close controls stay as a color-matched overlay.
• Bidirectional shutdown cleanup:
  • Closing the Electron window makes DSH dispose itself (shutting down the agent and related services), leaving no orphan processes;
  • If the DSH parent process exits, Electron detects it every 2 seconds and quits, leaving no orphan windows.

How It Works

dsh --profile dsh-desktop
        │  interactive terminal? → hand off to a detached child, then exit
        ▼
DSH boot (web-app bundle + desktop patch)
        │  patch disables dsh-host-webserver;
        │  the desktop plugin provides a non-listening webServer-shaped service
        ▼
src/index.js apply(ctx)
        │  after the loader settles, spawns Electron and establishes an fd-3 pipe RPC
        ▼
Electron creates a frameless BrowserWindow and loads dsh-desktop://127.0.0.1/
        │  the main process forwards static/API requests over fd-3 to DSH
        ▼
preload.cjs bridges fetch and /api/remote.mux → ipcRenderer → main process → fd-3 → DSH services
        │
        ▼
preload.cjs injects the DSH-styled title bar and bridges fetch plus /api/remote.mux to IPC

The Electron main process completes DSH 0.1.2's token/cookie exchange and injects the signed cookie into every bridged request; the desktop still never opens a TCP listener.

Requirements

• Node.js 24+ (the repo is pure ESM, "type": "module")
• npm (for installing dependencies and running development scripts)
• DSH CLI (dsh, 0.1.2-rc.1 or later with the Remote API; use the dsh-desktop profile on DSH 0.1.5+)
• Model credentials configured in DSH before running real sessions (e.g. DEEPSEEK_API_KEY)

Installation

Option 1: Download a release (recommended, no npm install)

1. Download the archive matching your system from the Releases page, e.g. dsh-desktop-0.1.0-win32-x64.zip (Windows), dsh-desktop-0.1.0-linux-x64.tar.gz (Linux), or dsh-desktop-0.1.0-darwin-* (macOS).
2. Extract it anywhere.
3. Link the extracted directory into DSH's dsh-desktop profile. If the profile does not exist yet, initialize it once first:

# First use only; DSH >= 0.1.5
dsh --profile dsh-desktop --from-default-profile web --dump-config

Then install the plugin:

# Windows
dsh plugin --profile dsh-desktop add link:D:\path\to\dsh-desktop-0.4.0-win32-x64

# macOS / Linux
dsh plugin --profile dsh-desktop add "link:/path/to/dsh-desktop-0.4.0-linux-x64"

Release archives bundle a platform-specific Electron runtime under dist/electron/runtime/, and the plugin prefers it, so no npm install is required.

Option 2: Install from source (development)

# 1. Clone and enter the project
git clone <repo-url>
cd dsh-desktop

# 2. Install development dependencies (includes Electron; this package has no dependencies)
npm install

# 3. Link this plugin into DSH's dsh-desktop profile
# If the profile does not exist yet, initialize it first:
dsh --profile dsh-desktop --from-default-profile web --dump-config

# Windows
dsh plugin --profile dsh-desktop add link:D:\path\to\dsh-desktop

# macOS / Linux
dsh plugin --profile dsh-desktop add "link:$(pwd)"

Notes:

• dsh plugin add forwards the remaining arguments to pnpm inside the profile directory, so pnpm's link: protocol is supported.
• In development the plugin resolves electron from this repo's node_modules (so step 2, npm install, is required); if that is missing, it falls back to the packaged Electron runtime under dist/electron/runtime/.
• Apart from Electron, DSH host modules (the web frontend, dsh-web-app, dsh-client-connection, dsh-api-gateway, dsh-api-remotes, etc.) are resolved by the DSH runtime, so this package declares no runtime dependencies.

Usage

dsh --profile dsh-desktop

After startup, the Electron window opens automatically and loads the DSH Web UI — just chat in the window.

Terminal behavior

Run from an interactive terminal, the command returns immediately: the plugin notices it is on a foreground terminal and hands the desktop instance to a detached child process before exiting itself, so it never occupies a terminal window or tab; closing the window still shuts the background instance down (unchanged behavior).

The detached instance appends stdout/stderr to ~/.dsh/desktop.log (override with DSH_DESKTOP_LOG): when no window appears, that file is the first place to look — startup failures and Electron crashes both land there.

To inspect arguments forwarded to the web app:

dsh --profile dsh-desktop --help

Development

Run from the repository root:

Commit conventions:

• Husky's commit-msg hook runs commitlint; commit messages must follow Conventional Commits.
• GitHub Actions runs lint, test, and format:check on pushes and PRs to main (Node 24).

Project Structure

dsh-desktop/
├── src/
│   ├── index.js               # desktop surface plugin: provides the webServer-shaped service and launches Electron
│   ├── electron-web-server.js # non-listening webServer service: route registry + IPC dispatch + fallback
│   ├── ipc-channel.js         # DSH ↔ Electron main-process fd-3 framing + RPC
│   └── startup.js             # session-identity helper (not referenced by the current patch)
├── apps/electron/
│   ├── main.js                # Electron main process: dsh-desktop:// protocol, fd-3 RPC, frameless window
│   ├── preload.cjs            # preload: fetch + /api/remote.mux bridge + DSH-styled title bar
│   └── package.json           # Electron app metadata
├── test/
│   ├── index.test.js
│   ├── electron-web-server.test.js
│   ├── ipc-channel.test.js
│   └── startup.test.js
├── scripts/
│   └── package.mjs            # packages the Electron runtime + creates release archives
├── dist/                      # build output (git-ignored; generated by npm run package / dist)
├── cordis.patch.yml           # DSH bundle patch: desktop plugin + disables webserver + suppresses fake URL
├── package.json               # package metadata, npm scripts, dsh.bundle.patch pointer
├── eslint.config.js
├── .prettierrc.json
├── commitlint.config.js
├── .husky/commit-msg          # Conventional Commits gate
├── .github/workflows/ci.yml   # CI: lint + test + format check
├── .agent-workflow/           # Dev Agent Workflow docs
└── LICENSE                    # MIT

Environment Variables

The plugin sets the following variables automatically when launching Electron; they only need to be set manually when running apps/electron standalone.

License

MIT