DeepSeek Harness Installer

English | 简体中文

A small, cross-platform installer and local process manager for the official DeepSeek Harness.

This project clones the upstream source code, installs its locked dependencies, builds the Web UI, and adds a deepseek command for starting, stopping, updating, and removing the local installation.

[!IMPORTANT] This is an independent community project, not an official DeepSeek project. DeepSeek Harness is currently a developer preview and may introduce breaking changes. For Harness features, configuration, and product support, refer to the upstream repository.

Why this installer?

The upstream project can already be run with npx @deepseek-ai/dsh web. This repository is intended for users who prefer a source-based, persistent local installation with a single management command.

Features

• Supports macOS, Linux, and Windows.
• Clones and builds the official DeepSeek Harness repository from source.
• Uses the upstream lockfile through pnpm --frozen-lockfile.
• Provides start, stop, status, logs, update, and uninstall commands.
• Uses http://127.0.0.1:3080 by default and selects a free port if 3080 is unavailable.
• Refuses to overwrite or update a checkout with local changes.
• Validates managed processes and install paths before stopping or deleting them.
• Requires no administrator or root privileges with the default locations.

How it works

The installer:

1. validates the required tools and Node.js version;
2. clones or fast-forwards https://github.com/deepseek-ai/deepseek-harness.git;
3. installs the exact dependency graph recorded by the upstream lockfile;
4. builds DeepSeek Harness and its Web UI;
5. installs a deepseek launcher in a user-local directory.

It does not install a system daemon and does not start automatically at boot. deepseek start launches a background process for the current user.

Requirements

Requirement	macOS / Linux	Windows
Git	Required	Required
Node.js	22.19+ on the 22.x line, or 24+	Same
Corepack	Required and available as corepack	Same
curl	Required	Not required by this installer
PowerShell	Not required	Required
Internet access	Required for install and update	Same

Check the main tools before installing:

git --version
node --version
corepack --version

Installation

Download or clone this repository first. Keep each installer beside its companion launcher while running it:

install.sh  + deepseek       # macOS / Linux
install.bat + deepseek.ps1   # Windows

macOS and Linux

cd deepseek-harness-installer
chmod +x install.sh deepseek
./install.sh

Restart the terminal after installation so the updated PATH is loaded, then start Harness:

deepseek start

The default locations can be changed for the installation command:

DEEPSEEK_INSTALL_DIR="$HOME/apps/deepseek-harness" \
DEEPSEEK_BIN_DIR="$HOME/bin" \
./install.sh

If DEEPSEEK_BIN_DIR is not already on PATH, the installer adds one marked entry to .zprofile, .bashrc, or .profile, based on the current shell.

Windows

Run install.bat by double-clicking it or from Command Prompt:

cd deepseek-harness-installer
install.bat

Restart Command Prompt or PowerShell after installation so the updated user PATH is loaded, then run:

deepseek start

The Windows installer uses user-local paths under %LOCALAPPDATA% and invokes the launcher with a process-scoped PowerShell execution-policy bypass. It does not change the machine-wide PowerShell policy.

Command reference

Command	Description
deepseek start	Start the Web UI in the background and print its local URL.
deepseek stop	Stop the process tree managed by this installer.
deepseek status	Show the process ID and URL, or report that Harness is stopped.
deepseek logs	Follow the last 100 log lines. Press Ctrl+C to stop following logs; the service keeps running.
deepseek update	Fast-forward the upstream checkout, reinstall locked dependencies, rebuild, and restart if it was running.
deepseek uninstall	Stop Harness and remove installer-managed files after confirmation.

deepseek status returns a non-zero exit status when Harness is stopped, which makes it suitable for shell scripts and health checks.

Local URL and port selection

The preferred address is:

http://127.0.0.1:3080

If port 3080 is already in use, the launcher asks the operating system for a free port. Always use the URL printed by deepseek start or deepseek status. The server binds to the loopback interface and is not exposed directly to other machines.

Updating

deepseek update

The update operation uses git pull --ff-only; it does not reset or rewrite the checkout. An update is refused when local changes are present. If you intentionally modify the upstream checkout, commit or back up those changes and maintain the checkout manually.

Because DeepSeek Harness is in developer preview, review upstream changes before updating installations that matter to you.

Security and trust model

This is a source installer, not a prebuilt or sandboxed distribution. During installation and update it downloads the current upstream Git branch, resolves packages from the registries configured for Corepack/pnpm, and runs upstream dependency and build scripts as your current user.

• Review this repository's four scripts before running them.
• Review upstream changes before deepseek update; Harness commits are not pinned by this installer.
• The frozen lockfile makes dependency resolution reproducible for a given upstream commit, but it does not freeze the upstream commit itself.
• Do not run the installer as root or Administrator unless you have independently chosen custom locations that require it.
• The lifecycle commands only terminate a process that matches the recorded checkout, and uninstall applies additional path and repository-origin checks.

File locations

macOS and Linux

Purpose	Default path
Upstream checkout	~/.local/share/deepseek-harness
Command	~/.local/bin/deepseek
Install metadata	${XDG_CONFIG_HOME:-~/.config}/deepseek-harness
PID, URL, and log	${XDG_STATE_HOME:-~/.local/state}/deepseek-harness

Windows

Purpose	Default path
Upstream checkout	%LOCALAPPDATA%\DeepSeekHarness\repo
Commands	%LOCALAPPDATA%\DeepSeekHarness\bin
Install metadata, PID, URL, and log	%LOCALAPPDATA%\DeepSeekHarness

Uninstallation

The recommended cross-platform command is:

deepseek uninstall

You may also run the original installer from this repository:

./install.sh uninstall

install.bat uninstall

Confirmation is intentionally platform-specific:

• macOS / Linux: type UNINSTALL exactly;
• Windows: type y or yes.

The uninstaller removes only the expected installer-managed checkout and state. On macOS and Linux, the marked PATH line in the shell profile is preserved to avoid editing user configuration destructively; remove that line manually if the directory is no longer used. On Windows, the installer bin directory is removed from the user PATH.

Troubleshooting

deepseek: command not found

Restart the terminal. On macOS or Linux, also confirm that ~/.local/bin (or your custom DEEPSEEK_BIN_DIR) is on PATH. On Windows, confirm that %LOCALAPPDATA%\DeepSeekHarness\bin is in the user PATH.

Unsupported Node.js version

Install Node.js 22.19 or later on the 22.x line, or Node.js 24 or later. The accepted range mirrors the current upstream engine requirement.

Missing corepack

Install or enable Corepack for your Node.js distribution, then verify that corepack --version works in a new terminal. This installer deliberately uses the package-manager version declared by the upstream project.

Startup failed

Inspect the log:

deepseek logs

The launcher waits for the local HTTP endpoint before reporting a successful start. Dependency, configuration, or upstream runtime errors appear in this log.

Update refused because of local changes

Run git status in the upstream checkout shown in File locations. Commit, stash, or discard the changes yourself. The installer will never reset them automatically.

Scope and support

Please report installer, lifecycle-command, and cross-platform script problems in this repository. Report DeepSeek Harness behavior, plugins, models, or Web UI problems to the upstream Discussions.

DeepSeek and DeepSeek Harness names belong to their respective owners. Their use here describes compatibility and does not imply affiliation, endorsement, or sponsorship.

Contributing

Issues and pull requests are welcome. Keep changes focused on installation and local lifecycle management, preserve safety checks around process termination and deletion, and test the affected platform before submitting a change.

By contributing, you agree that your contribution is licensed under this project's MIT License.

License

This installer project is open source under the MIT License.

DeepSeek Harness is a separate project, also currently distributed under its own MIT License. The upstream project and dependencies retain their own copyright notices and license terms. This repository's license does not replace or modify them.