How to Install DeepSeek Harness Plugins

DeepSeek Harness installs plugins into a named profile. The profile boundary matters: installing into web changes the Web composition, while another profile keeps its own dependencies and patch layers.

This tutorial follows the current official CLI reference for the developer preview. Always compare it with the plugin repository and the documentation for the exact Harness revision you run.

Need a candidate first? Browse the DeepSeek Harness plugin directory. Need the concepts? Read the DeepSeek Harness guide.

Before you install a plugin

You need:

Node.js, for running the official @deepseek-ai/dsh package.
pnpm on your PATH; the Harness plugin command forwards package operations to pnpm inside the selected profile.
A profile name. Use web for the shipped Web UI, headless for one-shot terminal tasks, or a separate custom profile for isolated testing.
A reviewed package name or Git specification from the plugin's authoritative repository.

Start the official Web UI once to confirm the base installation works:

npx @deepseek-ai/dsh web

The examples below use dsh as the CLI name shown in the official reference. If it is not installed on your PATH, run the same arguments through npx @deepseek-ai/dsh.

Step 1: inspect the plugin repository

Before copying an install command, confirm:

The source record points to the expected owner and repository.
The README names the supported Harness version or revision.
The package manifest identifies the package you will install.
Install and prepare scripts are understandable and necessary.
Requested credentials, filesystem access, commands, and network destinations match the capability you want.
The repository explains how to configure and remove the plugin.

A public or recently updated repository is not automatically safe. Star counts and directory labels are discovery signals only.

Step 2: choose the target profile

Use an existing profile when the capability clearly belongs there. For example, a Web client extension normally targets web:

dsh --profile web --dump-default-config

Use a separate profile when evaluating an unfamiliar plugin. Missing shipped profiles initialize from their templates; another new profile starts from the base bundle when the plugin command initializes it.

dsh plugin --profile plugin-test add github:owner/repository

Isolation reduces configuration overlap, but it does not make untrusted code safe. Plugin installation and runtime can still execute code with the permissions available to the process.

Step 3: install the DeepSeek Harness plugin

For a GitHub repository advertised by the maintainer:

dsh plugin --profile web add github:owner/repository

For a published package:

dsh plugin --profile web add package-name

Without a globally available dsh binary, the equivalent npm-run command is:

npx @deepseek-ai/dsh plugin --profile web add github:owner/repository

Do not invent the package name from the repository name. Use the exact package or Git specification documented by the maintainer.

After a successful package operation, Harness reconciles the profile's bundle list. A dependency whose manifest declares a dsh.bundle patch joins the bundle stack. A dependency without that declaration remains installed as a plain dependency and produces a warning; it may require a documented manual patch before it affects the profile.

Step 4: handle pnpm `allowBuilds` safely

Some Git-hosted plugins build source code during installation through a prepare script. pnpm 10 and later may block that build on the first attempt and print an allowBuilds hint.

Treat that failure as a review checkpoint:

Read the package's prepare script and the code it invokes.
Confirm the blocked package key belongs to the repository you intended to install.
Add only the reviewed key to the profile's pnpm-workspace.yaml as directed by the CLI output.
Run the same add command again.

Do not broadly allow every build script just to make installation pass. A prebuilt tarball or a local checkout may not require this allowance, but it still needs review.

Step 5: verify the installation

Ask pnpm why the selected profile contains the package:

dsh plugin --profile web why package-name

Then inspect the fully composed profile without booting it:

dsh --profile web --dump-config

Confirm the expected bundle or configuration rows are present and that unrelated providers, permissions, or network services did not change. Then start the profile:

dsh --profile web

Exercise the smallest intended workflow first. Watch the terminal and browser console for boot failures, missing services, permission prompts, or unexpected outbound access.

Update or remove a plugin

Update only after reviewing release notes and compatibility changes:

dsh plugin --profile web update package-name

Remove the dependency from the same profile:

dsh plugin --profile web remove package-name

After either operation, run --dump-config again. Harness reconciles bundle membership after successful package operations, but user-created patch rows or plugin-owned data may need separate cleanup according to the repository's instructions.

Troubleshooting DeepSeek Harness plugin installation

`pnpm` is not found

Install pnpm and make sure the pnpm executable is available on PATH. The plugin subcommand uses pnpm inside the profile directory even when you launch Harness through npm.

The first add fails with an `allowBuilds` message

This is pnpm protecting source-build execution. Review the named package and its scripts, add only the approved key where the CLI directs, and rerun the same command.

The package installs but nothing changes

Check the install output and package manifest. If the dependency does not declare a dsh.bundle patch, Harness keeps it as a plain dependency instead of automatically adding configuration. Follow the maintainer's version-matched patch instructions.

The profile fails to boot

Use dsh --profile web --dump-config to inspect the composed rows, then compare the plugin's compatibility statement with your Harness revision. Remove the plugin from the affected profile if you cannot establish a safe, supported configuration.

The wrong profile changed

Every management command should include the intended --profile <name>. Run why and --dump-config against both the expected and accidental profile, then remove the package from the wrong one.

Installation safety checklist

Verify owner, repository, package name, and current revision.
Read install, prepare, postinstall, and runtime scripts.
Review dependencies and lockfile changes.
Check requested filesystem, command, credential, browser, and network access.
Use a test profile and least privilege.
Pin a reviewed version or commit when reproducibility matters.
Inspect the composed configuration before boot.
Keep the exact removal command and any data-cleanup steps.