DSH browser surface composition package, overlays Web host and browser plugins on dsh-base, registers frontend dist, URL output, and DSH_WEB_URL variable.
ⓘ This plugin is a sub-package of the op7418/pilot-harness monorepo — stars and activity count the whole repository.
- Language
- TypeScript
- License
- MIT
- Branch
- main
Install
$ dsh plugin --profile web add @deepseek-ai/dsh-web-appRun the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial
Install via your agent
Install the DeepSeek Harness plugin op7418/pilot-harness/packages/bundle/web-app for me: review the repository at https://github.com/op7418/pilot-harness first, then run the install command and verify the plugin loads successfully.
Paste this instruction to the DSH Web GUI assistant — it will install and verify for you.
One-Line Description
DSH's browser surface bundle. Superimposes Web host and browser plugins on dsh-base, allowing dsh --profile web to start a local GUI service.
Core Capabilities
- Superimposes Web host components (webserver, API gateway, workspace, projection cache, storage) and browser plugin combination (themes, layouts, sessions, commands, plugin center, model selection, etc.) on dsh-base
- Parses command-line parameters such as
--host/--port/--trusted-host/--help, and provides them to the host aswebStartupservice - Prints
dsh web: http://127.0.0.1:<port>after port is ready and Loader config tree is settled, to avoid announcing an invalid application when sibling processes fail - Registers
DSH_WEB_URLruntime variable in bash environment, resolved from the current listening URL on each invocation - Injects
harness:sourceandapp:web-surfacesegments into model system prompts, letting the model know it's in a GUI and that browser alternatives are not accepted - Samples IPv4 addresses from current network interfaces during listening phase, as the source for LAN trust fence
Technical Implementation
- Language: TypeScript (ESM)
- Key Dependencies:
@deepseek-ai/dsh-web-frontend(frontend dist entry),commander(CLI parsing),@deepseek-ai/cordis&@deepseek-ai/cordis-plugin-loader(plugin host) - Architecture Pattern: Cordis function plugin +
cordis.patch.ymlbundle, overlaid on dsh-base viadsh.bundle.patchmanifest field; host injectswebStartupservice, web-runtime samples bind dependency values and releaseswebRuntimeto client trust fence - Entry Files:
src/index.ts(web-runtime glue plugin) +src/startup.ts(CLI provider) +cordis.patch.yml(patch layer)
Use Cases
For end users to install the "dsh running in browser" experience: after installing a repository locally, anyone who wants a GUI instead of CLI/TTY can install this bundle; or developers need a dsh process with URL for host tools like Claude Code/Codex proxying. Also suitable as a resource supplier for dsh-frontend, where upstream packaging/distribution platforms use this bundle as the embedding point.
Prerequisites & Compatibility
| Dependency | Minimum Version | Description |
|---|---|---|
| DSH | 0.1.0-rc.7+ | Same version as monorepo; this bundle is同级 to dsh-base / dsh-headless |
| Node | ^22.19.0 || >=24.0.0 | From monorepo root package.json engines.node field |
| Platform | Cross-platform | No os/cpu restrictions declared; startup behavior doesn't depend on specific OS |
| Native Modules | None | Only uses Node built-ins node:os / node:module / node:url; no node-gyp dependencies |
Installation
dsh plugin --profile web add github:op7418/pilot-harness/packages/bundle/web-app
Configuration
Bundle's own configuration (written in web-runtime line of cordis.patch.yml)
| Config | Type | Description | Default |
|---|---|---|---|
printUrl | boolean | Whether to print dsh web: http://127.0.0.1:<port> to terminal after port is ready | true |
surfaceContext | boolean | Whether to inject "Web Surface" prompt segment and bash variable DSH_WEB_URL into model | true |
trustedHosts | string[] | Extra authority hosts passed via --trusted-host CLI parameter, appended to browser trust fence | [] |
CLI Parameters (passed via dsh --profile web)
| Parameter | Usage |
|---|---|
--host <host> | Listening host; binding 0.0.0.0 will be rejected and report usage error |
--port <port> | Listening port; passing 0 means let OS pick an available port |
--trusted-host <authority...> | Extra authority hosts allowed by browser trust fence, can be repeated |
-h, --help | Print help text for this application; service won't start during printing |
FAQ
Q: What is this bundle and what is it for?
A: It's dsh's "Web Surface" bundle, overlaying all host and browser plugins needed for a browser interface on dsh-base. After installation, start a local GUI service via dsh --profile web.
Q: What's the relationship with dsh-headless and dsh-desktop?
A: These three are同级 surface bundles on dsh-base. web-app is the browser surface, headless is the headless surface, and desktop is the desktop application; they don't nest in each other; select one via --profile to load.
Q: Will it automatically open the browser after startup? Can it be disabled?
A: This bundle itself doesn't handle launching the system browser; it only prints one line dsh web: http://127.0.0.1:<port> after port is ready. Whether other layers (like desktop or external supervisor) open the browser is outside this bundle's scope.
Q: Why is --host 0.0.0.0 rejected?
A: The bundle currently intentionally doesn't support binding to all interfaces (will report usage error and exit before activation), because this would expose remote code execution capabilities to the network. Please use 127.0.0.1 or LAN trust host mode.
Q: What to do when "frontend dist not built" is reported?
A: This means the repository hasn't built the frontend dist. This bundle treats dist path as internal workspace knowledge, requiring pnpm run build to be executed in the repository root first, then start dsh --profile web.
Q: What is the DSH_WEB_URL variable for?
A: The bundle registers a bash-visible runtime variable DSH_WEB_URL, resolved from the currently listening local URL on each invocation. Models and scripts can use it to locate the current GUI.
Q: Why are some shared tools/toolbars with dsh-base disabled?
A: Web moves the agent plane (tool-bash, tool-pwsh, tool-fs, tool-skill, tool-subagent, etc.) to session-level agent presets; the host plane only keeps registry and services, so networked agents are assembled by their respective presets.
Q: HMR doesn't seem to be working?
A: The hmr line in cordis.patch.yml is currently disabled with a TODO: re-enable after Web-side reload lifecycle testing is complete; client plugin hot reload needs to配合 pnpm run dev:web watcher to trigger.
Getting Started Difficulty
Beginner — install once, run pnpm run build and dsh --profile web to see the interface in browser; no required configuration other than --host / --port / --trusted-host.
Known Issues & Limitations
- Frontend dist must be built: The
require.resolvefor dist reports error during activation with build hints; no fallback path to serve directly from source (README.md:25) lanAddressesis a startup snapshot: Network interface changes after startup won't re-announce; printed LAN URL always matches configured trust fence (README.md:26)--host 0.0.0.0is intentionally rejected: CLI treats "bind all interfaces" as a security risk and exits during parsing without publishingwebStartupservice (src/startup.ts:69-71)hmrline is disabled: Marked with TODO in cordis.patch.yml, to be re-enabled after Web-side reload lifecycle testing completes (cordis.patch.yml:21-23)DSH_TOOLS_MODEis a temporary workaround: The entire dsh process's tools mode (native|code|both) is switched via environment variable, to be removed after Web UI can select by session (cordis.patch.yml:36-41)
Pilot Harness
English | 中文
A CodePilot-inspired desktop client and plugin suite for DeepSeek Harness.
Run the DeepSeek Harness plugin runtime as a focused native app, manage providers and multimodal models visually, and keep desktop additions isolated as ordinary Harness plugins.
Quick start · Plugins · Architecture · MIT License
Why Pilot Harness
DeepSeek Harness has a powerful “everything is a plugin” architecture, but its default experience is designed around a CLI-launched Web UI. Pilot Harness keeps that runtime model and adds the parts expected from a daily desktop product:
- A real desktop app — Electron packages the local Harness runtime for macOS, Windows, and Linux, owns native window behavior, and provides a recovery screen when startup needs attention.
- A calmer CodePilot-inspired interface — consistent tokens, radii, menus, hover states, settings cards, Markdown, conversation/trajectory navigation, and platform-aware title bars.
- Provider and model management — connect supported providers, declare an OpenAI-compatible endpoint, manage credentials separately from settings, browse the live model catalog, and identify image-capable models.
- Workspace context without clutter — project-aware conversation rows show branch, state, reminder summary, mode, and model details, while Files opens as a true right sidebar.
- Plugin-first extensions — the theme, Worktree sidebar, Schedule summary, and Session-log export remain Cordis/DeepSeek Harness rows rather than desktop-only business logic.
- Reversible customization — disabling the CodePilot theme row removes its product mark and visual overrides so the stock Harness presentation can take over again.
Pilot Harness does not replace the DeepSeek Harness agent loop, Session log, tool pipeline, provider contracts, or RPC implementation. Electron owns packaging and native integration; the composed Harness plugin tree remains the application runtime.
Quick Start
Download the installer for your system from GitHub Releases:
| Platform | Download | Install and handle the security prompt |
|---|---|---|
| macOS (Apple Silicon) | DMG installer ZIP app | Open the DMG, drag pilot-harness.app into Applications, and launch it normally. A formal Release is published only after its Developer ID signature has been verified. Because notarization is not enabled yet, Gatekeeper may still block the first launch; in that case open System Settings → Privacy & Security, click Open Anyway, then confirm Open. Do not run xattr or disable Gatekeeper for a formal Release. If macOS reports that the signed app is damaged, delete it, verify the Release checksum, and download it again instead of bypassing the warning. Apple's security instructions. |
| Windows (x64) | EXE installer | Run the EXE. If Microsoft Defender SmartScreen says Windows protected your PC, first confirm that the file came from this Release, then choose More info → Run anyway. Do not disable SmartScreen globally. A managed computer may hide this option; contact its administrator instead. Microsoft's SmartScreen explanation. |
| Linux (x64) | AppImage DEB RPM | DEB: sudo apt install ./Pilot-Harness-Linux-amd64.debRPM: sudo dnf install ./Pilot-Harness-Linux-x86_64.rpmAppImage: chmod +x Pilot-Harness-Linux-x86_64.AppImage, then ./Pilot-Harness-Linux-x86_64.AppImage. If the file manager blocks execution, enable Allow executing file as program in file properties. The preview packages are unsigned, so only accept a package-manager warning after confirming the official Release source. |
The table links to formal end-user Releases, not the seven-day Actions preview artifacts. Formal macOS files must pass Developer ID verification before publication; while they remain unnotarized, the only expected extra step is Open Anyway in System Settings. Preview macOS artifacts are ad-hoc signed for CI verification and are not the normal installation path. Once notarization is enabled, the Open Anyway step should normally disappear and this guide must be updated with the release pipeline. Windows and Linux preview installers remain unsigned. Only override an operating-system warning for files downloaded from this repository's official GitHub Release; do not turn off platform security globally.
After installation, open Pilot Harness, select a Workspace, then go to Settings → Providers to connect a provider and choose one of its available models. No separate DeepSeek Harness installation is required for the desktop app. Source setup and packaging instructions live in Development, not in the user installation path.
What is included
| Area | What Pilot Harness adds | Ownership |
|---|---|---|
| Desktop shell | Native window, local runtime lifecycle, directory dialog, recovery, installers, and platform icons | Electron app |
| Visual system | CodePilot-inspired design tokens and component contracts | @deepseek-ai/dsh-client-ui-codepilot-theme |
| Workspace Files | Right sidebar, file count, branch summary, row actions, and @path insertion | @deepseek-ai/dsh-ui-worktree |
| Reminder summary | Active reminder count and nearest scheduled time in Session hover details | @deepseek-ai/dsh-ui-schedule-summary |
| Session export | Per-Session ZIP export from the Trajectory toolbar and /export | @deepseek-ai/dsh-session-log-export |
| Providers and models | Configurable adapter, credential/settings UI, live catalog, and multimodal labels | Existing Harness plugins plus the Pilot Harness desktop profile |
The provider/model experience is deliberately a profile composition, not a new provider implementation. It mounts existing adapter, Settings, and Credentials contracts, then replaces the desktop placeholder only after a real provider advertises a usable model.
Use the plugins independently
The desktop client already includes every plugin below. If you use a local DeepSeek Harness Web profile instead, install only the feature you want with one command; each release asset is a prebuilt dsh.bundle, so no repository clone, YAML patch, or local build is required.
CodePilot theme
dsh plugin --profile web add https://github.com/op7418/pilot-harness/releases/latest/download/deepseek-ai-dsh-client-ui-codepilot-theme-0.1.0-rc.5.tgz
Applies the Pilot Harness visual system and product mark. Removing the plugin restores the stock Harness presentation. See theme details.
Files sidebar
dsh plugin --profile web add https://github.com/op7418/pilot-harness/releases/latest/download/deepseek-ai-dsh-ui-worktree-0.1.0-rc.5.tgz
Adds the Workspace-confined right file sidebar, file count, branch summary, row actions, and @path insertion. See Files plugin details.
Reminder summary
dsh plugin --profile web add https://github.com/op7418/pilot-harness/releases/latest/download/deepseek-ai-dsh-ui-schedule-summary-0.1.0-rc.5.tgz
Adds active-reminder metadata to Session hover details while the upstream Schedule plugin remains the reminder authority. See reminder plugin details.
Session-log export
dsh plugin --profile web add https://github.com/op7418/pilot-harness/releases/latest/download/deepseek-ai-dsh-session-log-export-0.1.0-rc.7.tgz
Adds per-Session ZIP export to the Trajectory toolbar and the /export command. See export plugin details.
Restart the Web profile after installation and use dsh --profile web --dump-config to confirm the added row. Files and Reminder summary require the Pilot Harness UI slot contracts included in Pilot Harness v0.1.0; older upstream Harness builds can install their bundles but cannot render those two UI contributions.
Remove a plugin with the same package name shown in its details page, for example:
dsh plugin --profile web remove @deepseek-ai/dsh-ui-worktree
Development
git clone https://github.com/op7418/pilot-harness.git
cd pilot-harness
pnpm install
pnpm run desktop:dev
Run the desktop checks with:
pnpm run desktop:test
pnpm --filter @deepseek-ai/dsh-desktop run typecheck
pnpm --filter @deepseek-ai/dsh-desktop run test:e2e
Official installers are never built or uploaded from a developer machine. Every verified push to main, and a manual workflow dispatch without a release tag, produces seven-day Actions preview artifacts on native macOS, Windows, and Linux runners. A version-matched v* tag starts the formal path, verifies the platform artifacts and macOS Developer ID signature, generates SHA256SUMS.txt, and publishes the GitHub Release.
The Sync DeepSeek Harness upstream workflow checks the newest non-draft official release every day at 09:00 Asia/Shanghai. A clean update is merged without force-pushing, verified, committed to main, and dispatched to the same native release pipeline as v<upstream-version>-pilot.1. A merge conflict opens or refreshes a GitHub Issue and stops before changing main; missing macOS signing secrets also open an issue and leave the verified source synchronized without publishing an unsigned release. Rerunning the workflow after resolving either condition resumes the pending release.
For the underlying system, read the DeepSeek Harness architecture, development guide, and desktop architecture.
Upstream, attribution, and trademark notice
Pilot Harness is an independent community project derived from the MIT-licensed DeepSeek Harness and visually inspired by CodePilot. It is not an official DeepSeek product and is not endorsed by or affiliated with DeepSeek. “DeepSeek”, “DeepSeek Harness”, and “CodePilot” remain the property of their respective owners.
License
Pilot Harness is available under the MIT License. Third-party software and licenses are listed in THIRD_PARTY_NOTICES.md.
Read the usage guide →
Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.
Listing badge
[](https://deepseek-plugin.org/plugins/op7418/pilot-harness/packages/bundle/web-app)Paste this markdown into your GitHub README to link back to this listing. The badge only states the listing — not a security endorsement.