Skip to main content
All posts
Tutorial

DeepSeek Harness Quickstart: From npx to Your First Agent Session

Install DeepSeek Harness with npx, open the Web UI at 127.0.0.1:3080, add an API key, choose a workspace, and run your first dsh agent task from scratch.

Run npx @deepseek-ai/dsh web, open http://127.0.0.1:3080 in your browser, add a DeepSeek API key under Settings → Models, pick a workspace directory, and send a task — that's the entire path from zero to your first DeepSeek Harness (dsh) agent session. No account creation, no config file to hand-write first. This guide walks through each of those steps in order, plus what the permission prompt means and how to install your first plugin once you're up and running.

Prerequisites

dsh is a Node.js CLI, so the only hard requirement is a recent Node runtime:

RequirementVersion
Node.js^22.19.0 || >=24.0.0 (per apps/cli/package.json engines)
Tested in CINode 22.19, 24, and 26
pnpmNeeded later, once you install plugins (dsh plugin shells out to it directly)
Package manager to launch dshnpm's npx (shown below), or pnpm/bun equivalents

If you're on an older Node install, upgrade before you start — a Node version below 22.15 throws a node:zlib error the moment dsh tries to decompress an internal module (createZstdDecompress is missing). We cover that and other platform-specific install issues in Installing DeepSeek Harness on macOS, Windows, and Linux.

Step 1: Launch the Web UI

npx @deepseek-ai/dsh web

This pulls the latest published package — 0.1.0-rc.6 on npm as of this writing — and starts the Web UI, listening on http://127.0.0.1:3080 by default. dsh web is a hardcoded alias for dsh --profile web, so the first run also bootstraps a web profile under $DSH_HOME/profiles/web (default $DSH_HOME is ~/.dsh) using the built-in base + web-app bundle template.

Note that dsh is a developer preview: the README states plainly that there will be compatibility-breaking changes between releases. Pin a version in CI or automation scripts if you need reproducibility (npx @deepseek-ai/dsh@0.1.0-rc.6 web).

Open the printed URL in a browser. You should land on a setup screen rather than a chat box — that's expected, since no model provider is configured yet.

Step 2: Add your API key

Go to Settings → Models. The DeepSeek card has a single API key field; paste your key and save. There's no restart required — the next request you send picks up the new credential immediately.

Under the hood, the key is written to $DSH_HOME/.credentials.yaml, and the Web UI never echoes it back in plaintext after saving (only a masked reference). If you want to use a different provider instead — Anthropic, OpenAI, or a self-hosted OpenAI-compatible endpoint — see Setting Up Your DeepSeek API Key and Models and Using OpenAI, Anthropic, or Any OpenAI-Compatible API with DeepSeek Harness for the full configuration paths.

Step 3: Choose a workspace

Before you can start a session, dsh requires you to pick a workspace — the directory the agent will treat as its working root. This isn't optional: without a workspace selected, the "new session" flow won't let you proceed.

The directory picker has two possible backends: a native OS dialog (directory-picker-native) or an in-app browse dialog (directory-picker-browse). On some platforms — notably Windows, where the native picker depends on a binding called koffi — the native dialog can fail to load; see our Web UI guide for how to switch backends if that happens to you.

Whatever directory you choose becomes the root dsh treats as trusted for file writes under the default workspace-write sandbox mode (more on that below).

Step 4: Send your first task

Type a task into the composer and send it. A few things happen automatically:

  • dsh loads any AGENTS.md or CLAUDE.md file it finds in the workspace root, up to a 65,536-byte render budget, and folds it into the agent's context.
  • A new session defaults to the workspace-write sandbox mode: the agent can read, write, and run commands, but filesystem writes are constrained to the workspace root and platform temp directories. Network access itself is not restricted by this mode.
  • If you'd rather start with a bare-bones agent, dsh ships a built-in minimal preset — system prompt fixed to You are a helpful software engineer assistant., with only bash and str_replace_editor tools mounted. It's available as a session option in the Web UI.

You'll see the agent's plan and tool calls stream in as it works. This is a normal Cordis-plugin-driven agent loop: every tool it uses — file edit, shell command, web search — is itself a plugin registered against the running dsh instance.

Step 5: Handle the approval prompt

Because the default permission preset pairs workspace-write sandboxing with an ask approval policy, you'll periodically see a popup asking whether to allow a specific action — usually something that reaches outside the sandbox boundary, or that the plugin author flagged as needing confirmation. You can allow or deny it inline; nothing runs silently by default.

If you want a stricter or looser posture — read-only for pure inspection, or danger-full-access for a fully unsandboxed session (no approval prompts at all) — that's a permission preset choice covered in the Web UI guide linked above.

Step 6: Install your first plugin

dsh ships with core capabilities only; almost everything else — UI enhancements, memory, browser control, notifications — comes from the community plugin ecosystem. Installing one is a single command:

dsh plugin --profile web add github:liustack/modlens

That installs modlens, a vision-bridge plugin that lets text-only models work with pasted images — one of the highest-starred entries in FindHarness's curated index. The full mechanics of that command — npm vs. GitHub vs. local-path sources, the allowBuilds security prompt, updating and removing — are covered in How to Install DeepSeek Harness Plugins. You can browse the whole catalog, filtered by category, on FindHarness's plugin list or start from a specific category like UI Enhancements or Tools & Capabilities.

Quickstart checklist

[ ] Node.js ^22.19.0 or >=24.0.0 installed
[ ] npx @deepseek-ai/dsh web
[ ] Browser open at http://127.0.0.1:3080
[ ] Settings → Models → DeepSeek API key saved
[ ] Workspace directory chosen
[ ] First task sent, approval prompt understood
[ ] First plugin installed with dsh plugin --profile web add ...

FAQ

Do I need to install dsh separately before running npx?

No. npx @deepseek-ai/dsh web downloads and runs the package on demand; there's no separate global install step required to get started. You'll want pnpm on your PATH once you install plugins, since dsh plugin forwards its arguments straight to pnpm.

What version does npx install?

Whatever npm's latest dist-tag currently points to — 0.1.0-rc.6 as of this writing. dsh has no GitHub Releases page or CHANGELOG; npm is the source of truth for what version you're actually running. Pin an explicit version (@deepseek-ai/dsh@0.1.0-rc.6) if you need a stable target.

Is DeepSeek Harness free to use?

The dsh software itself is MIT-licensed and free. You still need API credits from whichever model provider you connect — DeepSeek's own API, or any OpenAI-compatible/Anthropic-compatible endpoint you configure.

Can I skip the Web UI and just run a task from the terminal?

Yes — that's what headless mode is for. See DeepSeek Harness Headless Mode for one-shot CLI and CI usage.

Why can't I reach the Web UI from another machine on my network?

By design. --host 0.0.0.0 is intentionally unsupported for safety reasons — exposing the port would expose remote code execution to your network. Stick to 127.0.0.1 or use your own trusted tunnel/port-forward, which is covered in the Web UI guide.

Next steps