DeepSeek Harness npm or Source Build? 2026 Guide

Testing the Web UI or a basic Agent workflow? Use the npm path.

Changing core packages, debugging plugin boundaries, or maintaining a development branch? Use a source checkout. For remote teams, keep npm for stable workloads and source builds in a separate research environment.

Who this decision guide is for

This guide is for people who want to launch DeepSeek Harness quickly, plugin authors who need to decide how much of the repository to maintain, and platform teams delivering a repeatable remote Mac environment.

We focus on software delivery responsibility, not on Web, headless, or ACP mode selection. The question is whether the runtime should come from a published package or a checked-out workspace.

Last updated August 18, 2026. Version and workflow details were verified against the official README, development guide, repository package.json, architecture documentation, and user guide.

What the npm path actually removes

The official README provides an npm launch path based on Node.js and the npx @deepseek-ai/dsh web command. It starts the Web UI at http://127.0.0.1:3080 by default. The same README provides a source path that clones the repository, installs dependencies with pnpm, builds the project, and then starts the Web UI. (official npm and source setup instructions)

The npm route removes several categories of work:

• You do not need to understand the repository workspace before the first launch.
• You do not need to install the full development dependency graph.
• You do not need to run TypeScript checks or build both library aggregates.
• You can test the runtime from a clean working directory.
• You can record the package version and reproduce that package later.

That makes npm the correct first move for a trial. The success criterion should be narrow: the Web UI starts, a model can be configured, a workspace can be selected, and one basic task produces a repeatable result.

The official user guide adds an important boundary that is easy to miss. The process uses its invoking directory as the default filesystem location, but a new Web UI has no selected workspace until you add one. The model configuration is also completed through Settings rather than assumed from the launch command. (official DeepSeek Harness user guide)

This means a successful process start is not the same as a successful Harness deployment. Your validation record should include:

1. The directory from which dsh was started.
2. The model configuration method.
3. The selected workspace path.
4. The exact task prompt used for acceptance.
5. The resulting files or response that prove the task completed.

For a remote Mac, these details matter more than a short installation command. A package that starts in the wrong directory can appear healthy while the Agent cannot access the intended project.

Plugin users should separate installation from development

Installing a plugin does not automatically justify running DeepSeek Harness from source.

The official architecture documentation describes a plugin-oriented system in which the model adapter, tool registry, session log, and Agent loop are all replaceable through plugin composition. Profiles can contain bundles and out-of-tree plugins, and the running tree can be inspected with dsh --profile web --dump-config. (official plugin architecture documentation)

For an existing plugin, start with the published npm runtime if the plugin documentation supports it. This gives you a cleaner answer to the first troubleshooting question: is the plugin incompatible with the runtime, or is the local source workspace incomplete?

Use this sequence:

1. Launch the known package version without the plugin.
2. Run the baseline task.
3. Add the plugin.
4. Run the same task and one plugin-specific task.
5. Dump or record the active profile configuration.
6. Remove the plugin and confirm that the baseline still works.

That final removal test is important. A broken plugin should not leave the only usable environment in an unknown state.

Choose source only when the plugin investigation requires one of these actions:

• Debugging an interface change between the plugin and Harness.
• Inspecting Host-side or Client-side type behavior.
• Testing a plugin against an unreleased repository change.
• Modifying an official package.
• Reproducing a bug that cannot be isolated through the published runtime.

For an external plugin, an independent repository is usually the lower-maintenance boundary. You can publish and test the plugin without carrying the entire monorepo, provided the public extension interface is sufficient for the feature.

Remote teams should lock the runtime by evidence, not by guesswork

There is no universally correct answer to “which npm version should a remote Mac use?” The correct version is the exact published package version that passed your acceptance task on the target environment.

For each remote deployment, preserve these fields:

• Node.js version and architecture.
• npm version and the command used to launch.
• Exact DeepSeek Harness package version.
• Working directory.
• Profile or configuration source.
• Plugin names and versions.
• Environment variable names, without exposing secret values.
• Workspace path.
• Acceptance prompt.
• Resulting artifact or response.
• Rollback command or previous package version.

Do not use an unqualified “latest” command for a production-like task. It makes future reconstruction depend on whatever the registry serves later. The package metadata and package manager rules are the evidence; the word “latest” is not.

The current source repository identifies a Node.js floor and a pinned pnpm release, but those details apply to the repository state inspected on August 18, 2026. The official README also labels the project a developer preview with expected compatibility-breaking changes. That combination argues for explicit version records and scheduled revalidation, not automatic upgrades. (official DeepSeek Harness README and release guidance)

For remote Mac planning, our recommended policy is:

• Stable task host: exact npm package version, fixed Node.js runtime, documented launch directory.
• Research host: separate source checkout, pinned commit, isolated credentials and workspace.
• Promotion gate: baseline task, plugin task, restart test, and rollback test all pass.
• Upgrade window: create a new environment or snapshot before changing the stable host.

This is also where a remote DeepSeek Harness deployment guide can complement the software decision. The software path and the remote machine lifecycle should be documented separately, then joined by the acceptance record.

How to recover when a source build fails

A failed source build should not force a production rollback through improvisation.

Use this recovery order:

1. Stop the failed development process.
2. Preserve the error output, Node.js version, pnpm version, commit, and lockfile state.
3. Do not delete the known-good stable environment.
4. Re-run the baseline task from the last tested npm package or source commit.
5. Create a fresh source checkout instead of repeatedly modifying a contaminated directory.
6. Run pnpm install from the repository root.
7. Run pnpm run typecheck before attempting a full task.
8. Run the official build command and then start the local CLI.
9. Compare the baseline result with the stable environment.
10. Promote only after the plugin and rollback tests pass.

The development guide notes that installation also configures worktree-local hooks and a Git merge driver. If those integrations are missing because installation was restored from cache or postinstall was skipped, the guide provides a manual installation command. That is a source-workspace responsibility that does not belong in the stable npm host. (official source recovery and setup guidance)

If the repository is still changing rapidly, the safest fallback is usually not “fix the source build at all costs.” It is to return to the last package version or commit that passed the baseline task, then investigate the source failure in isolation.

Final choice by maintenance condition

Choose npm when all of these are true:

• You are validating the Web UI or a basic Agent workflow.
• You are installing an existing plugin without changing Harness internals.
• You need a short-lived or easily rebuilt environment.
• You can record the package version and Node.js runtime.
• The baseline task is more important than repository-level debugging.

Choose source when any of these are true:

• You need to modify an official package.
• You are debugging Host and Client boundaries.
• You need to test an unreleased change.
• You must inspect build output or internal type behavior.
• You are preparing a contribution or maintaining a long-lived fork.

Choose dual-track when these conditions apply:

• Stable remote tasks must continue while development remains active.
• Plugins or core changes require repeated regression testing.
• More than one person needs to reproduce the environment.
• Upgrade and rollback evidence matters as much as initial setup.
• The team can maintain separate credentials, workspaces, and ownership rules.

The current npm route is easier to start, but it still needs a version record. The source route is more customizable, but it still needs a clean build and acceptance proof. The strongest operational choice is not the one with fewer commands. It is the one that makes the next rebuild and rollback predictable.

If your current setup mixes a moving source checkout with production tasks, depends on an unpinned npm command, or stores important sessions and workspaces on one experimental Mac, it has three real weaknesses: version drift, unclear recovery ownership, and a larger blast radius when a plugin or build fails. A separate VNCMac environment lets you place the stable npm runtime and the source research workspace on distinct remote Macs, keep the working directory consistent, and test upgrades without taking the only usable instance offline. Start with the remote environment acceptance criteria, then decide whether temporary cloud access is enough or whether your team needs a persistent Mac for repeatable DeepSeek Harness delivery.