DeepSeek Harness: Installation and Startup
Last updated: 2026-08-31
DeepSeek Harness installation is incredibly simple — a single command gets you started, with no complex environment configuration needed. Whether you use npx for a one-click experience or run from source for deep customization, DSH can have you up and running in 5 minutes.
💡 Tip: For first-time use, we recommend
npx @deepseek-ai/dsh web for a one-click launch with no manual dependency installation. The source code approach is for developers who need to modify the framework itself.
📋 Prerequisites: Basic command-line knowledge, completed 01-intro.md
1. What You'll Learn
- Node.js 18+ environment setup
- npx one-click launch of DSH Web UI
- Running DSH from source (pnpm install + pnpm dsh web)
- Web UI access and interface overview
- Environment variable configuration details
2. Environment Setup
(1) Node.js Installation
DSH is based on the Node.js runtime, requiring Node.js 18+ as a minimum.
BASH
# Check Node.js version
node --version
# v18.x.x or higher
# Check npm version
npm --version
# 9.x.x or higher
If Node.js is not yet installed:
BASH
# macOS (Homebrew)
brew install node
# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
# Windows (winget)
winget install OpenJS.NodeJS.LTS
We recommend using Node.js 20 LTS — this is the current most stable long-term support version, and DSH has been most thoroughly tested on it.
(2) OS Compatibility
| Operating System | Support Status | Notes |
|---|---|---|
| macOS 12+ | ✅ Fully supported | Both Intel and Apple Silicon |
| Ubuntu 20.04+ | ✅ Fully supported | LTS versions recommended |
| Windows 10+ | ✅ Supported | WSL2 environment recommended |
| Windows (Native) | ⚠️ Basic support | Some tools may have path issues |
(3) Network Requirements
DSH needs to access LLM APIs. Ensure your network environment:
BASH
# Test DeepSeek API connectivity (requires API Key)
curl -s https://api.deepseek.com/v1/models \
-H "Authorization: Bearer $DEEPSEEK_API_KEY" | head -20
# Test OpenAI-compatible endpoint connectivity
curl -s https://api.openai.com/v1/models \
-H "Authorization: Bearer $OPENAI_API_KEY" | head -20
3. One-Click Launch: npx Method
(1) Starting the Web UI
The simplest approach — no installation needed, just run:
BASH
npx @deepseek-ai/dsh web
On first run, npx will automatically download the latest version of the DSH package:
TEXT
📖 Display only
Need to install the following packages:
@deepseek-ai/dsh@latest
Ok to proceed? (y) y
🚀 DeepSeek Harness v0.x.x (developer preview)
📦 Starting Web UI...
➜ Local: http://127.0.0.1:3080/
➜ Network: http://192.168.1.100:3080/
⚠️ Developer Preview: APIs may change before stable release.
(2) Accessing the Web UI
Open your browser and navigate to http://127.0.0.1:3080/:
TEXT
📖 Display only
http://127.0.0.1:3080/
├── Left: Session List
├── Center: Chat Area
├── Right: Tool Panel
└── Top: Mode Selection + Model Selection
(3) npx Method Characteristics
| Advantages | Disadvantages |
|---|---|
| Zero installation, run immediately | May download new version each time |
| Always gets the latest version | Cannot control the version |
| Great for quick trials | Limited customization |
(4) ▶ Example 4
BASH
# Specify a version number
npx @deepseek-ai/dsh@0.5.0 web
# Specify a beta version
npx @deepseek-ai/dsh@beta web
4. Running from Source
(1) Cloning the Repository
Suitable for users who need to modify framework code or contribute to development:
BASH
# Clone the repository
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
# View available branches
git branch -r
# origin/main
# origin/dev
# origin/feature/...
(2) Installing Dependencies
DSH uses pnpm as its package manager:
BASH
# Install pnpm (if not already installed)
npm install -g pnpm
# Install project dependencies
pnpm install
pnpm install will install all workspace dependencies, including:
TEXT
📖 Display only
packages/
├── core/ # Cordis kernel
├── cli/ # CLI tool
├── web/ # Web UI
├── sdk-python/ # Python SDK
├── plugins/ # Built-in plugins
└── tools/ # Built-in tools
(3) ▶ Example 3
BASH
# Start Web UI (development mode, with hot reload)
pnpm dsh web --dev
# Start CLI mode
pnpm dsh cli
# Start Headless mode
pnpm dsh headless
Differences between development and production modes:
| Dimension | Development Mode --dev |
Production Mode |
|---|---|---|
| Hot Reload | ✅ Code changes auto-refresh | ❌ |
| Source Map | ✅ Full debug info | ❌ |
| Performance | Slower (unoptimized) | Faster (compiled optimization) |
| Log Level | debug | info |
(4) ▶ Example 4
BASH
# Build all packages
pnpm build
# Build only Web UI
pnpm --filter @deepseek-ai/dsh-web build
# Run after building
pnpm dsh web
5. Environment Variable Configuration
DSH manages API Keys, model endpoints, and other configuration through environment variables.
(1) Core Environment Variables
BASH
# DeepSeek API Key (required when using DeepSeek models)
export DEEPSEEK_API_KEY="sk-xxxxxxxxxxxxxxxx"
# OpenAI-compatible endpoint (optional, when using non-DeepSeek models)
export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"
export OPENAI_BASE_URL="https://api.openai.com/v1"
# Custom endpoint (optional, when using third-party compatible APIs)
export DSH_LLM_BASE_URL="https://your-custom-endpoint.com/v1"
export DSH_LLM_API_KEY="your-api-key"
(2) Runtime Configuration
BASH
# Web UI port (default 3080)
export DSH_PORT=3080
# Log level (debug / info / warn / error)
export DSH_LOG_LEVEL=info
# Workspace (root directory for Agent operations)
export DSH_WORKSPACE="/path/to/your/project"
# Sandbox mode (strict / permissive / off)
export DSH_SANDBOX=permissive
(3) Using a .env File
We recommend creating a .env file in your project root to manage environment variables:
BASH
# .env file example
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxx
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx
DSH_PORT=3080
DSH_LOG_LEVEL=info
DSH_WORKSPACE=/home/alice/my-project
DSH_SANDBOX=permissive
Security note: The
.envfile contains sensitive information. Make sure to add it to.gitignore:
BASH
# Ensure .env is not committed
echo ".env" >> .gitignore
(4) Environment Variable Priority
graph LR
A[Command-line Arguments] -->|Highest| RES[Final Value]
B[.env File] --> RES
C[System Environment Variables] --> RES
D[Default Values] -->|Lowest| RES
6. CLI Mode Startup
In addition to the Web UI, DSH also supports pure CLI interaction:
BASH
# Start CLI mode
npx @deepseek-ai/dsh cli
# Or specify a workspace
npx @deepseek-ai/dsh cli --workspace /path/to/project
# Specify a model
npx @deepseek-ai/dsh cli --model deepseek-chat
# Specify a running mode
npx @deepseek-ai/dsh cli --mode ptc
CLI mode interaction interface:
TEXT
📖 Display only
$ npx @deepseek-ai/dsh cli
🚀 DeepSeek Harness v0.x.x
📂 Workspace: /home/alice/my-project
🤖 Model: deepseek-chat
🔧 Mode: standard
> Help me analyze this project's directory structure
🔍 Using tool: search...
📂 Reading directory structure...
Agent: This project is a typical Express.js application. The directory structure is as follows:
...
7. Verifying Installation
(1) Check DSH Version
BASH
npx @deepseek-ai/dsh --version
# 0.x.x
(2) Check Environment Configuration
BASH
npx @deepseek-ai/dsh doctor
dsh doctor automatically checks:
TEXT
📖 Display only
✅ Node.js: v20.11.0
✅ pnpm: 8.15.0
✅ DEEPSEEK_API_KEY: configured (sk-...xxxx)
⚠️ OPENAI_API_KEY: not configured (optional)
✅ Network: api.deepseek.com reachable
✅ Workspace: /home/alice/my-project (exists)
⚠️ Sandbox: permissive mode (not recommended for production)
(3) Quick Functional Test
BASH
# Start Web UI and verify with curl
npx @deepseek-ai/dsh web &
sleep 5
curl -s http://127.0.0.1:3080/api/health | head -5
# {"status":"ok","version":"0.x.x"}
8. Common Installation Issues
(1) Node.js Version Too Low
TEXT
📖 Display only
Error: DSH requires Node.js 18 or higher.
Current version: 16.x.x
Solution:
BASH
# Use nvm to manage multiple Node.js versions
nvm install 20
nvm use 20
(2) Port Already in Use
TEXT
📖 Display only
Error: Port 3080 is already in use.
Solution:
BASH
# Specify a different port
export DSH_PORT=3081
npx @deepseek-ai/dsh web
# Or find the process using the port
lsof -i :3080 # macOS/Linux
netstat -ano | findstr :3080 # Windows
(3) Invalid API Key
TEXT
📖 Display only
Error: Invalid API key. Please check your DEEPSEEK_API_KEY.
Solution: Check that the environment variable is set correctly:
BASH
echo $DEEPSEEK_API_KEY
# Should output sk-xxxxxxxxxxxxxxxx
# If empty, set it again
export DEEPSEEK_API_KEY="sk-your-actual-key"
❓ FAQ
Q Does npx download every time?
A The first npx run downloads the DSH package; subsequent runs use the cache. If you want to avoid repeated downloads, you can install globally:
npm install -g @deepseek-ai/dsh, then start directly with dsh web.Q Can I run DSH in Docker?
A Yes. DSH provides an official Docker image:
docker run -p 3080:3080 -e DEEPSEEK_API_KEY=sk-xxx deepseek/dsh:latest.Q How do I update DSH to the latest version?
A The npx method automatically gets the latest version. For global installs, use
npm update -g @deepseek-ai/dsh. For source installs, use git pull && pnpm install.Q What are the known issues with Windows native environments?
A Path separator issues (
\ vs /) may cause some tools to malfunction. We recommend using WSL2 to run DSH for the best experience.Q How can I see DSH's detailed startup logs?
A Set the environment variable
DSH_LOG_LEVEL=debug before starting to see the full initialization process and plugin loading information.Q What should I do if pnpm install fails?
A Ensure Node.js version >= 18, then try:
pnpm store prune && pnpm install --force. For network issues, configure an npm mirror: pnpm config set registry https://registry.npmmirror.com.📖 Summary
- DSH requires Node.js 18+ minimum; Node.js 20 LTS is recommended
npx @deepseek-ai/dsh webone-click launches the Web UI, accessible at http://127.0.0.1:3080- Source code running:
git clone+pnpm install+pnpm dsh web - Environment variables are configured via
.envfile or export; API Key must be set - The
dsh doctorcommand can check environment configuration in one step - Common issues: Node version, port conflicts, API Key configuration
📝 Exercises
1. ⭐ Basic： Start the DSH Web UI using the npx method, and take a screenshot (or describe) the homepage interface elements you see.
2. ⭐⭐ Intermediate： Clone the DSH repository from source, complete pnpm install and start development mode. Record any issues encountered during startup and how you resolved them.
3. ⭐⭐⭐ Challenge： Configure DSH to connect to both the DeepSeek API and an OpenAI-compatible endpoint (e.g., Ollama). Successfully switch between the two models in the Web UI and send a message with each.
