DeepSeek Harness Web UI Guide
Starting from a running server, this guide walks you through the complete DeepSeek Harness Web UI workflow: configure the model, select a workspace, run tasks, and go further with the Python SDK and CLI modes. The dsh process uses the directory it was started in as the default filesystem location.
Get Started in Four Steps
Start the Web UI as described in the repository README (npx @deepseek-ai/dsh web); the command prints its access address. Then follow these steps to begin collaborating with your agent.
Configure the Model
Open Settings → Models, enter your DeepSeek API key, and save. Model routing becomes available immediately — no server restart needed. Other providers and custom OpenAI-compatible endpoints are also supported.
Select a Workspace
Click Select Workspace, add the project directory where dsh was started, and select it. The dsh process uses its startup directory as the default filesystem location; the session input box stays disabled until a workspace is selected.
Run Tasks
Start a session and send a task. The agent can read and edit workspace files, run commands, delegate work, and maintain plans. If an action requires approval under the current permission policy, the Web UI asks you first.
Keep Going
Configure additional providers, orchestrate from your own programs with the Python SDK, run one-shot tasks in headless mode, or develop your own Cordis plugins to extend agent capabilities.
Run Your First Task
Once the workspace is ready, send the first task to the session — for example, ask the agent to analyze the current repository:
Summarize this repository and identify its main packages.
What the Agent Can Do
Read & Edit Workspace Files
The agent reads, creates, and edits project files in the workspace, understands code structure, and applies changes directly.
Run Commands
The agent runs shell commands in the workspace to execute builds, tests, and scripts.
Delegate & Plan
The agent delegates work to subagents and maintains a plan, continuously tracking task progress.
Permission Approvals
Under the current permission policy, actions that require approval ask you first through the Web UI — safe and controllable.
Beyond the Web UI: Python SDK & Headless Mode
Beyond the Web UI, the Python SDK (Python 3.10+) calls the same API from your own programs, while headless mode runs one fresh session from the terminal and prints the final answer.
# Install the Python SDK (deepseek-harness-sdk, Python 3.10+)
python -m pip install deepseek-harness-sdk
# Use the SDK in your own program
from pathlib import Path
from deepseek_harness import DeepSeekHarness
with DeepSeekHarness(
provider="deepseek-official",
model="deepseek-v4-flash",
cwd=str(Path("/absolute/path/to/workspace")),
session_root=str(Path("/absolute/path/to/sessions")),
) as harness:
result = harness.run(
"Summarize this repository.",
session_id="example-001",
)
print(result.final_response)# Other uses of the dsh command dsh web # Web UI (alias of --profile web) dsh --profile headless "job" # one fresh session, prints the final answer dsh --profile <name> # boot the named profile dsh plugin --profile <name> ... # manage a profile's plugins via pnpm
Learn More
FAQ
How do I configure a model after starting the Web UI?
Open Settings → Models, enter your DeepSeek API key, and save. Model routing is available immediately without restarting the server. Other providers and custom OpenAI-compatible endpoints are also supported.
Why is the session input box disabled?
The session input stays disabled until a workspace is selected. Click Select Workspace, add the project directory where dsh was started, and select it to unlock the input.
What is the default filesystem location of the dsh process?
The dsh process uses the directory it was started in as the default filesystem location. A fresh Web UI selects no workspace — you need to add one manually.
What ways exist to use DeepSeek besides the Web UI?
The dsh command supports headless mode (dsh --profile headless "task" — one fresh session that prints the final answer) and booting named profiles; the Python SDK (pip install deepseek-harness-sdk) calls the same API from your own programs.