DeepSeek Harness Developer Preview: install it with a safe rollback boundary

Author: Ahab · Date: August 19, 2026

Quick answer

DeepSeek Harness, or dsh, is DeepSeek AI's open-source agent harness. The official repository describes an “everything is a plugin” architecture and provides a one-command Web UI:

npx @deepseek-ai/dsh web

Do not read that short command as a production-readiness claim. The project is explicitly in Developer Preview, and its README warns that compatibility-breaking changes will happen. At the source snapshot checked for this guide—default branch master, commit 99f6f02fecdb7dff40c3fbc9470f5907c29f74ca—the latest GitHub pre-release and npm version are both 0.1.0-rc.7.

The safest first evaluation is a disposable one: pin that exact version, give it an isolated DSH_HOME, launch it from a throwaway workspace, keep the default workspace-write + ask permission preset, add a test-only model credential, and run eight acceptance tests before pointing it at real code. Stop if any boundary is ambiguous.

Who this is for

This guide is for independent developers and agent-framework engineers who want to understand what DeepSeek Harness can do without giving a preview build broad authority over their normal home directory or primary repository.

It is not a production deployment guide. If you need a stable configuration format, migration guarantees, centralized secret isolation, or an audited network boundary, wait for those contracts to mature or add them at a stronger container, VM, or operating-system boundary.

DeepSeek Harness is also separate from the DeepSeek model API. Installing dsh does not migrate model IDs or make a model available; model/API migration remains a different task, covered in the DeepSeek V4 API migration checklist.

What the source actually establishes

Question Confirmed at commit 99f6f02 Evaluation consequence
Product stage Developer Preview with compatibility-breaking changes expected Pin a release candidate and keep state disposable
Quick start npx @deepseek-ai/dsh web starts a Web UI on 127.0.0.1:3080 by default Verify loopback binding before entering a key
Workspace The invoking directory is the default filesystem location; a fresh UI still requires workspace selection Start from a dedicated empty directory
User state DSH_HOME overrides the default ~/.dsh root Isolate profiles, settings, credentials, sessions, and identity together
Default permission Shipped base composition uses workspace-write plus ask Keep it for the first run; do not begin with full access
Full-access preset danger-full-access pairs no file confinement with approval policy never Treat it as an explicit trust decision, never a convenience toggle
Secret storage Model keys saved in the UI go to $DSH_HOME/.credentials.yaml; settings keep only references Verify redaction, but do not mistake same-user file permissions for model isolation
Durable sessions Shipped composition stores session logs under $DSH_HOME/sessions Back up or discard the isolated root as one unit

The Web UI guide says an agent can read and edit workspace files, run commands, delegate work, and maintain a plan. That is meaningful authority. The right first question is therefore not “does the UI open?” but “can I prove where its state and effects go?”

A safe first-run workflow

1. Record the source and release boundary

Before installation, record the repository default branch, commit, GitHub release, and npm version. For this article:

repository: https://github.com/deepseek-ai/deepseek-harness
default branch: master
commit: 99f6f02fecdb7dff40c3fbc9470f5907c29f74ca
GitHub pre-release: dsh-v0.1.0-rc.7
npm package: @deepseek-ai/dsh@0.1.0-rc.7
checked: 2026-08-19

The branch name matters: the current official default is master. Copying an older note that assumes main weakens source traceability even when the commit happens to match.

2. Create two isolated roots

Use one directory for harness-owned state and another for the agent workspace. Do not launch from your home directory or a monorepo root.

trial_root="$(mktemp -d)"
mkdir -p "$trial_root/dsh-home" "$trial_root/workspace"
cd "$trial_root/workspace"

Keep the printed location in your evaluation record. The empty workspace makes unexpected writes easy to see; the separate harness home makes settings, credentials, profiles, sessions, and anonymous identity easy to quarantine.

3. Pin the preview package

Avoid an unversioned npx command in a repeatable test:

DSH_HOME="$trial_root/dsh-home" +  npx --yes @deepseek-ai/dsh@0.1.0-rc.7 web

The official README gives the unpinned quick start. Pinning rc.7 is an IndieSeek safety addition, not an official promise that this release is stable. The repository root at this snapshot declares Node.js ^22.19.0 || >=24.0.0 for source work; check your runtime and release notes again before testing a later candidate.

4. Prove the listener is local

Before entering any credential, confirm the process is listening only on loopback and that the printed URL is http://127.0.0.1:3080 unless you intentionally changed it.

Do not expose the preview UI to a LAN, tunnel, or public reverse proxy as part of the first run. Loopback binding is not authentication, and this guide does not establish a hardened remote-hosting contract.

5. Configure a test-only provider key

In Settings → Models, add a key with a narrow budget and no access to production data. The official provider guide says keys are write-only in the page: after saving, the UI receives a redacted descriptor rather than the literal value. The managed value lives in $DSH_HOME/.credentials.yaml, while settings.yaml stores its reference.

That design prevents ordinary configuration responses from echoing the key, but it is not a hard secret boundary against the agent. The credential-provider README is explicit: tool processes run as the same operating-system user, and the shipped file sandbox restricts mutations, not reads. A same-user process can deliberately read the credential file. If that risk is unacceptable, put the entire trial inside a disposable VM/container with a test credential, or wait for a provider backed by a keychain/KMS boundary.

6. Keep the default permission preset

Start with workspace-write and approval policy ask. The source defines the sandbox vocabulary as a file-effect policy:

Network and process visibility are outside that vocabulary. A sandbox report can also be partial on some host backends. Therefore, a successful outside-workspace write denial does not prove network isolation or full host containment.

The Python SDK example deserves special caution: its checked-in minimal composition uses danger-full-access, and the documentation says the Bash and editor tools may modify any path visible to the runtime process. Use that example only in a disposable checkout or container. It is an example composition, not the universal default.

7. Run a payload-free task first

Use a task that requires no repository secrets and produces an obvious, reversible artifact:

List the files in this workspace. Create trial-note.txt containing only:
deepseek-harness-evaluation
Then stop and report the path you changed.

Do not ask the first session to install dependencies, open external accounts, change Git history, or inspect private files. The goal is to test effect routing, not agent quality.

8. Preserve evidence, then exit

Stop the dsh process and inspect both roots:

find "$trial_root/workspace" -maxdepth 3 -print
find "$trial_root/dsh-home" -maxdepth 3 -print
du -sh "$trial_root/workspace" "$trial_root/dsh-home"

Keep a short record with the pinned package, commit, OS, Node version, listener address, selected permission preset, files created, approval prompts, credential source, and session-resume result. Archive the isolated root only if you need replay evidence; otherwise delete it after confirming no asset is needed. Never turn “remove the trial” into a broad recursive command whose target depends on an unset variable.

Eight acceptance tests

# Test Pass evidence Stop condition
1 Listener scope Only expected loopback listener and port LAN/public bind appears unexpectedly
2 Workspace selection UI names the disposable workspace Home directory or primary repo is selected
3 Permission baseline New session shows workspace-write with approvals Full access or never-approve appears without intent
4 Contained write Test file appears inside the workspace Write lands elsewhere or target is unclear
5 Escape denial A harmless outside-workspace write is denied or requires explicit widening Silent outside write succeeds
6 Credential presentation UI shows configured/redacted state, never the literal secret Key appears in UI response, logs, or prompt
7 State location Settings, credentials, profiles, and sessions stay under the isolated DSH_HOME New persistent state appears in the normal home
8 Restart and rollback Stop/restart behavior is understood; the two trial roots contain the whole evaluation State cannot be attributed or removal target is ambiguous

An approval dialog is evidence of policy routing, not proof that an operation is safe. Read the exact command, target, and requested widening before accepting it. This is the same trust-boundary principle used in the untrusted-repository sandbox checklist.

Promotion decision tree

Is the task disposable and free of production secrets?
  no  -> do not use this Developer Preview evaluation path
  yes -> are DSH_HOME and the workspace isolated?
           no  -> create separate roots before launch
           yes -> is the package pinned to a verified pre-release?
                    no  -> pin and record the version/commit
                    yes -> is the UI loopback-only with workspace-write + ask?
                             no  -> stop and correct the boundary
                             yes -> did all eight acceptance tests pass?
                                      no  -> preserve evidence and roll back
                                      yes -> keep use limited to preview experiments;
                                             re-run the matrix on every upgrade

Common mistakes

FAQ

Is DeepSeek Harness production-ready?

The official project does not claim that. It calls the current stage Developer Preview and warns that compatibility-breaking changes will occur. Treat each release candidate as an evaluation snapshot.

What does npx @deepseek-ai/dsh web do?

It starts the Web UI, served at 127.0.0.1:3080 by default. The process uses its invoking directory as the default filesystem location, and the fresh UI asks you to add and select a workspace.

Where does DeepSeek Harness store local data?

The shared home defaults to ~/.dsh, or to DSH_HOME when set. Shipped configuration places settings in settings.yaml, managed credentials in .credentials.yaml, profiles under profiles/, and durable session logs under sessions/.

Should I choose danger-full-access for the first run?

No. Start with the shipped workspace-write + ask baseline inside a disposable workspace. Full access bypasses file confinement and is paired with no approval prompts in the shipped preset.

How do I roll back?

Stop the process, inventory the isolated workspace and DSH_HOME, preserve only the evidence you need, and remove or quarantine those exact trial roots. Revoke the test credential separately. Do not delete your normal ~/.dsh or primary repository unless they were intentionally part of the experiment.

Sources