DeepSeek Harness Setup: Install dsh, Plugins, MCP & Fixes

DeepSeek Harness is official DeepSeek AI software for building and running coding agents—not a model and not an Atoms integration.

This guide is organized around the real setup questions developers search for: how to install dsh, launch the Web UI, choose a port, understand profiles, add plugins, connect MCP safely, and recover from the errors most likely to block a first run.

Check the verified setup

Verified locally on August 28, 2026: macOS 26.5.2 on Apple Silicon arm64, Node.js v22.23.1, npm 10.9.8, pnpm 11.7.0. The repository build completed successfully, and a source-launched Web UI returned HTTP 200 at http://127.0.0.1:3080.

Linux and Windows are Not tested in this guide. Remote inference, API-key authentication, MCP server connectivity, and third-party plugin behavior are also Not tested unless explicitly marked below.

What DeepSeek Harness Is—and Which Project Is Official

DeepSeek Harness (dsh) is an open-source agent harness developed by DeepSeek AI. The official repository is:

• GitHub: deepseek-ai/deepseek-harness
• Official site: DeepSeek Harness developer preview

The repository describes a plugin-based architecture powered by Cordis. Its public preview says that models, tools, skills, sessions, sandboxes, storage, loops, scheduling, and the UI can be swapped or recomposed as plugins.

Do not confuse these layers:

• Harness: runtime that connects an agent to context, tools, files, sessions, policies, and environments.
• Model: the inference provider selected by the runtime. DeepSeek Harness is not itself a model.
• Plugin: an installable or composed capability in the Cordis runtime.
• MCP client: the Harness-side connector that speaks the Model Context Protocol.
• MCP server: an external process or service that exposes tools or resources.
• Profile: a runtime composition/configuration boundary. Installing a plugin and enabling it in the active profile are separate operations.

DeepSeek Harness is currently a developer preview. Compatibility-breaking changes are expected. Pin versions for repeatable setups and re-run the checks after upgrades.

DeepSeek Harness 60-Second Quickstart

Official npm path

The official repository README currently documents:

npx @deepseek-ai/dsh web

Status: Not tested in this environment. An attempted npx @deepseek-ai/[email protected] web invocation did not produce startup output during the local time window and was stopped. Do not treat the npm path as locally verified here.

Verified source path

The source checkout was verified with the following environment:

OS: macOS 26.5.2
Architecture: arm64
Node.js: v22.23.1
npm: 10.9.8
pnpm: 11.7.0
Repository: deepseek-ai/deepseek-harness checkout

The repository package declares this engine range:

Node.js ^22.19.0 or >=24.0.0

The verified source quickstart was:

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

Verified output:

dsh web: http://127.0.0.1:3080

A separate HTTP check returned:

HTTP 200
Content-Type: text/html; charset=utf-8

The build completed successfully with the repository’s pnpm run build command. The install emitted platform warnings for Linux-only native packages on macOS and warnings about demo-package bins that were not built yet; these did not prevent the build or Web UI from starting.

What this quickstart proves

It proves that the checked source tree can build and launch the local Web UI on the verified macOS environment. It does not prove:

• that every npm release installs identically;
• that a configured model provider is reachable;
• that API authentication works;
• that plugins from third parties are safe;
• that Linux or Windows behavior matches macOS;
• that a production deployment is ready.

OS, Node.js, npm, and Port Requirements

Check the runtime before installing:

node -v
npm -v
pnpm -v

Verified output in the checked environment:

v22.23.1
10.9.8
11.7.0

The default Web UI address is:

http://127.0.0.1:3080

If port 3080 is occupied, first identify the process and consult the version-matched CLI help or repository documentation for the supported port override. The exact alternative-port flag was Not tested here; do not assume a flag name from another release.

Complete the First-Run Setup

Launching the Web UI is only the first step. A first-run checklist should include:

1. Open the local URL and confirm the interface loads.
2. Select or configure the intended model provider.
3. Keep API keys in the supported credential mechanism, not in prompts or committed files.
4. Choose a workspace with only the repository files the agent needs.
5. Start with the most restrictive permission preset that can complete the task.
6. Test a read-only task before allowing edits or shell execution.
7. Confirm the active profile and enabled plugins.
8. Record the exact package/repository version.
9. Run a small task and inspect the trajectory, tool calls, results, and errors.
10. Only then expand network, filesystem, or MCP access.

The local UI does not imply local inference. The browser and runtime can run on your machine while model calls go to a remote provider. The configured provider, retention policy, and billing terms must be checked separately.

dsh Web, CLI, TUI, and Profiles

Web UI

The web command starts the browser-facing interface:

pnpm dsh web

or, using the official package path:

npx @deepseek-ai/dsh web

CLI and source development

The source repository exposes the dsh command through its workspace scripts. The source build and source-launched Web UI were verified on macOS. Other CLI commands and headless modes were Not tested in this run.

TUI terminology caution

Do not assume that a “TUI” means the same interface in every release. Read the version-matched documentation and help output before writing automation around terminal prompts, environment variables, or profile files.

Profiles

A profile determines which capabilities are composed into a runtime. A plugin can be present in a repository or package store without being enabled in the profile currently running.

When diagnosing a missing tool:

Package available
→ Plugin resolved
→ Plugin enabled in active profile
→ Service registered
→ Tool exposed to the agent
→ Permission allows the call

Failure at any layer can look like “the plugin does not work.” Check the layers separately.

Install and Enable Plugins

DeepSeek Harness’s distinctive claim is that capabilities are plugins. The official public materials describe pluginized models, tools, skills, sessions, sandboxes, storage, loops, scheduling, and UI.

Installation and activation are not synonyms:

A safe plugin workflow is:

1. Read the plugin repository and license.
2. Check its maintenance history and declared dependencies.
3. Inspect what files, network endpoints, subprocesses, and credentials it requests.
4. Install it in a disposable test workspace.
5. Enable it in a non-production profile.
6. Restart dsh after changing profile composition.
7. Run a read-only verification task.
8. Review logs and tool traces.
9. Promote it only after the requested permissions are understood.

The public repository recommends the dsh-plugin topic for plugin discoverability. That topic is a discovery mechanism, not a security certification.

Connect MCP Servers Safely

MCP adds another boundary to the runtime.

DeepSeek Harness
  └── MCP client
        └── MCP server
              └── external tools / resources

The client and server have different responsibilities:

• MCP client: runs within or alongside the Harness and initiates protocol communication.
• MCP server: exposes tools or resources and may have its own filesystem, network, credentials, and subprocess access.
• Configuration: defines how the client starts or reaches the server and which environment is passed to it.
• Permission: determines whether the agent may invoke the exposed capability.

Do not treat “MCP connected” as “safe.” Before enabling a server, document:

• executable or endpoint;
• version and source repository;
• required environment variables;
• files it can read or write;
• network destinations;
• credentials it can access;
• tools and resources it exposes;
• destructive operations;
• timeout and failure behavior;
• human approval requirements.

The exact MCP configuration syntax for the current DeepSeek Harness release was Not tested in this environment. Use the official version-matched documentation rather than copying a configuration from an older preview.

A minimal principle is:

No broad home-directory access
No unrestricted network by default
No production credentials in a test profile
No destructive tool without explicit approval

DeepSeek Harness Troubleshooting

The following table separates the observed symptom, likely cause, repair, and verification status.

npx @deepseek-ai/dsh web does not start

Likely causes: unsupported Node.js engine, registry/network failure, package resolution delay, or a release-specific startup error.

Repair: run node -v, confirm the repository engine range, retry with the exact version recommended by the official release documentation, and inspect the complete npm error. If npm remains blocked, clone the official repository and use the source path.

Verified environment: source path verified on macOS 26.5.2, arm64, Node.js 22.23.1. npm path Not tested.

Unsupported engine or syntax error during install

Likely cause: Node.js is older than ^22.19.0 and does not satisfy the package engine requirement.

Repair: upgrade Node.js with the team’s approved version manager, open a fresh shell, and confirm node -v before reinstalling.

Verified: the checked repository declares ^22.19.0 || >=24.0.0. Upgrade path itself Not tested.

Port 3080 is already in use

Likely cause: another dsh process or unrelated local service owns the default port.

Repair: inspect the process using the port, stop only the process you own, or use the alternative port mechanism documented by the exact installed release.

Verified: default port 3080 launched successfully. Alternative-port override Not tested.

The browser opens but the model does not answer

Likely causes: missing provider credential, incorrect base URL, unavailable provider, rate limit, unsupported model, or remote inference policy.

Repair: verify the configured provider separately from the local Web UI. Check the provider’s current model ID, credential scope, base URL, billing, and error response. Do not place keys in the repository or prompt.

Status: Not tested; no model credential was used for this setup verification.

A plugin is installed but its tool is missing

Likely causes: plugin is not enabled in the active profile, dependencies are unresolved, the runtime was not restarted, or permissions hide the tool.

Repair: verify package resolution, profile composition, restart dsh, inspect the plugin inventory, and run a least-privilege read-only test.

Status: plugin activation and third-party plugin behavior Not tested.

MCP server starts but tool calls fail

Likely causes: client/server protocol mismatch, wrong executable path, missing environment variable, unavailable dependency, blocked network, or insufficient permission.

Repair: run the server independently in a disposable profile, inspect stderr, verify the configured command and environment, expose one harmless read-only tool first, and confirm the active profile after restart.

Status: MCP setup Not tested in this environment.

Changes to the profile do not appear in the UI

Likely cause: the running process is using a different profile or has not been restarted.

Repair: record the active profile path, stop the old process, restart dsh, and verify the enabled plugin list from the new session.

Status: profile switching Not tested.

Source build fails on macOS because of a native package

Likely cause: a package targets Linux or Windows while the host is macOS, or a native dependency requires a platform-specific build tool.

Repair: read the package’s platform constraints, build only the supported target, and do not interpret a platform warning as a generic Harness failure.

Verified: pnpm install emitted Linux-only native-package warnings on macOS, but pnpm run build completed and pnpm dsh web served the UI.

Least-Privilege and Container Setup

DeepSeek Harness can connect an agent to powerful tools. Start with the smallest execution surface.

Least-privilege checklist

• [ ] Run from a dedicated repository workspace.
• [ ] Do not run from a home directory containing unrelated projects.
• [ ] Keep production credentials out of development profiles.
• [ ] Use environment variables or the supported credential reference mechanism.
• [ ] Start with read-only filesystem access where possible.
• [ ] Restrict writable paths to the target workspace.
• [ ] Deny unrestricted network access by default.
• [ ] Require approval for package installation, deployment, deletion, and credential use.
• [ ] Expose only the MCP tools the task needs.
• [ ] Review plugin source, dependencies, and requested permissions.
• [ ] Record tool calls, command results, approvals, and failures.
• [ ] Keep a disposable profile for experimentation.
• [ ] Test rollback or workspace recovery before consequential changes.

Container checklist

Containers can reduce blast radius, but they are not automatically secure. Define:

• image digest and provenance;
• non-root user;
• read-only root filesystem where possible;
• explicit writable mount;
• restricted network;
• dropped Linux capabilities;
• resource limits;
• no host socket unless unavoidable;
• no broad credential mounts;
• log retention and cleanup;
• a clear boundary between test and production data.

The official repository includes sandbox and filesystem capability packages, but this guide does not claim that a particular container or sandbox configuration has been validated for every OS or deployment model.

Developer Preview Limitations

DeepSeek Harness is a developer preview, not a stable compatibility contract.

Expect potential changes to:

• package names;
• CLI flags;
• profile schemas;
• plugin APIs;
• MCP configuration;
• session formats;
• model adapters;
• Web UI behavior;
• platform support;
• permission defaults.

The official data-processing statement describes DeepSeek Harness as local-first, with data processed and stored locally by default once installed and running, subject to the actual configuration and connected services. Local-first does not mean that remote model providers or MCP servers receive no data. Audit the complete path.

Do not describe Atoms as running DeepSeek Harness, an official DeepSeek integration, or a security replacement for DeepSeek Harness. Atoms is a separate AI product-development platform with its own multi-agent workflow. If the real goal is to build a website or web app rather than configure an agent runtime, use the product brief CTA below.

Last-Verified Changelog

Re-run the quickstart and update this table whenever the package, repository commit, Node version, or profile composition changes.

FAQ

Is DeepSeek Harness a model?

No. It is an agent harness and runtime. It connects model providers to tools, files, sessions, policies, and environments.

What is the official DeepSeek Harness install command?

The official repository documents:

npx @deepseek-ai/dsh web

In this guide, the source-build path was verified; the npm launch path was not successfully verified in the local test window.

What is dsh web?

It launches the local Web UI. The verified source run served http://127.0.0.1:3080.

Does the local Web UI mean local inference?

No. The UI can be local while the configured model provider is remote.

Are plugins the same as MCP servers?

No. A plugin is a Harness runtime capability. An MCP server is an external protocol participant. A Harness plugin may provide or manage an MCP client, but the boundaries should be documented separately.

Why must I restart after enabling a plugin?

Profile composition is normally resolved at runtime startup. Restarting reloads the active profile and makes the new capability observable.

Is DeepSeek Harness production-ready?

It is publicly described as a developer preview with expected compatibility-breaking changes. Evaluate it against your own security, reliability, audit, and operational requirements before production use.

Can Atoms run DeepSeek Harness?

This article makes no such claim. Atoms is a separate platform for building and deploying websites and applications with its own AI-agent workflow.

What if my actual goal is to build a website or web app?

Use the Atoms workflow instead of treating DeepSeek Harness configuration as the product itself. Define the user, pages, data, actions, and success criteria, then open the AI App Builder or AI Website Builder.

Sources

• DeepSeek Harness official developer preview
• DeepSeek Harness official GitHub repository
• DeepSeek Harness README
• DeepSeek Harness data-processing statement
• DeepSeek Harness safe-use policy
• Atoms AI Agents
• Atoms AI Website Builder
• Atoms AI App Builder
• Atoms AI Coding Agents
• Atoms Backend
• Atoms Cloud
• Production-Ready AI App Builder