Language: English | 简体中文

DeepShell Agent

A desktop agent powered by DeepSeek Harness.

DeepShell Agent is a desktop Agent product built on DeepSeek Harness (DSH). It combines the official DSH Web UI, a pinned DSH runtime, bundled Node.js, DeepShell first-party Bundle/Preset integration, and desktop lifecycle management to provide an out-of-the-box, recoverable, packageable local Agent workstation.

DeepShell Agent does not reimplement the Agent Runtime and does not fork the official DSH Web UI. Its architectural boundary is:

Tauri owns the desktop shell and process lifecycle; the official DSH Web UI owns the base interaction; the DSH Runtime owns the Agent; DeepShell differentiates through official extension points.

Current status

The latest published baseline is the unsigned v0.1.4 preview release. It completed Windows 11 x64 on-device acceptance and the final macOS arm64 regression, and adds per-platform runtime trimming, a Windows portable ZIP, safer Windows uninstall cleanup, and platform-specific native menus while retaining DeepSeek Harness 0.1.5-rc.1, the official Web UI, and the public-extension-point architecture.

Capabilities already included in the source baseline:

• macOS arm64 desktop app build and disk-image generation;
• Windows x64 runtime asset locking and platform-aware path baseline;
• bundled Node.js, so end users do not need to install Node.js, npm, pnpm, or DSH;
• pinned official DSH runtime;
• official DSH React Web UI;
• DeepShell first-party deepshell-desktop DSH Bundle;
• deepshell-coding, deepshell-work, deepshell-general, and legacy deepshell Agent Presets;
• DeepSeek official API, OpenAI-compatible API, and Responses API routing;
• official workspace-write Permission Preset;
• official credentials-local credential scheme;
• DeepSeek Web Search and public HTTP(S) Web Fetch;
• DeepSeek deepseek-flash / DeepSeek-V41-Flash catalog compatibility through the upstream DSH DeepSeek adapter;
• Sidecar dynamic port, token cleanup, Ready Gate, process cleanup, and basic recovery;
• bounded local pre-upgrade backup of dsh-home/sessions during the v0.1.1 to v0.1.2 runtime refresh;
• redacted local diagnostics, package-size reporting, SBOM baseline, vulnerability-audit entrypoint, and release staging automation;
• macOS E2E/Release artifact security-boundary comparison;
• per-platform runtime packaging for macOS arm64 and Windows x64;
• a Windows x64 NSIS installer and portable ZIP validated on real Windows 11 hardware;
• native macOS and Windows menu layouts with safe runtime shutdown routes.

Still required before formal signed/notarized public binary distribution:

• macOS Developer ID signing and Apple notarization;
• Windows code signing;
• release-level legal review of the generated license inventory and notices.

Completed by v0.1.3 (the two items previously listed here): Windows x64 on-device installer acceptance, and Windows WebView2 first-run / shutdown / process-tree cleanup acceptance. See the v0.1.3 closeout.

Main capabilities

Coding Mode

Coding Mode targets code workspaces. It reuses DSH file, search, Shell, test, Git, Session, and Approval capabilities for code understanding, modification, verification, and change explanation.

General Mode

General Mode provides a general-purpose Agent entry for Q&A, local tasks, and lightweight research. It is implemented as the deepshell-general Agent Preset and uses the official DSH Agent Preset UI.

Work Mode

Work Mode targets general research and text output. The MVP focuses on:

• Web Search;
• Web Fetch;
• local text/Markdown file read/write;
• structured result capture;
• session-history recovery.

Native Office/PDF/PPTX/XLSX parsing, complex knowledge bases, enterprise connectors, and dedicated document UI are not part of the current baseline.

Model Providers

The current route supports:

• DeepSeek official API;
• OpenAI-compatible API;
• Responses API.

Models, routes, base URLs, API keys, and model lists are managed through the official DSH Models Settings whenever possible. DeepShell does not create a second model registry or credential system.

Getting and running

For published binaries, use GitHub Releases. The v0.1.4 preview release provides a macOS arm64 DMG, a Windows x64 NSIS installer, and a Windows x64 portable ZIP. These preview assets are not Developer ID/notarized or Windows code-signed.

The current source baseline has not completed all formal binary-distribution gates. The public repository is primarily for source publication, architecture review, and reproducible builds. If you want to build from source, see “For contributors” below.

macOS users

Target platform:

• Apple Silicon Mac;
• macOS 13.0 or later.

For published macOS developer-preview builds, users may download the .dmg, drag DeepShell Agent.app into Applications, and launch it from there.

Developer-preview DMGs are locally signed for packaging, but they have not completed Developer ID signing or Apple notarization. macOS may show the usual security warning for non-notarized apps. Signing, notarization, and Gatekeeper verification are required before formal public binary distribution.

Windows users

Target platform:

• Windows 10 22H2 or Windows 11 x64;
• WebView2 Runtime (the NSIS installer embeds the bootstrapper and installs it automatically when missing).

Windows users can use either the NSIS installer or the portable ZIP. The portable build is extracted and launched in place, shares %APPDATA%\com.deepshell.agent with the installed build, and requires an existing Evergreen WebView2 Runtime. Do not run installed and portable forms concurrently; the product intentionally keeps a single-instance model.

The v0.1.4 preview release completed WIN-01 through WIN-13 on real Windows 11 x64 hardware, including installed/portable session creation, UI-level session and Provider sharing in both directions, portable-directory removal with retained user data, native menu inspection, orphan-Sidecar uninstall cleanup, and representative v0.1.3 session upgrade. See the v0.1.4 closeout.

v0.1.3 completed end-to-end acceptance on real Windows x64 hardware (setup wizard, first launch, data directory, credential setup, sessions and tools, single instance, dynamic ports, malicious-origin isolation, the exit-cleanup scenario tested at that time, crash recovery, diagnostics bundle, environment restoration). Acceptance found and fixed 8 Windows platform defects; see the v0.1.3 closeout.

Known limitations of the released v0.1.3 baseline (not to be read as current-branch passes):

• Uninstall does not clean up fully: later Windows measurements observed orphan Sidecar processes after both normal app close and abnormal app termination. When the orphan keeps native libraries mapped, the install directory can retain 5 files / 108.54 MB, which require terminating that process and deleting them manually. This was not fixed in v0.1.3; v0.1.4 implements and validates the REL-024 cleanup route.
• Per-platform runtime trimming was not implemented in v0.1.3: its installer bundles both the macOS and Windows Node runtimes, and the macOS half (4800 files / 187.5 MB) is entirely unused on Windows. v0.1.4 implements and validates the REL-022 macOS and Windows paths.
• Two WebView2 matrix dimensions were not measured this round: font/CJK rendering, and the file picker / drag-and-drop / clipboard.
• Dependency vulnerability audit is unavailable on this machine (the configured npm mirror has no audit endpoint), so dependencies have not passed a vulnerability scan.
• Windows code signing is not done.

The final v0.1.4 audit found no production-root, bundled-DSH-runtime, or Rust advisories. The root development/test toolchain still reports four high and one moderate warning; these are recorded as non-blocking build-tooling findings rather than shipped-runtime findings.

Usage

A typical first-run flow is:

1. Open DeepShell Agent.
2. Configure the DeepSeek official API, or add an OpenAI-compatible / Responses API Provider in Models Settings.
3. Select or create a Workspace.
4. Create a General, Coding, or Work Mode Session.
5. Ask the Agent to read, search, or modify Workspace files, run necessary commands, or use Web Search / Web Fetch for research and text output.

Permissions and credentials

DeepShell Agent uses the official DSH workspace-write Permission Preset by default:

• writes inside the Workspace are allowed according to official permission semantics;
• writes outside the Workspace, permission expansion, and dangerous requests must use official Approval or fail closed;
• Shell commands follow official DSH Sandbox/Approval semantics;
• credentials use the official credentials-local scheme.

Note: credentials-local is not the system Keychain. It can use local file permissions to separate OS users, but it must not be described as a strong security boundary between processes running as the same OS user.

Build and distribution boundary

The public source repository keeps only source code, tests, build scripts, lock manifests, and public documentation.

It does not commit:

• full runtime;
• installed dependency trees;
• build cache;
• local .app, .dmg, or installer artifacts;
• E2E and release staging manifests;
• local acceptance evidence;
• logs, screenshots, diagnostic bundles, or real secrets.

Binary packages should be distributed through GitHub Releases or another release channel. A platform-specific license/NOTICE inventory, SBOM, package report, and security-audit report should be regenerated for each binary release artifact.

License

DeepShell Agent source code is released under the MIT License. See LICENSE.

Third-party dependencies, bundled runtime components, and binary-release components remain under their own licenses. Before distributing binary packages, regenerate the platform-specific license/NOTICE inventory, SBOM, and release staging assets, then ship or publish the required notices with the release artifact. The current baseline is documented in THIRD_PARTY_NOTICES.md.

Documentation

• Architecture (中文)
• Roadmap (中文)
• v0.0.1 POC Closeout (中文)
• v0.1.0 MVP Closeout (中文)
• v0.1.1 Release-Hardening Closeout (中文)
• v0.1.2 DSH Runtime Refresh Closeout (中文)

docs/plans/ is a local process-document directory for requirement exploration, design drafts, implementation plans, and acceptance evidence. It is not published with the public source repository by default.

Branding and icon

DeepShell Agent uses an independent icon language:

• deep-sea-blue rounded square;
• bright cyan-blue minimal scallop;
• large >_ terminal prompt;
• flat, lightly skeuomorphic, and suitable for modern macOS / Windows desktop icon styles.

Current icon assets:

• src-tauri/icons/app-icon-source.svg
• src-tauri/icons/app-icon-source.png
• src-tauri/icons/icon.png
• src-tauri/icons/icon.icns
• src-tauri/icons/icon.ico

Relationship to DeepSeek Harness / DeepSeek

DeepShell Agent is an independent desktop Agent product built on DeepSeek Harness. DeepSeek Harness provides the core Agent Runtime, Web UI, and plugin mechanism; DeepShell Agent provides desktop packaging, runtime distribution, productized Bundle, default modes, diagnostics/recovery, and release workflow.

This project is not an official DeepSeek product and does not imply affiliation, partnership, authorization, or endorsement by DeepSeek. DeepSeek, DeepSeek Harness, and related names belong to their respective owners. They are used here only to describe technical compatibility and upstream dependency relationships.

For contributors

The following sections are for contributors who build, develop, and validate DeepShell Agent from source.

Technology stack

• Desktop Shell: Tauri 2 + Rust
• Web Bootstrap: Vite + TypeScript
• UI Runtime: official DSH React Web UI
• Agent Runtime: DeepSeek Harness 0.1.5-rc.1
• Bundled Node.js: Node.js 24.20.0
• Package Manager: pnpm 10.30.2
• Test: Rust test, Vitest, WebdriverIO/Tauri E2E

Source build flow

The build flow has three stages:

1. Install development dependencies.
2. Prepare the bundled runtime and DSH Profile.
3. Build the platform-specific application package on the target operating system.

The public source repository does not commit the full runtime, installed dependency tree, or local build artifacts. On first build, scripts download and verify the Node.js runtime from runtime/manifest/runtime-lock.json, then install the locked DSH production dependency tree from runtime/manifest/dsh-install/package-lock.json.

macOS arm64 build

Build environment:

• Apple Silicon Mac;
• macOS 13.0 or later;
• Xcode Command Line Tools;
• Node.js >=24.0.0;
• pnpm 10.30.2;
• Rust 1.96.0;
• macOS system dependencies required by Tauri 2.

Prepare the environment:

xcode-select --install
corepack enable
corepack prepare pnpm@10.30.2 --activate
rustup toolchain install 1.96.0

Install project dependencies:

pnpm install

Prepare runtime and Profile:

pnpm runtime:prepare --target all
pnpm runtime:verify --target all
pnpm profile:prepare
pnpm profile:verify

Run in development:

pnpm dev

Build the macOS .app, generate .dmg, and run the current macOS release checks:

pnpm package:verified

Notes:

• pnpm package:verified first builds an E2E-only .app, then builds the Release .app / .dmg, and compares their security boundaries.
• If you only need to rebuild the Release package using an existing E2E manifest, run pnpm package:mvp.
• Local .app and .dmg outputs are under the Tauri build output directory and are ignored by Git.
• The current source baseline does not include Developer ID signing or Apple notarization. Complete them separately before formal binary distribution.

Windows x64 build

Build environment:

• Windows 10 22H2 or Windows 11 x64;
• WebView2 Runtime;
• Microsoft C++ Build Tools / Visual Studio Build Tools, including MSVC and Windows SDK;
• Node.js >=24.0.0;
• pnpm 10.30.2;
• Rust 1.96.0 with the MSVC toolchain;
• Windows system dependencies required by Tauri 2.

Prepare the environment:

corepack enable
corepack prepare pnpm@10.30.2 --activate
rustup toolchain install 1.96.0-msvc
rustup default 1.96.0-msvc

Install project dependencies:

pnpm install

Prepare runtime and Profile:

pnpm runtime:prepare --target all
pnpm runtime:verify --target all
pnpm profile:prepare
pnpm profile:verify

Run in development:

pnpm dev

Build the Windows NSIS installer:

pnpm package:mvp

Notes:

• On Windows, pnpm package:mvp calls Tauri to build the NSIS installer, emits the release NSIS package manifest (runtime/staging/package-release-win32-x64-nsis-installer.json, schemaVersion: 5), and runs static security-boundary checks for the Windows release manifest. It does not run the macOS-only E2E/Release artifact comparison on Windows.
• The NSIS toolchain is downloaded automatically by Tauri into %LOCALAPPDATA%\tauri\NSIS\; it needs no separate install and no system PATH change. The WebView2 bootstrapper is cached in the same directory.
• v0.1.3 ran that Windows installer pipeline end to end on real Windows x64 hardware (compile → makensis → manifest capture → static boundary checks, exit 0); the artifact is 80.41 MB.
• The current source baseline does not include Windows code signing. Complete signing separately before formal binary distribution.
• Dependency vulnerability audit requires a working npm audit endpoint. When the configured mirror does not provide one, pnpm security-audit reports the failure honestly rather than reporting a pass.

Common development commands

pnpm check
pnpm runtime:smoke
pnpm runtime:verify --target all
pnpm profile:verify
pnpm package:e2e
pnpm package:mvp
pnpm package:verified
pnpm package:compare
pnpm licenses:collect
pnpm sbom:generate
pnpm package:report
pnpm release:stage
pnpm diagnostics:collect
pnpm release:windows:check
pnpm security:audit

Notes:

• pnpm check runs formatting checks, Clippy, TypeScript, unit tests, contract tests, integration tests, security tests, and profile/runtime validation.
• pnpm runtime:smoke starts the real DSH Web runtime and validates loopback, token exchange, CSP, Ready Gate, and branding plugin boot-graph integration.
• pnpm runtime:verify --target all validates macOS arm64 and Windows x64 runtime lock manifests.
• pnpm profile:verify validates DeepShell Bundle/Profile/Preset relationships against the official DSH baseline.
• pnpm package:e2e builds the E2E-only app package and captures its artifact manifest.
• pnpm package:mvp is platform-aware:
  • macOS: builds .app, signs, verifies, generates .dmg, captures release manifests, and requires the E2E/Release artifact comparison to pass;
  • Windows: builds an NSIS installer in a Windows build environment, captures the release NSIS manifest, and runs static security-boundary checks.
• pnpm package:verified rebuilds E2E and Release artifacts and compares their security boundaries on the macOS release route.
• pnpm licenses:collect, pnpm sbom:generate, pnpm package:report, and pnpm release:stage prepare local release-support assets without publishing anything.
• pnpm diagnostics:collect exports a local redacted diagnostics bundle under ignored staging.
• pnpm release:windows:check reports the Windows x64 packaging route and must not be treated as Windows installer acceptance when run on macOS.
• pnpm security:audit creates a vulnerability-audit summary; use pnpm security:audit -- --dry-run for deterministic pipeline checks.