Quickstart

This page follows the public repository's official run path and gets you running before diving into internals (leave those to the concepts course and the learning path).

DSH is currently in Developer Preview, so updates may include compatibility-breaking changes. Treat deepseek-ai/deepseek-harness as the source of truth.

What you will get out of this walk

By the end you will have:

• Configured a model API key
• Opened the Web UI and completed a first conversation, and seen what the "composition tree" looks like
• Learned where your data is stored

0. Install and check requirements

Use Node.js ^22.19.0 or >=24.0.0. The zero-install entry point is:

npx @deepseek-ai/dsh web

It starts the Web UI at http://127.0.0.1:3080 by default. For source development:

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

The rest of the docs use dsh for an available CLI entry point. With the zero-install path, write npx @deepseek-ai/dsh ... instead.

1. Configure the API key

When DSH starts it reads credentials by priority: process environment → ~/.dsh/.credentials.yaml (managed storage) → working-directory .env → ~/.dsh/.env (fallback).

# Option 1: write into ~/.dsh/.env (as the fallback layer)
echo "DEEPSEEK_API_KEY=sk-xxx" >> ~/.dsh/.env

# Option 2: temporary environment variable
export DEEPSEEK_API_KEY=sk-xxx

• The official provider is deepseek-official; a model such as deepseek-v4-flash (see Configuration for the default routing).
• To use another provider / your own gateway, configure llm-pi-ai.providers (see Multi-model).

Credential safety: the managed .credentials.yaml is written atomically by DSH with 0600 permissions (0700 directory); .env is a plain environment layer whose permissions are your own responsibility. Finer details live in Credentials and Data & privacy.

2. Launch the Web UI

npx @deepseek-ai/dsh web

Your browser opens http://127.0.0.1:3080 automatically.

On first launch, a versioned notice and the model-credential step run in order. The workbench then shows:

• On the left, a collapsible Workbench sidebar (expanded column or 56px rail)
• In the middle, a workspace to pick: the first time it asks you to choose a working directory — all DSH activity happens inside the directory you pick
• On the top right, a light / dark theme toggle

By default the Web UI only listens on 127.0.0.1:3080 (loopback, not exposed to the LAN). For LAN access: dsh web --host 0.0.0.0.

Can't open it? Common causes

Symptom	Troubleshooting
Port is taken	dsh web --port 8080 to change the port
Browser didn't open	Visit http://127.0.0.1:3080 manually
Page broken / blank	dsh web --dump-config to check whether the plugin tree is healthy (below)

3. First conversation

Once you have selected a working directory, your first message triggers the full pipeline: the agent picks a model → assembles context → calls the model → (maybe) calls tools → writes back to the session. Everything is recorded into the session logs under ~/.dsh/sessions/ (zstd-compressed by default).

Try a question that triggers a tool, such as "list the first 10 files in the current directory". In the message stream you will see:

1. A user/message (what you sent)
2. Several assistant/messages or tool calls (tool/call → tool/result)
3. The agent summarizing into an answer

What that one message goes through is the whole topic of Agent main loop. Don't dig into it now — just confirm it works.

4. Verify and observe

# Composition tree: see which plugins DSH stacked together (the authoritative tool for "which layer overrides what")
dsh web --dump-config | head -40

# Session log (zstd-compressed by default, two-level --<cwd>--/<id>/ dirs)
zstdcat ~/.dsh/sessions/*/*/session.jsonl.zstd | tail -20

Each line of --dump-config normally carries a # == source annotation, so you can tell whether a config came from the base layer, the web-app layer, or your profile layer.

5. Common path shortcuts

Path	Purpose
~/.dsh/	Harness home (config, sessions, plugins)
~/.dsh/profiles/web/	Web profile (plugin mounts, dependencies, cordis.patch.yml)
~/.dsh/sessions/	Session logs (zstd-compressed, two-level dirs)
~/.dsh/.env	API key (0600 permissions)
~/.dsh/settings.yaml	Global runtime settings (default model routing, permission presets, etc.)

6. Common issues

Issue	Fix
--dump-config errors / breaks plugins	Usually a plugin failed to parse: fail-loud tells you which one; delete the suspicious patch line and retry
Model doesn't respond	Check the .env key is correct and the provider/model is fully configured (see Configuration)
Want to switch models	See Configure models

Next steps

You can run now. Pick a path based on your goal:

• Just everyday use: Usage guide → Capabilities → configure permissions
• Understand the internals: What is DSH → Agent main loop
• Give the model new abilities: Write your first plugin

For the full map see the learning path.