Reading guide

Nonead DSH Desktop User Manual

This is an operations manual for everyday users. It does not assume you can write code, and it does not require Node.js, pnpm, or any development tool installed beforehand — the installer bundles the whole runtime, so it works as soon as you install it.

Applies to: 2.2.8 (DSH runtime 0.2.2-rc.1) · November 2026

For: users meeting this product for the first time; read the sections in order, or jump straight to the one you need

In this manual

The thirteen sections are ordered as "set it up → use it → when things go wrong". If you only want to fix one specific problem, jump straight to Section 12.

1 · What this is — three layers; everyday use touches only the top one.
2 · Installation — which package for each platform, and how to install it.
3 · First launch — the seven-step wizard, and "closing the window is not quitting".
4 · Main interface at a glance — what each of the four areas handles.
5 · Your first conversation — how to state a request clearly.
6 · Tray menu — every system-level entry point lives here.
7 · Settings page — what each section can change.
8 · Profiles — how to switch configurations and how failures fall back.
9 · Plugins — what ships in the box, three ways to install, how to remove.
10 · Safe mode and recovery mode — how to rescue an app that a bad plugin stopped from starting.
11 · Updates — five stages and four reusable actions.
12 · Troubleshooting — a symptom table and the diagnostic export.
13 · Data and help — where files live and where to find more documentation.

1. What this is

In one sentence: it puts DeepSeek Harness's agent capabilities inside a desktop application — double-click the icon and start a conversation, letting it read and write files, run commands, and call tools.

The product consists of three layers. You only ever interact with the third one; the first two run automatically in the background.

Figure 1　The product is made of three layers; everyday actions happen on the top layer.

How does it differ from the web version? The web version can only chat. The desktop version hands the whole computer to it: read your files, run commands, install plugins, connect to your working directories — all of it happens on your machine, and data never leaves it.

2. Installation

Grab the package for your platform from the product download page and double-click it. The installer already bundles Electron, Node.js, pnpm, and a pinned version of the DSH runtime, so you don't need to install anything else. This version bundles Electron 44.0.0, Node.js 24.21.0, pnpm 11.8.0, Python 3.12.14, and DSH runtime 0.2.2-rc.1.

Table 1　Installation on the three platforms. If Linux reports missing FUSE, run it with `--appimage-extract-and-run` instead.
Platform	Download	How to install
Windows x64	.exe installer	Run it and follow the prompts to finish
macOS (Universal: Intel / Apple silicon)	.dmg disk image	Open it and drag the icon into Applications
Linux x64	.AppImage	Run `chmod +x` to grant the execute bit first, then double-click it or run it from the command line

Upgrading does not mean closing the old version by hand. The installer first asks the running copy to quit, force-closes it if it does not, and only then overwrites the files; if it genuinely cannot be closed, the installation reports an explicit error and stops, rather than leaving you with an app that will not open after the install. Saving your work first is still worth the habit.

Note: Windows ARM64 is currently an experimental build. The main program is ARM64-native, but some of the bundled payloads (the built-in Python / Node / Office runtimes, some native modules) are still x64, and it has not been fully validated on ARM devices — everyday users should use the x64 build.

3. First launch

The first startup prepares a default configuration automatically (a Profile named desktop) and starts the interface service locally. You will see a wizard first — seven steps in all, and you can choose "Skip setup" at any point and fill things in later on the settings page.

Table 2　The seven steps of the first-launch wizard.
Step	What it asks	Suggestion
1 Welcome	What the wizard is going to configure	Click "Start setup"
2 Window mode	Compatible / Extended / Enhanced; decides the window layout and how desktop control works	If unsure, pick "Compatible mode" — it is the most compatible; Extended and Enhanced are not supported on Linux
3 Window material	Solid background or glass background	Solid is steadier on older GPUs or over remote desktop
4 Plugin marketplace	Off / dsh-market / dsh-community-market; only one can be enabled at a time	Leaving it off works fine; turn one on when you need it
5 Phone connection	Whether to use Agents-Anywhere (Beta) to reach this computer from a phone or a browser	Leave it off if unsure; once it is on, finish pairing in the sidebar's "Phone connection"
6 Desktop notifications	Whether to send system notifications when this turn, a background task or an automation finishes or fails	Worth turning all of them on, so long tasks do not need watching
7 Browser access	Whether the current Profile may be opened in a browser, and whether that is this computer only or the whole LAN	For your own use pick "This computer only"; LAN access needs an HTTPS certificate

When the wizard finishes you land in the main interface. Closing the window is not quitting the app: by default a close only puts the window in the tray, while the background service and any running tasks carry on. To quit for real, use "Quit" in the tray menu.

4. Main interface at a glance

Table 3　The four areas of the main interface.
Area	Position	What it handles
Sidebar	Left	Session list, new session, plugin and skill entry points, phone connection, settings; collapsible
Conversation area	Centre	Messages between you and it, tool calls as they happen, file edits and command output
Input box	Bottom	Type your request; attach files, switch models, choose the working directory; interrupt at any time after sending
Desktop control bar	Top of the window	Provided by the desktop shell: back / forward, reload, window controls; its shape differs by window mode

The working directory matters. By default it can only read and write the directory you picked for that session. Checking the directory when you start a session is far less trouble than discovering later that the wrong place was edited.

5. Starting your first conversation

Start a new session and set the working directory.
Say what to do, where, and what the result should look like — in one sentence. For example: "Read the README in this directory and list every download link in it that is out of date, as a table".
Once it starts working, watch the tool calls and the files it changes; if you want a different direction, interrupt it and state the new requirement.
If you are not happy with the result, say exactly what is wrong. It revises with the context in hand, so there is no need to open another session.

Three things that make a request clear:

Scope: which directory and which files may change; do not leave it open-ended.
Acceptance: what counts as done (it runs, the tests pass, the table has no empty cells).
Constraints: what must not be touched, formats that must be preserved, whether it may use the network.

6. Tray menu

Once the window is closed, the tray icon is the way into the app. Right-click the tray icon to see:

Table 4　The tray menu.
Menu item	What it does
Open DSH Desktop	Brings the window back
New Profile…	Creates another independent configuration
Profile: <name>	The Profile in use; switch here
Mode: Enhanced / Compatible / Extended	Switches the window mode quickly (takes effect after a restart)
Check for updates…	Checks for a new version by hand
Install stable version…	Goes back from the test channel to the stable release
Enter safe mode…	Starts in a temporary environment to isolate plugin problems (see Section 10)
Leave safe mode and restart…	Safe mode only; returns to a normal start
Open DSH terminal	Opens the built-in terminal, where the `dsh` command is available
Export diagnostics…	Bundles logs and system information for a bug report
Reload interface	The same as refreshing a web page; the background service is not restarted
Restart into recovery mode	Opens the recovery assistant first, without loading the current Profile or its plugins
Quit	Quits the app for real; the background service ends with it

7. Settings page

The settings entry point is at the bottom of the sidebar (Settings → Desktop settings). The sections are:

Table 5　The sections of the desktop settings page.
Section	What you can change	Takes effect
Profile	Choose the Profile to start with, create one, delete one (deleting removes its configuration and plugin files with it)	Restart
Window mode	Compatible / Extended / Enhanced, and the window material (solid / glass)	Automatic restart after saving
Plugin marketplace	Off / dsh-market / dsh-community-market; only one at a time	Restart; after an upgrade from an older version it stays off until you pick one explicitly
Browser and LAN	Allow opening in a browser (Compatible mode only), this computer only or the LAN, the local CA certificate fingerprint and its download	Immediately or after a restart
Agents-Anywhere (Beta)	The phone connection switch; once it is on, finish pairing in the sidebar's "Phone connection"	Immediately
Desktop notifications	Turn finished / failed, background task finished / failed, automation finished / failed	Immediately
Logs	The developer log switch and the log level; logs travel with the diagnostic package	Immediately
Version and updates	Current version, check for updates, restart, restart into recovery mode	Immediately
Developer options	Reload the interface, toggle developer tools	Immediately
Bottom actions	Export diagnostics, open the DSH terminal	—

In safe mode this page is read-only, and browser access, LAN access, Agents-Anywhere and notifications are disabled as well — that is by design, not a fault.

8. Profiles: several configurations

A Profile is an independent configuration set: sessions, plugins and settings each belong to one Profile and do not interfere with the others. The usual split is "work" and "personal", or "everyday" and "trying new plugins".

Figure 2　A Profile decides which set of plugins and settings is loaded; a failed start falls through to the recovery assistant.

Three practical rules:

If one Profile is broken, another one keeps you working — you do not have to repair the broken one first.
A new Profile starts empty (only the official base components) and its plugins have to be installed again; that is exactly why it is clean.
Deleting a Profile deletes its local configuration and plugin files along with it, and cannot be undone.

9. Plugins: what ships and how to install them

9.1 What ships in the box

The installer pre-installs no third-party plugin at all. The default Profile created on first launch loads only two official base components:

@deepseek-ai/dsh-base — the Host kernel: sessions, tools, file access, model connections.
@deepseek-ai/dsh-web-app — the web interface you see.

In other words, a fresh install gives you a clean desktop app that can hold a conversation, read and write files and run commands; the plugin marketplace, expert teams, voice input, the task board, the code graph and so on are all yours to install. That is deliberate: what gets installed is your decision, and when something breaks it is easy to trace back to "the one I just added".

An earlier edition of this manual carried a list of "the 35 plugins installed on this machine". That was a record taken from one particular machine, not the shipped state, and it has been removed. To see what is on your machine, use the methods below.

9.2 Three ways to install

Table 6　The three ways to install a plugin.
Route	Good for	How to use it
Plugins page	Official and third-party plugins	Sidebar "Plugins" → "Add plugin" → "Install a third-party plugin", then enter an npm package name, a Git repository address or a local directory
Plugin marketplace	Community third-party plugins	First pick a marketplace under Settings → "Plugin marketplace" and restart, then search and install inside it
DSH terminal	Third-party plugins whose package name you know; batch operations	Tray → "Open DSH terminal", then run `dsh plugin add <package>`

The plugins page (the "Plugins" entry in the sidebar, subtitled "Install, enable, and configure plugins") does two things:

Install a new plugin: click "Add plugin", choose "Install a third-party plugin", and enter an npm package name (such as dsh-xxx or @author/plugin-name), a GitHub repository address, or a local directory. During the installation you can pick a registry: Default registry, Official npm registry, Mainland China mirror, or a custom internal npm registry.
Manage what is installed: under "Installed plugins", enable, disable, uninstall and check for updates, and see each plugin's version, source and runtime status.

Some plugins are shipped together with DSH: they show "This plugin ships with DSH" — "Enable it without downloading another copy", and enabling one is all it takes. When such a plugin is older than the current DSH version, an "Update" action appears. This group includes expert teams, voice input, the plugin marketplace, automatic review, the terminal, session search, session titles, badge skills, Ralph, chain-of-thought translation, Inspector, LiveShare, Forge, worktree tools and personalised recommendations. The heavier ones that are not installed by default (the Claude Code subagent, the Codex subagent, Computer Use desktop control) are enabled from the same page when you need them.

Base components bundled with DSH (such as dsh-base and dsh-web-app) do not appear in the manageable list on the plugins page; their runtime status is shown under Settings → "Built-in plugins".

Plugin marketplace currently offers two choices: dsh-community-market (the built-in open marketplace, which supports custom data sources) and dsh-market (a community-curated marketplace drawing on awesome-dsh-plugin). Only one of them can be enabled at a time.

Three commands in the terminal (without --profile they act on the currently active Profile):

Command	What it does
`dsh plugin add <package>`	Install
`dsh plugin remove <package>`	Uninstall
`dsh plugin update`	Update the installed plugins

9.3 Restart after installing, and confirm it loaded

A newly installed plugin is loaded after a restart — when the installation finishes, the interface says "Installed; restart DSH to load it." To confirm it is really there:

Open the plugins page and check that it appears under "Installed plugins" and is enabled.
Look in the sidebar for its entry point (a marketplace, a task board, an expert team page and so on).
If you are still unsure, open Settings → "Logs", raise the log level and restart once; a failed load usually leaves an explicit error.

9.4 Disabling and uninstalling

Disable first, uninstall second. Disabling only stops a plugin from loading at the next start: its files and configuration stay put, so you can switch it back on whenever you like. Uninstalling removes the package through dsh plugin remove, and the interface asks "Uninstall '<name>'?" and warns that what it provides goes away once it is uninstalled. The recovery assistant calls the same action "Disable".
Components that plugin management itself needs (the Host, the web service, file access and so on) are marked "Plugin management needs it; it cannot be switched off or uninstalled." — that is what keeps you from uninstalling the app into a brick. Built-in base components such as dsh-base and dsh-web-app never enter the manageable list at all; their status is visible only under Settings → "Built-in plugins".
A Profile upgraded from an older version keeps the plugin marketplace off until you explicitly pick one in settings. That is not a fault.

9.5 When a plugin breaks the app

You do not need to reinstall the system or delete the data directory. Use the recovery assistant from Section 10: first disable the plugin you added most recently under "Plugin management" and start again; if that is not enough, use "Roll back" to return to the last checkpoint that would start.

10. Safe mode and recovery mode

Both features solve the same class of problem: it will not start after something was installed. The difference is that safe mode gets you inside to work in the clean, while recovery mode stops at the door to repair.

10.1 Safe mode

Safe mode starts on its own temporary data directory: it does not read your existing plugins, settings, sessions or workspace records, so those cannot drag it down either. Your original data is not touched — not a single byte.

How to get in: tray → "Enter safe mode…"; or "Safe mode" on the first page of the recovery assistant.

What you can do in safe mode:

Find out whether it really is a plugin problem — if everything behaves in safe mode, the problem is almost certainly in a plugin or in the configuration.
Hold conversations, read and write files in the web interface, and get the urgent work done.
Read the logs and export diagnostics (the recovery assistant can export them too).

Limits (by design):

The desktop settings page is permanently read-only.
Anything that depends on persisted configuration — browser access, LAN access, Agents-Anywhere, desktop notifications — is unavailable.
A "Safe mode" banner stays at the top of the interface, reminding you that you are running in a temporary environment.

Getting out: tray → "Leave safe mode and restart…". Afterwards the temporary environment is cleaned up automatically at the next normal start, so it does not sit on disk taking up space.

10.2 The recovery assistant (recovery mode)

When you end up here:

You chose "Restart into recovery mode" from the tray, or Settings → Version and updates → "Restart into recovery mode".
Startup failed several times in a row and the app fell back to the recovery assistant on its own.
When the interface really will not come up, a separate "Recover DSH Desktop" dialog appears, so you can try recovery once more without restarting the background service.

The recovery assistant tells you three things: why you are here (a manual entry says "Entered recovery mode manually"), which Profile and which directory are in use, and where startup stopped (Electron initialisation → shell environment preparation → desktop runtime preparation → Profile selection → plugin configuration assembly → plugin services → desktop interface → startup result). Wherever it stopped is how far the problem reaches.

Table 7　The six tabs of the recovery assistant.
Tab	What it is for	When to use it
Quick recovery	The front door to safe mode, plugin management, checkpoints, Profile switching, data management and diagnostics	You do not know which one to pick — start here
Plugin management	Lists the directly installed plugins, with "Disable" (keeps the installation, does not load it) and "Uninstall"; built-in and protected items are read-only	You suspect the plugin you added most recently
Roll back	Restores a startup checkpoint: puts back the Profile, the shared `settings.yaml` and the data directory patches (including plugin enablement) as they were	You remember "it was fine yesterday"
Switch Profile	Lists the available Profiles and lets you switch or create one; the current Profile is kept	One Profile is broken; use another for now
Reset and data management	View or change the data directory, restore the default directory, reset to factory settings	Nothing else has worked
Diagnostics	View or edit `settings.yaml`, Profile patches and the plugin list, open the Profile directory, export the diagnostic package	You want the root cause, or you are filing a report

How roll back works: after every successful start the app stores a startup checkpoint — the configuration that was known to work at that moment. Rolling back moves the Profile, settings.yaml and the plugin enablement states back to that point together. A checkpoint shows one of three states: restorable, unreadable, or no checkpoint yet; "unreadable" means the checkpoint itself is damaged, so pick an earlier one.

Reset to factory settings: moves the current data directory to the trash (the Recycle Bin on Windows) as a whole, and a fresh default Profile is created after the restart. Project files outside the data directory are not deleted — it only clears its own configuration and sessions. Make sure you really no longer need the old sessions before you do it.

10.3 Getting out

Once it is fixed there is nothing to clean up by hand: leave the recovery assistant and start the app normally. If you clicked "Restart" from recovery mode, the app goes through the normal startup sequence again; if that fails it returns to the recovery assistant instead of looping forever.

11. Updates

Figure 3　The update flow.

Five stages: check → download → install → restart → confirm the version. Four actions you will reuse:

Check by hand: tray → "Check for updates…", or Settings → Version and updates → "Check for updates".
Restart: Settings → Version and updates → "Restart"; you can also click the update notice in the title bar.
Clear installation leftovers: a failed update is usually an old instance holding on to the files. Quit from the tray and run the installer again — there is no need to delete directories by hand.
Go back: from the test channel to the stable release, use "Install stable version…" in the tray; to return only to the last state that would start, use "Roll back" in the recovery assistant.

An update never touches your Profiles, plugins or session data — they live in the data directory, and the installer only replaces the program itself.

12. What to do when something goes wrong

Table 8　Common symptoms and what to try.
Symptom	Try this first	If that does not help
Double-clicking the icon does nothing / a blank window	Quit from the tray and start again; check whether an instance is already running	Restart into recovery mode and see where startup stopped
Startup hangs or keeps restarting	Recovery assistant → "Switch Profile", pick one that works	Recovery assistant → "Plugin management" → disable the one you added most recently
The interface errors after a plugin was installed; a panel returns 4xx	Disable that plugin on the plugins page, then restart	Uninstall it and use another plugin instead
A plugin is installed but has no effect	Confirm on the plugins page that it is enabled, then quit completely and start again	Look for the load error under Settings → "Logs"
The window is closed and the app cannot be found	Look at the tray icon; the app does not quit by default	Tray → "Open DSH Desktop"
A task stalls halfway	Check whether it was stopped by a safety guard or is waiting for confirmation; check the log level	Export diagnostics and report it with the time it happened
The browser will not open the interface	Check that the window mode is "Compatible mode"	Turn "Allow opening in a browser" back on in settings
LAN devices cannot connect	Check that LAN access is on and that the device has trusted the certificate	Check the firewall and whether the machine's IP address has changed
The update will not install	Quit the app from the tray and run the installer again	Export diagnostics and attach the installer's error
The settings page is greyed out and cannot be changed	Most likely you are in safe mode; look at the banner at the top	Leave safe mode and restart

Exporting diagnostics

Tray → "Export diagnostics…", or the same item at the bottom of the settings page. The package contains local paths, logs, system information and, after a crash, memory fragments. Read it yourself before sharing it: paths and session fragments can contain private material.

13. Where your data lives, and where to find help

Table 9　Where data lives. With a standalone install or a changed install directory, use the actual install path.
What	Where
Application data (Profiles, settings, sessions, plugins)	Windows: `%APPDATA%\Nonead DSH Desktop`; macOS: `~/Library/Application Support/Nonead DSH Desktop`; Linux: `~/.config/Nonead DSH Desktop`
The program itself	Windows defaults to `D:\Software\Nonead DSH Desktop` (changeable at install time); on macOS it is Applications; on Linux it is wherever the AppImage lives
Desktop logs	Switched on under Settings → Logs; exported with the diagnostic package
Session files	The session store inside the data directory; "Diagnostics" in the recovery assistant opens the Profile directory directly
Your project files	The working directories you choose for each session; they are not in the application data and are not deleted by an uninstall

Acknowledgements

This product is built on the upstream DeepSeek Harness and on the open-source community: Electron, Node.js, pnpm, Python, and the Cordis plugin system with its official bundle ecosystem. Thanks to the upstream maintainers and to everyone who contributed.

Third-party plugin authors ship their information with their own plugins; you can find it on the plugins page or in a marketplace listing. This manual no longer lists individual versions and authors, because that reflects your installation choices rather than the state the product ships in.

The manual is updated with each release. If something does not match the version you are running, please open an issue on GitHub or GitCode.