# DSH Studio **A native desktop shell for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).** Rust + Tauri 2. It supervises the local `dsh` service, reclaims every process it spawns, and never forks the upstream project to do it. [![Release](https://img.shields.io/github/v/release/Moresyl/dsh-studio?style=flat-square&color=3560e8&label=release)](https://github.com/Moresyl/dsh-studio/releases/latest) [![Downloads](https://img.shields.io/github/downloads/Moresyl/dsh-studio/total?style=flat-square&color=3560e8&label=downloads)](https://github.com/Moresyl/dsh-studio/releases) [![CI](https://img.shields.io/github/actions/workflow/status/Moresyl/dsh-studio/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/Moresyl/dsh-studio/actions/workflows/ci.yml) [![Stars](https://img.shields.io/github/stars/Moresyl/dsh-studio?style=flat-square&color=3560e8)](https://github.com/Moresyl/dsh-studio/stargazers) [![License](https://img.shields.io/badge/license-MIT-3560e8?style=flat-square)](LICENSE) [![Download for Windows](https://img.shields.io/badge/Windows-.exe%20%C2%B7%20.msi-3560e8?style=for-the-badge&logo=windows&logoColor=white)](https://github.com/Moresyl/dsh-studio/releases/latest) [![Download for macOS](https://img.shields.io/badge/macOS-.dmg-1c1c1e?style=for-the-badge&logo=apple&logoColor=white)](https://github.com/Moresyl/dsh-studio/releases/latest) [![Download for Linux](https://img.shields.io/badge/Linux-.AppImage%20%C2%B7%20.deb%20%C2%B7%20.rpm-0e9e74?style=for-the-badge&logo=linux&logoColor=white)](https://github.com/Moresyl/dsh-studio/releases/latest) Lite and Full/Offline installers · [all artifacts and checksums](#install) · [简体中文](README.zh-CN.md) For a precise platform and runtime boundary, see the [support matrix](docs/support-matrix.md). If startup or plugin installation fails, begin with the [troubleshooting guide](docs/troubleshooting.md).
Plugin marketplace in the actual Windows desktop: responsive cards, readable metadata and installed-state badges **Browse cards, review compatibility, then install** — inspect the exact package before installing through Harness's own plugin command. Installed layers can be disabled without uninstalling them. Screenshots show v0.9.19 in an isolated Windows QA environment. Local paths and LAN addresses are blurred; screenshots illustrate the interface, not test coverage.
--- | | | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **⟳ Supervised, not just launched**
Backoff restart when it exits, and a real HTTP probe every 10 seconds to catch the harness that is alive but wedged. A restart lands on a new port and the window follows it. | **⛨ Managed process trees**
Every child joins a Windows job object or a POSIX process group, so the kernel reclaims the whole tree — including the grandchildren a plain kill would orphan, and even if the shell is killed outright. | | **⬗ A plugin marketplace in the window**
Search the npm registry, see what a package declares before you commit to it, install into the hosted profile through the harness's own command. Disable a plugin without uninstalling it. | **▣ Your phone, without putting the agent on the network**
`dsh` stays on loopback, and that is not configurable. What opens is a separate gateway on one LAN address, paired by a QR code good for one device and two minutes. | ## Why this exists Session attachments support literal text, raster images and PDF previews, plus saving the original file through the system save dialog. Harness must be running to authorize the read. Original downloads are limited to 20 MiB and verified by SHA-256 before an atomic write; text previews are limited to 1 MiB. Files are saved without executing their contents. The PDF reader supports pagination, zoom, password-protected files and selectable extracted text, with a 20 MiB file limit. Its worker, fonts and decoders are bundled locally; PDF scripts are not executed. `dsh` is a local web service. Running it from a terminal works, but it leaves you managing a process by hand: finding a free port, noticing when it dies, and cleaning up the tool subprocesses it leaves behind when it does. DSH Studio makes that a window. The design goal is that the shell should be **boring** — it starts the service, keeps it alive, and stays out of the way of the harness UI. ## What it does **Keep projects, sessions and reusable instructions close.** Workspace summaries show sessions, turns, usage and recent activity, with direct navigation to associated records. Pin sessions, name them, add tags/notes and bookmark messages. The local prompt library supports editing, search, variables, preview and copying. Bounded native validation and atomic writes preserve original Harness logs; close, update and recovery protect unfinished edits. Batch pins/tags organize selected sessions. Prompt JSON import/export and personal backups preview conflicts and reject stale confirmations. Workspace browsing lazily loads directories and previews/copies bounded UTF-8 text without editing files. Find file names and paths across the workspace, navigate folder history and read wrapped, numbered previews. Project notes auto-save with durable draft recovery and revision conflicts; Git review offers per-file unified and side-by-side views. Local prompt library in the actual desktop: shared cards, tags and copy actions The prompt-library image uses v0.9.24 in isolated Windows QA, with demonstration content and processed local paths. Workspace files in the actual desktop: lazy folders, filtering, read-only text preview and copying Project notes stay separate for each workspace, with local autosave and recoverable drafts. Revision conflicts keep your text available for a separate copy. Actual desktop project notes with workspace isolation, saved status and local editing Select a changed file and compare its old/new lines side by side without modifying Git. Actual desktop read-only per-file Git review with side-by-side line numbers The file-browser image uses isolated demonstration data. Links, special files and oversized previews are rejected. **Supervises, rather than just launches.** The service runs under a supervisor that restarts it with backoff when it exits. A restart lands on a new port and the window follows it — no stale bookmarks, no manual re-launch. **Notices a service that is alive but wedged.** Watching the process is only half the job: a server that has stopped answering still has a live PID, and a TCP connect still succeeds because the kernel completes the handshake from the listen backlog. So the supervisor sends a real HTTP request every 10 seconds. Three consecutive misses and the harness is recycled. **Reclaims the whole process tree.** The harness spawns tools, which spawn their own children. On Windows the service is launched into a [Job Object] with `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE`, so the kernel tears the tree down even if the shell is killed outright. On Unix it gets its own process group and is signalled as a group. Quitting the application leaves nothing behind. Hiding the main window in the tray keeps the application and its managed processes running. **Picks its own port.** `--port 0` asks the OS for an unused one and the supervisor reads back the port the service actually bound. There is no configured port to collide with, and no scan-for-a-free-port race between the check and the bind. **Brings its own Node, if the machine has none.** Being sent to nodejs.org and told to come back is where most people stop. So the row that says Node is missing is also a button: it reads the current LTS from the official release index, downloads that build, checks it against the published SHA-256 before unpacking it, and only calls it installed once the unpacked binary answers `--version`. It lands inside the app's own data directory — nothing is added to `PATH`, nothing is written to the registry, and deleting the directory undoes it. There is a second mirror for places where nodejs.org is slow, serving the same bytes. **Installs the harness for you.** If `@deepseek-ai/dsh` is not on the machine, the row that says so is a button. It runs `npm install` against a private prefix inside the app's data directory — invoking `npm-cli.js` through the detected Node binary directly, never through a shell — and streams the output into the window while it works. **Hosts the harness instead of replacing it.** The harness UI is loaded in a frame under the shell's own title bar, so the window stays movable and closable, and switching to the control panel does not throw away a running session. Studio does not maintain an upstream fork or vendor Harness source. Its managed, exact-version client receives one deterministic native-workspace integration at install time; the runtime contract verifies that known seam and enters Repair if a future upstream version moves it. **Extends it through its own plugin system.** There is a marketplace in the window: search the npm registry, read what a package declares before you commit to it, and install into the harness's hosted profile. Installation goes through the harness's own plugin command rather than around it — no private side channel into somebody else's config. A package whose manifest declares a profile patch becomes a layer the harness loads; one that does not is labelled the plain library it is, instead of appearing as a plugin that mysteriously did nothing. An installed plugin can also be switched off without being uninstalled, so "is this the one breaking it?" costs a click rather than a download. **Reaches your phone without putting the agent on the network.** Remote access is off until you open it, and opening it does not move the service — `dsh` stays bound to loopback, which is not configurable. What opens is a separate gateway, bound to one LAN address. Pairing is a QR code, and the code inside it is good for one device and two minutes: scan it and that phone walks away with a credential of its own, which is what every request after it carries. Everything from there is spliced straight through to the harness. Paired devices are listed on the pane, and forgetting one revokes its credential and drops the connection it already had. Close the door and all of them die with it. [Job Object]: https://learn.microsoft.com/en-us/windows/win32/procthread/job-objects
Remote access controls with the gateway closed; local network address blurred **Remote access stays closed until you enable it.** Once enabled, each redeemed pairing code creates a separate device credential that can be revoked individually.
## How it works One process owns everything. The Rust side supervises the service and the WebView renders the shell; the harness itself is loaded from its own origin, so what you see is the real upstream UI rather than a re-implementation of it. ```mermaid flowchart LR phone["phone on the same network"] subgraph app["DSH Studio — one process"] ui["WebView
React shell UI"] sup["Rust supervisor
backoff · readiness · health"] gw["remote gateway
one LAN address · per-device keys"] ui <-->|Tauri IPC| sup ui <-->|Tauri IPC| gw end sup ==>|"spawn: node dsh web --port 0"| dsh subgraph guard["proc-guard — Job Object (Windows) / process group (Unix)"] dsh["dsh service
127.0.0.1:ephemeral"] t1["tool subprocess"] t2["tool subprocess"] dsh --> t1 dsh --> t2 end ui -.->|iframe loads the origin| dsh sup -.->|"HTTP probe every 10s"| dsh phone -.->|"paired by QR, then cookie"| gw gw ==>|"spliced, once the credential checks out"| dsh ``` The startup sequence is worth spelling out, because every step exists to remove a failure the terminal version has: 1. **Detect.** Every Node on the machine is probed with `--version` — including the ones a version manager installed but never put on `PATH`. The newest one that meets the minimum wins. 2. **Install, if needed.** `@deepseek-ai/dsh` goes into a private prefix under the app's data directory. Nothing is written to your global npm root. 3. **Launch.** The service is spawned into a Job Object (Windows) or its own process group (Unix), with `--port 0` so the kernel assigns the port. 4. **Read back.** The supervisor parses the readiness line the service prints and learns the port it actually bound. No guessing, no scanning. 5. **Host.** The window loads that origin in a frame, and keeps probing it over HTTP. Three consecutive misses and step 3 runs again.
Runtime page: environment checks, agent choices, and diagnostic output collapsed until needed The Runtime page after startup: environment checks and agent choices stay visible, with detailed output available on demand. Every image on this page is captured from the shipped UI by the deterministic script in media/, against a stand-in backend — which is why no real home directory, LAN address or pairing key appears in any of them.
## Install Grab an installer from [Releases]. Every tagged version is built by CI for five targets: | Platform | Artifact | | ------------------- | ------------------------------------------------------------ | | Windows x64 | `.exe` (NSIS), `.msi`, and a complete `-portable.zip` folder | | macOS Apple Silicon | `.dmg` | | macOS Intel | `.dmg` | | macOS Universal | One `.dmg` for both Intel and Apple Silicon | | Linux x64 | `.AppImage`, `.deb`, `.rpm` | The Universal macOS image is the lightweight edition. Full / Offline images stay architecture-specific because their embedded Node runtime is native code. Or through a package manager. The manifests all live in [`packaging/`](packaging) and are generated from a real release, so the version and the SHA-256 in them are never hand-typed: ```powershell scoop bucket add dsh https://github.com/Moresyl/dsh-studio scoop install dsh-studio ``` winget, Homebrew Cask and AUR manifests are written and validated but not yet submitted to their registries — [`packaging/README.md`](packaging/README.md) says exactly what each one is still waiting on. > **Signing.** The release pipeline signs macOS builds with an Apple Developer ID, > notarizes and staples them, and signs the Windows installers through Azure > Artifact Signing when those credentials are configured. Tauri updater signing > and the complete non-empty artifact matrix are mandatory. Builds without > platform credentials carry an explicit CI warning; Windows may show an unknown > publisher and macOS may require approval in System Settings → Privacy & Security. Downloading from a mirror rather than from GitHub? Releases carry a `SHA256SUMS.txt`; [`packaging/MIRRORS.md`](packaging/MIRRORS.md) covers checking a download against it, and why the checksum has to come from GitHub even when the bytes did not. No Node.js on the machine is fine — the app installs one for you. What changed between versions is in the [changelog](CHANGELOG.md). [Releases]: https://github.com/Moresyl/dsh-studio/releases ## Status The v0.9.x line is production-ready for supported desktop workflows. Windows, Linux, and macOS artifacts are built and tested in the release matrix; platform publisher signing and physical Apple-device acceptance remain separately tracked release conditions. | | | | ---------------------------------------------- | ------------------------------------------------------------------- | | Environment detection, one-click install | ✅ | | Supervisor, backoff restart, health probing | ✅ | | Process-tree reclamation (Windows / Unix) | ✅ | | Harness hosting, log console, English + 中文 | ✅ | | Harness 0.1.7 plans, goals, jobs, workflows | ✅ qualified runtime and real-Profile boot | | Subagents, user questions, deliverable preview | ✅ | | Agent Preset editor and portable packages | ✅ migration, native open/drop, SHA-256 review | | Plugin marketplace — install, switch, remove | ✅ | | Remote access, single-use QR, revocable keys | ✅ | | Signed in-app update, checked on a schedule | ✅ | | Verified on Windows 11 | ✅ | | macOS / Linux platform builds | ✅ compiled and tested in the platform CI matrix | | Node runtime fetched and verified on demand | ✅ no system Node needed | | Updater signatures and `SHA256SUMS.txt` | ✅ mandatory; OS signing is applied when credentials are configured | | Download page, five packaging channels | ✅ manifests generated and validated in the release pipeline | | Tray icon, close-to-tray while serving | ✅ | | Native context menus, saved window bounds | ✅ | | Light and dark, following the system or not | ✅ | | Profile manager, import/export and comparison | ✅ | | Terminal, session search/usage/export, windows | ✅ | | Compatibility / Quick actions / Advanced pages | ✅ | | Fixed or random loopback port | ✅ occupied fixed ports fail clearly | | Renderer-independent startup recovery | ✅ static native retry/diagnostics/quit | | Read-only Host plugin contract | ✅ Host Protocol 1; no package or command authority | | Silent self-update | ⏳ planned | | Packaged releases | ✅ Windows installer + portable, Linux, macOS native + Universal | ## Design notes Three decisions shape everything else here, and each one gives something up. **The upstream service is hosted, not forked.** Vendoring the harness into this repository would buy direct control of its UI, at the price of merging every upstream release forward forever. Hosting it unmodified gives up that control — the plan for extending the UI is to go through the harness's own plugin system rather than around it — and takes upstream updates for free. A plugin installed from the shell's own marketplace is the supported way to change what the harness does. **Shutdown is the kernel's job, not a signal's.** Killing the process you spawned does not kill the tools it spawned, and on Windows there is no process group to fall back on — so a shell that crashes can strand a compiler, a test runner, or a language server nobody can now see. A Job Object makes the kernel responsible for the whole tree, which is why closing this window is enough even when the closing was not graceful. **The service stays on loopback; reach is a separate, authenticated door.** Binding an agent that can run shell commands to a LAN interface is not something to do by default, and not something to do without a credential. Remote access is off until you turn it on, and when you do, a gateway holding one credential per paired device proxies to a service that never stopped being loopback-only. Any one of those credentials can be taken back on its own, mid-connection. ## Requirements - **Nothing you have to install first.** DSH Studio needs Node.js 22.19 or newer to run the harness, and it finds one if you have it — including the ones a version manager installed but never put on `PATH`. If you do not, it downloads and verifies one into its own data directory. The harness itself is installed for you either way. - Releases provide two editions. **Lite** is the smaller installer and downloads verified runtimes only when needed. **Full / Offline** carries the platform's Node.js archive and the complete tested DSH dependency closure, verifies both again before extraction, and can finish first-run setup without a network. - Windows 10/11 with WebView2 (present on Windows 11 by default). ## Building from source ```sh pnpm install pnpm tauri dev # run it pnpm bundle:local # produce unsigned installers for local verification # The release workflow prepares src-tauri/runtime-cache/offline and merges # src-tauri/tauri.full.conf.json to produce the Full / Offline edition. ``` `bundle:local` deliberately skips updater and platform signing because developer machines do not carry the release private keys. Official releases are built by the release workflow, which fails closed unless the updater artifacts are signed. Checks: ```sh pnpm lint # ESLint, zero warnings pnpm exec tsc --noEmit # strict TypeScript pnpm test # store and i18n behaviour cargo test --manifest-path src-tauri/Cargo.toml --workspace ``` ## Layout ``` src/ React 19 + Tailwind 4 shell UI src-tauri/src/harness/ supervisor, readiness parsing, health probe, install src-tauri/src/remote/ LAN gateway, pairing codes, QR, address selection src-tauri/src/plugins/ registry search, profile inspection, install/switch/remove src-tauri/crates/ node-runtime/ find a usable Node on this machine proc-guard/ kill a process tree and mean it ``` `node-runtime` and `proc-guard` are deliberately free of Tauri and of anything specific to this app — they are two small crates that answer two questions any desktop app wrapping a Node service has to answer. ## FAQ Documentation hub: [Docs](docs/index.md) · [User guide](docs/user-guide.md) · [Troubleshooting](docs/troubleshooting.md) · [Architecture](docs/architecture.md) · [Plugin and catalog development](docs/plugin-development.md) · [Plugin interoperability contract](docs/plugin-interoperability.md) · [Protocol 3 SDK](sdk/README.md) · [Current roadmap](docs/ROADMAP.md). **Does this replace the harness UI?** No. The harness is loaded from its own service, unmodified. What the shell adds is the window around it, and everything needed to keep the service alive inside that window. **Do I need to install `dsh` myself?** No. If it is missing, the row that says so is a button. It installs into a private prefix inside the app's data directory rather than your global npm root, so nothing on the rest of your machine changes. **Do I need Node.js installed?** No. If you have one the shell uses it — including the ones nvm, fnm or Volta installed but never added to `PATH`. If you do not, the row that says so is a button: it fetches the current LTS, checks it against the published SHA-256, and keeps it inside the app's own data directory. Your `PATH` is not touched, so this cannot disturb a Node you rely on for something else. **Which port does it use?** Whichever one the kernel hands out. `--port 0` means there is no configured port to collide with, and the supervisor reads the real port back from the service's own readiness line. This is also why a restart can land somewhere else and the window simply follows. **I closed the window and the harness kept running.** That is deliberate, while a service is up. The window hides to the tray and the service keeps working; the close button says so on hover. Quit from the tray menu to stop everything. **Does closing the app leave processes behind?** It should not, including if the shell is killed outright rather than closed. That is what `proc-guard` is for. If you ever find an orphan, that is a bug worth reporting. **How do I use it from my phone?** Open the Remote pane, press Open access, and scan the code with the phone's camera. Both devices have to be on the same network — there is no relay and no account, so nothing about the pairing leaves the room. The code is good once and for two minutes; the phone that redeems it gets a key of its own, and the pane lists it afterwards, so that key can be taken back without disturbing anything else that paired. **Can I install any npm package as a plugin?** You can install any package, but only one that declares a profile patch in its manifest becomes an active layer — the marketplace says which is which before you install. Plugins land in the harness's own profile through its own plugin command, so what the shell installs is exactly what the harness would have. **Is my data sent anywhere?** The shell makes exactly one request you did not ask for: a GET to this repository's public release feed, shortly after launch and every six hours after, to find out whether there is a newer version. No account, no identifier, nothing about your machine. That is the whole list. Everything else stays where it is. The service is bound to loopback and that is not a setting — an agent that can run shell commands has no business being reachable by default. Remote access does not change it: the service stays on loopback, and what listens on the network is a gateway that will not forward a byte without a credential it minted itself. It is off until you switch it on, and it goes off again the moment the harness stops. What the harness itself does with your API keys is upstream's business, not this project's. ## Community | Where | For | | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | [Report a bug](https://github.com/Moresyl/dsh-studio/issues/new?template=bug_report.yml) | The form asks for the platform, the Node and the log up front — the three things triage needs. | | [Ask for a feature](https://github.com/Moresyl/dsh-studio/issues/new?template=feature_request.yml) | Including "the harness can do this from a terminal and the window cannot". | | [Report something privately](https://github.com/Moresyl/dsh-studio/security/advisories/new) | Anything about the gateway, the pairing keys, or the supervisor. See [SECURITY.md](SECURITY.md). | | [The harness itself](https://github.com/deepseek-ai/deepseek-harness/issues) | The agent, its UI, its models. This repository is only the window around it. | Participation is governed by the [Code of Conduct](CODE_OF_CONDUCT.md) ([中文](CODE_OF_CONDUCT.zh-CN.md)). Issues in Chinese are welcome and get answered in Chinese — the app, the README, the changelog and the contributing guide are all bilingual, and so is triage. ## Contributing Issues and pull requests are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) ([中文](CONTRIBUTING.zh-CN.md)) for how to set up, what the checks are, and how commits are worded here. The one house rule is in the code style: comments explain _why_ a thing is the way it is, not what the line below does. ## Star history [![DSH Studio star history](https://api.star-history.com/svg?repos=Moresyl/dsh-studio&type=Date)](https://www.star-history.com/#Moresyl/dsh-studio&Date) ## License [MIT](LICENSE). DSH Studio is an independent project. It is not affiliated with or endorsed by DeepSeek.