DeepSeek Harness Lite

Keep the official Harness core. Make installation, capability trimming, customization, and plugin extension lighter.

Unofficial community project. This repository is independently maintained and is not affiliated with, sponsored by, or endorsed by DeepSeek. The project image is a community-provided asset, not an official project endorsement.

简体中文 | Architecture | Plugin authoring | Security

Positioning: DeepSeek Harness Lite is an unofficial lightweight distribution and extension layer built on the official Harness runtime, not a reimplementation. It preserves the official agent loop, session model, tool registry, and LLM interfaces while using smaller verified profiles, removable capability packs, and a focused plugin path to make installation, capability trimming, downstream customization, and plugin integration easier.

Plugin compatibility is best-effort and release-gated. Plugins built on public Harness/Cordis interfaces can be integrated when they fit Lite's supported host-service and security boundaries, but compatibility with every official or third-party plugin is not promised.

What you are running

Lite is for users who want a small, inspectable Harness runtime in a terminal or script. It is not currently a graphical chat client.

Quick start

Download the package for your system from the latest GitHub Release. Packaged builds include Node.js and Corepack; you do not need Git, Node.js, or pnpm. The first init downloads and validates the exact platform-specific Harness closure, so it needs network access and may take a few minutes. PowerShell 7 (pwsh) is needed on Windows only when the shell pack is enabled.

Windows x64

Use the .exe installer, open DeepSeek Harness Lite Terminal from the Start menu, and run:

dsh-lite init --config "$env:LOCALAPPDATA\Programs\DeepSeek Harness Lite\examples\chat-only\lite.config.json" --home "$HOME\.dsh-lite-home"
dsh-lite doctor --home "$HOME\.dsh-lite-home"

For the portable ZIP, extract it, open PowerShell in the extracted folder, and use ./dsh-lite.cmd instead of dsh-lite:

.\dsh-lite.cmd init --config .\examples\chat-only\lite.config.json --home "$HOME\.dsh-lite-home"
.\dsh-lite.cmd doctor --home "$HOME\.dsh-lite-home"

macOS or Linux

Download the archive matching your CPU (x64 for Intel/AMD, arm64 for Apple Silicon), extract it, and enter the extracted directory:

tar -xzf deepseek-harness-lite-v0.1.1-<platform>-<arch>.tar.gz
cd deepseek-harness-lite-v0.1.1-<platform>-<arch>
./dsh-lite init --config examples/chat-only/lite.config.json --home "$HOME/.dsh-lite-home"
./dsh-lite doctor --home "$HOME/.dsh-lite-home"

The macOS .dmg contains the same CLI directory as the .tar.gz; copy its contents to a writable folder before running ./dsh-lite. Because the community builds are unsigned, Windows SmartScreen or macOS Gatekeeper may show a warning. Verify the download against SHA256SUMS.txt; see Installation format for the exact security and signing status.

init should print initialized .... doctor should return JSON with "status": "ok" and every check set to pass. Neither command needs a model key.

Commands below use dsh-lite for the installed Windows build. For a portable Windows ZIP, use .\dsh-lite.cmd; for macOS/Linux, use ./dsh-lite. Source-checkout users use node apps/cli/dist/src/bin.js.

Example terminal output from the verified flow; paths are shortened and no real credential is shown.

Run the first model task

Set credentials only in the current terminal process. This example uses the official API URL and its common chat model; for another OpenAI-compatible endpoint, use a model name that endpoint actually supports.

Windows PowerShell:

$env:DEEPSEEK_BASE_URL = "https://api.deepseek.com/v1"
$env:DEEPSEEK_API_KEY = "<your-key>"
$env:DEEPSEEK_MODEL = "deepseek-chat"
dsh-lite run "Reply with exactly: ready" --home "$HOME\.dsh-lite-home"

macOS/Linux:

export DEEPSEEK_BASE_URL='https://api.deepseek.com/v1'
export DEEPSEEK_API_KEY='<your-key>'
export DEEPSEEK_MODEL='deepseek-chat'
./dsh-lite run 'Reply with exactly: ready' --home "$HOME/.dsh-lite-home"

The expected stdout is the model answer, for example ready. DEEPSEEK_BASE_URL may be an API root ending in /v1 or the full /chat/completions URL. The code default for DEEPSEEK_MODEL is deepseek-v4-flash; set the variable explicitly when your endpoint uses a different model name. Never put credentials in lite.config.json, generated profiles, fixtures, logs, or commits.

How to use it

1. Run init once for a chosen config and Lite home. It resolves, installs, activates, and validates a complete profile before publishing it.
2. Run doctor after installation or an update. Continue only when all checks pass.
3. Run inspect when you want the exact upstream version, packages, Cordis rows, packs, and plugins in the active profile.
4. Export endpoint credentials in the current terminal.
5. Run one quoted task. The CLI prints the final text and exits; invoke it again for another task.

Command reference

Paths are resolved from the current working directory. --home stores generated runtime state; do not edit files inside it by hand. To change capabilities, edit or select a config and rerun init against the same home. Publication switches the active profile only after the replacement passes validation.

Use the developer profile

The included developer profile enables bounded workspace notes, sanitized session export, and the health plugin:

dsh-lite init --config examples/developer/lite.config.json --home .dsh-lite-home
dsh-lite doctor --home .dsh-lite-home
dsh-lite inspect --home .dsh-lite-home

For a custom selection, create a config like this and run init with its path:

{
  "schemaVersion": 1,
  "upstream": { "channel": "stable", "version": "0.1.0-rc.6" },
  "profile": "custom",
  "packs": ["workspace", "research"],
  "plugins": ["health"]
}

Pack-contributed plugins are added automatically. Do not also list the same plugin in plugins; duplicate activation is rejected. Review the capability table below before enabling shell or network access.

Run against another project directory

The current directory becomes the workspace seen by workspace-aware Lite plugins. Keep the CLI and generated home in the cloned Lite repository, then call them with absolute paths from your project:

Windows PowerShell:

$LiteRepo = "C:\src\deepseek-harness-lite"
Set-Location "C:\src\my-project"
node "$LiteRepo\apps\cli\dist\src\bin.js" run "Summarize this project" --home "$LiteRepo\.dsh-lite-home"

macOS/Linux:

LITE_REPO="$HOME/src/deepseek-harness-lite"
cd "$HOME/src/my-project"
node "$LITE_REPO/apps/cli/dist/src/bin.js" run 'Summarize this project' --home "$LITE_REPO/.dsh-lite-home"

Common problems

Installation format

Starting with v0.1.1, Release assets are produced and smoke-tested on their native platform:

CI rejects absolute, checkout-bound, escaping, or broken links, moves the deployment away from the checkout, and runs init, doctor, and inspect through the packaged launcher before publishing it. The artifacts include both READMEs, examples, the project image, MIT license, NOTICE, and checksums. They are CLI distributions, not GUI apps or single-file binaries.

The current community builds are not code-signed. The Windows installer may trigger SmartScreen. The macOS images are not notarized and may require the user to approve the download in Privacy & Security. Do not bypass a warning before checking the SHA-256 checksum and confirming that the file came from this repository's Release page.

Build from source

Contributors and unsupported architectures can still build from source. This path requires Git, Node.js ^22.19.0 or >=24, and Corepack:

git clone https://github.com/sakurarain1213/deepseek-harness-lite.git
cd deepseek-harness-lite
corepack pnpm@10.15.0 install --frozen-lockfile
corepack pnpm@10.15.0 build
node apps/cli/dist/src/bin.js init --config examples/chat-only/lite.config.json --home .dsh-lite-home
node apps/cli/dist/src/bin.js doctor --home .dsh-lite-home

What Lite changes

Profiles and capability packs

Packs are declarative and removable. Changing the selection regenerates the exact dependency closure, lock, and Cordis rows. Disabled capability packages are physically absent from the generated profile.

The v0.1.0 workspace pack intentionally excludes upstream generic filesystem and search tools. The research pack intentionally excludes upstream generic web_fetch. Those broader surfaces remain off until their containment and SSRF boundaries pass the release gate.

Bundled plugins

Repository plugins install with the source checkout for static, reviewable imports. Installation does not activate them. A resolved profile mounts only direct selections and contributions from selected packs.

The plugin roadmap favors capabilities with a clear user workflow, public upstream interfaces, narrow authority, deterministic tests, and native Windows/macOS/Linux evidence. The project aims to add more useful plugins over time, but a plugin is bundled or recommended only after its install, build, activation, license, secret, and security-boundary checks pass. External plugins can enter the evidence-based catalog before they are candidates for bundling.

Plugin catalog

Catalog status is derived from evidence, not from repository topics, popularity, or metadata alone.

External submissions must pin a full source commit, declare an SPDX license and Harness compatibility, include install/build/activation evidence, and disclose risk flags. See Plugin authoring and the generated catalog.

Architecture

lite.config.json
       |
       v
CLI -> resolver -> exact closure + Cordis rows -> immutable profile publication
                    ^                         |
                    |                         v
             capability packs       official Harness runtime
                                              |
                                              v
                                  official tool registry + Lite plugins

Lite owns configuration, closure generation, publication, plugins, and evidence. Official packages own the agent loop, sessions, model integration, and tool registry. Read Architecture for trust boundaries and the publication protocol.

Upstream compatibility

The stable channel pins the complete upstream 0.1.0-rc.6 package inventory in compat/upstream-lock.json. Generated closures and locks cover every pack combination on Windows, macOS, and Linux.

The v0.1.0 release evidence and all five bundled plugin records are bound to Lite source commit 573e77a16e58d9832f6dca282cac00f1dbde2cea. The later evidence commit records generated results without changing that verified source.

Compatibility is best-effort and release-gated, not permanent:

• stable uses the exact upstream release that passed the recorded gates;
• the latest-upstream workflow only detects new registry metadata;
• an upstream update requires regenerated closures and locks plus the complete release gates;
• Lite config and pack schemas remain stable where practical;
• incompatible upstream changes are handled through migration notes and versioned releases.

The maintenance target is to evaluate each coherent official Harness release promptly and publish a matching Lite patch or minor release after regenerated closures, plugins, runtime behavior, and the complete native CI matrix pass. If an upstream version fails, Lite keeps the last verified stable set and documents the blocker instead of claiming untested compatibility. This is an active best-effort synchronization policy, not a same-day compatibility guarantee.

See Upstream maintenance.

Windows support

Windows is a supported v0.1.0 platform. The native path uses PowerShell rows, Windows package closures, PATHEXT-aware probes, and final-path profile construction so pnpm absolute junctions remain valid. current.json changes only after the candidate passes validation.

The release gate includes a native regression named keeps a native Windows absolute junction valid after publication. Windows is part of the same release-blocking CI matrix as Ubuntu and macOS; it is not configured with continue-on-error. Local validation also covers init, doctor, inspect, a real OpenAI-compatible API turn, profile cleanup, secret scanning, and all five plugins.

See Windows support for the exact gates and platform requirements.

Install-size evidence

The committed clean measurement was recorded on Windows x64 with Node.js 24.12.0 and pnpm 10.15.0. It is one-platform evidence, not a universal size promise.

compat/reports/install-size.json is the source of truth. Run corepack pnpm@10.15.0 measure:install again whenever the dependency graph or measurement method changes.

Security and maintenance

• Credentials stay in process environment variables; diagnostics redact secret-like fields.
• Generated profiles use exact dependencies, committed lock hashes, and profile-local resolution checks.
• Optional packs expand authority and must be selected explicitly.
• Network, filesystem, process, and session plugins enforce separate narrow boundaries.
• A valid Lite configuration is not a sandbox. Review enabled packs and plugins before running untrusted tasks.

Report vulnerabilities through GitHub private vulnerability reporting as described in SECURITY.md. Do not include real keys or private logs.

Contributing and license

See CONTRIBUTING.md for code, pack, documentation, and catalog changes. Original Lite code is available under the MIT License. Upstream and third-party packages retain their own copyrights and licenses; see NOTICE.md.

"DeepSeek" and "DeepSeek Harness" identify the upstream project. Their use here does not imply affiliation, sponsorship, or endorsement.