DeepSeek Just Open-Sourced Harness Last Night: A 20,000-Word Hands-On Tutorial by Wanshao

Just yesterday (August 13), DeepSeek officially released its first Agent product, DeepSeek Harness (dsh), and fully open-sourced it under the MIT license, directly targeting Claude Code and Codex.

The news immediately exploded across the developer community. During the internal testing phase, 769 developers signed up, and around 300 community plugins have already emerged. Some are even shouting goodbye to Claude Code.

This article combines the complete introductory tutorial into 20,000 words; you can follow along by opening the dsh web interface. Bookmark this, and it's like carrying a dsh manual with you.

---

Part 0 · Preparation

First stop: Understand what dsh is, set up the runtime environment, launch the Web UI, and understand the interface layout.

0.1 Getting to Know dsh: What It Is and What It Can Do

You will learn Understand what dsh is, what it can do, and how it differs from the ChatGPT web version you've used, then decide whether to continue reading.

What is dsh

dsh stands for DeepSeek Harness, open-sourced by DeepSeek AI. It is an agent Harness, which in plain terms is an agent runtime framework: a "cockpit" that allows an AI assistant to read and write your files, execute commands, call tools, and work according to a process.

It has four very practical characteristics:

• Graphical Interface. After running a single command, open a webpage. All configurations, conversations, and tool-calling processes are visible. You can use it with mouse clicks, no coding required.
• Everything is a Plugin. The underlying architecture is assembled using the Cordis framework. Reading files, running commands, searching the web, calling large models—each capability is a pluggable plugin. Install whatever you need.
• Safe and Controllable. When the agent wants to modify your files or execute commands, it will first ask for your permission. Every step is crystal clear.
• Open Source and Free. MIT license, code hosted on GitHub. You can deploy it yourself, modify it, and develop it further.

What It Can Do

Once installed, you can ask dsh to help you with these types of tasks:

Scenario	One-Line Instruction
Understand Code	"Summarize what this repository does and its main modules"
Modify Code	"Change all error messages in the login API to Chinese"
Run Tasks	"Run the tests, list the failed cases, and fix them"
Look Up Info	"Check how to configure local search in the latest VitePress"
Write Docs	"Generate a release note based on this project's README"
Do Chores	"Compress this batch of images to under 200KB"

The key is that it works on your real computer, reading your files and running your commands, not inside a closed chat box.

How Is It Different from the ChatGPT Web Version

This is the easiest point of confusion for beginners. Let's clarify with a table:

Comparison Item	ChatGPT Web Version	dsh
Can it see your files?	No, only chat	Yes, reads/writes after workspace selected
Can it execute commands?	No	Yes, run tests, install deps, start services
Where is the modified code?	In the chat log	Directly modified in your project
Is the process transparent?	Only gives conclusions	Full tool-call tree visible
Does it require approval?	No	Asks you before sensitive ops
Is it extensible?	No	Plugins can be installed freely

In one sentence: The web version is "ask it"; dsh is "make it do".

What Basics Do You Need

Not much, just two things:

1. Know how to install software. This article will guide you through installing Node.js and dsh, just follow the steps.
2. Know how to open a terminal and type a command. No coding or AI principles knowledge required.

How This Article Guides You

The chapter order of this article is the usage order of the dsh graphical interface. What you see first when you open the interface, what you need to click first, the article explains first:

1. Configure the model, giving dsh a "brain" to use.
2. Select a workspace, telling dsh which territory to work in.
3. Send the first instruction, watching how it works.
4. Unlock the advanced features in the session one by one.
5. Finally, learn settings, CLI, and common issues.

Follow the interface once, and you'll finish the entire tutorial.

First Glance at the Real Thing

This is the main interface after dsh starts up. Just get familiar with it first:

On the left is the workspace and session navigation, in the middle is the chat area, at the bottom is the input box, and the top right is the settings entry. We'll break down what each area does in detail below.

0.2 Environment Setup

You will learn Install Node.js, start dsh with one command, and open the graphical interface. The whole process takes about 10 minutes.

Before we start, let's be clear: you only need to install two things: Node.js (the runtime base for dsh) and dsh itself (installed via a single npm command). No database, no Java configuration, no programming knowledge needed.

Step 1: Install Node.js

dsh is written in TypeScript and runs on Node.js, so the first step is to install Node.js.

1. Open the Node.js official website https://nodejs.org/
2. Download the LTS (Long Term Support) version installer, version 22 or above is recommended.
3. Double-click to install, just keep clicking next with the defaults.

After installation, open your terminal (PowerShell or CMD on Windows, Terminal app on macOS) and enter the following two commands to verify:

node -v
npm -v

Seeing version numbers similar to these means the installation is successful:

v22.19.0
10.9.4

⚠️ Version Note dsh is currently in preview stage and requires Node.js 22 or above. If node -v shows 18 or older, please upgrade to the latest LTS before continuing.

Step 2: Start dsh with One Command

No need to install dsh separately. Just run the following command, and npm will automatically download and start it:

npx @deepseek-ai/dsh web

The first run will take a minute or two to download dependencies, and the terminal will scroll a bunch of logs; this is normal. Seeing content similar to below means the startup was successful:

DeepSeek Harness
  http://127.0.0.1:3080/

Want to install first, then start? If you don't want to use npx to download on the fly every time, you can install dsh globally first, then run it:

npm install -g @deepseek-ai/dsh
dsh web

Both methods work the same. Beginners are recommended to use npx directly, one less concept to grasp.

Step 3: Open the Graphical Interface

After successful startup, open your browser and visit:

http://127.0.0.1:3080/

Once you see the dsh main interface, the environment setup is complete.

Right now, this interface is still "empty": no workspace on the left, no session in the middle, and the bottom input box is not yet usable. Don't worry, these are exactly what we'll unlock in the following chapters.

0.3 Startup and Interface Overview

You will learn Recognize every area of the dsh main interface: sidebar, chat area, input box, top status, and settings entry, knowing where to click for each step.

Open http://127.0.0.1:3080/, and you will see the following interface:

At first glance, there isn't much information, but every corner has its purpose. Let's break it down from top to bottom, left to right.

Top Left: New Session Button

The very top left of the interface is the New Session button. Each click creates an independent conversation. You can think of it as opening a new chat window. Multiple sessions do not interfere with each other; each has its own context.

Left Sidebar: Workspace and Session Navigation

There is a navigation bar on the left side of the interface, currently only showing the Workspace entry.

The concept of a workspace runs throughout dsh. It is the project directory where you let the agent work. Before selecting a workspace, dsh doesn't know where your files are, so the chat area is "idle". We'll cover this in detail in Part 2. For now, just remember one thing: Without a workspace, dsh cannot truly get to work.

Top Status Area: Model, Permissions, and Preset

Above the chat area is a row of status information. This row is the easiest for beginners to overlook, but it's very important:

• Model: The name of the model used for the current session. You can think of it as "which brain is assigned to this job". The example interface shows a DeepSeek model. Section 1.1 will teach you how to configure and change it.
• Permissions: The permission level of the current session. The example interface shows High, meaning the agent can perform higher-privilege operations. Higher permissions mean the agent can do more, but you need to be more careful about it going rogue. Sections 4.4 and 7.2 will cover this in detail.
• Agent Preset: The example interface shows Standard Mode, which determines the agent's role and default behavior when creating a new session. This can be changed in settings, covered in Section 6.3.

Center Main Area: Chat Area

The large blank space in the middle is the Chat Area. Your sent instructions, the agent's replies, and every step of its tool calls will scroll and display here.

When first opened, it displays "Explore the Uncharted" and a Preview label; this is dsh's start page. Once we send the first instruction, this area will become lively.

Bottom: Input Box

Below the chat area is the Input Box, where you give instructions to the agent. Note that it is currently unavailable because no workspace has been selected. The input box will unlock after selecting a workspace. We'll send the first instruction in Section 3.1.

Top Right: Settings Entry

There is a Settings button in the top right corner. Click it to open the settings panel:

The settings panel has four tabs, which we will use later one by one:

Tab	Purpose	Learning Chapter
General	Agent preset, permission mode, language, theme	Part 6
Model	Configure API keys, select model providers	Part 1
Plugins	View and enable/disable plugins	6.2
Agent Preset	Select or write session presets	6.3

Before continuing, you can click open the settings panel and browse around. Just look, don't click; don't worry, you won't break anything.

Part 1 · Configure Model

The first mandatory configuration of the interface: tell dsh which model to use and where to fill in the key.

1.1 Configure the First Model

You will learn Fill in the first DeepSeek API key for dsh, bringing the "brain" online. This is the first mandatory configuration of the entire interface; the model is immediately usable after completion.

Why the First Step is Configuring the Model

We've seen the dsh interface earlier. It has everything, but it's still missing one thing: a brain.

dsh itself doesn't produce models; it's responsible for scheduling and doing the work. The actual "thinking, coding, and replying" is done by the large model service behind it. So before starting work, you must tell dsh: which provider's model to use and what key to use. Until configured, the session input box cannot truly function.

Step 1: Apply for a DeepSeek API Key

dsh has the best support for DeepSeek, working out of the box. Let's use it first.

1. Open the DeepSeek Open Platform https://platform.deepseek.com/
2. Register and log in (supports phone number or email)
3. Find API Keys in the left menu
4. Click Create API Key, give the key a name, like dsh-tutorial
5. Copy and save it immediately after creation. The format is a long string starting with sk-

⚠️ The key is only displayed once After creation on the DeepSeek platform, the key is only fully displayed once on the page. Once you close the page, you can never see it again. Please copy it to a safe place before closing the page.

Step 2: Open the Model Page in Settings

Go back to the dsh interface, click Settings in the top right corner, and in the pop-up panel, click the Model tab:

There's a sentence at the top of the page: Fill in the API keys for each provider to use their models. Below, the DeepSeek provider is listed and pre-configured by default.

Step 3: Fill in the Key and Save

1. On the DeepSeek provider card, click the Edit button.
2. An edit form pops up. Find the API Key field:

1. Paste the key starting with sk- that you copied in the previous step.
2. Don't touch other settings. The default Base URL is https://api.deepseek.com, and the model list already includes available models (V4-Flash and V4-Pro).
3. Click Save.

After saving, the model routing takes effect immediately; no need to restart dsh.

Verify

Go back to the main interface and look at the model status above the chat area. If it shows a DeepSeek model name (like DeepSeek-V4-Flash), the configuration is successful.

What it looks like before configuration If you look at this spot before configuring, it won't show a specific model. The model name will only appear after configuration, and you can click it to switch to other models, which will be covered in Section 4.1.

Security Reminder

An API key is your wallet; it's billed by usage. Treat it like a password:

• Don't screenshot the key and post it in groups or blogs.
• Don't commit it to a git repository.
• If you suspect a leak, just revoke and recreate one on the DeepSeek platform; the old key becomes invalid immediately.

1.2 Multiple Models and Custom Endpoints

You will learn Besides DeepSeek, learn to connect more model providers and connect dsh to any OpenAI-compatible service, such as a local model or an internal company gateway.

Two Connection Methods

There are two entry points on the model page, corresponding to two scenarios:

• Add Provider: Choose from dsh's built-in list of supported providers, fill in the key, and you're done. The easiest way.
• Add Custom Provider: Manually fill in a service address. Suitable for local models, relay gateways, and internal company services.

This section covers both.

Method 1: Add from the Built-in List

1. Open Settings → Model.
2. Click Add Provider.
3. In the pop-up list, select the service you use. Built-in support includes OpenAI, OpenRouter, xAI, Tongyi Qianwen (qwen), MiniMax, Moonshot, Mistral, Zhipu (zai), Xiaomi, NVIDIA, Together, and over twenty others.
4. After selection, you'll enter the provider's configuration form. Fill in the corresponding API Key and click Save.

Each provider's form looks similar, all with a key and an optional model list, consistent with the DeepSeek edit form in Section 1.1.

Can't get a key for a certain provider? Each platform has its own open platform. Go to the corresponding official website to register and apply. Once filled in, the model is immediately usable, just like DeepSeek.

Method 2: Add a Custom Provider

This entry is for "standard OpenAI-compatible interfaces". As long as your service implements the OpenAI interface protocol, dsh can recognize it. Three typical scenarios:

• Locally run models, like Ollama, vLLM, LM Studio.
• Third-party relay services that forward to multiple large models uniformly.
• Internal company gateways, only open to employees.

Click Add Custom Provider, and the following form pops up:

Field-by-field explanation:

Field	What to fill in	Example
Provider ID	A unique identifier starting with a lowercase letter, used to derive credential names	my-gateway
Display Name	The name displayed on the interface	My Gateway
API Address	The full address of the service	https://gateway.example/v1
API Protocol	Interface protocol, three options	openai-completions
API Key	The key for this service	sk-...
Model Catalog	List available model IDs	See explanation below

Which API Protocol to Choose

• openai-completions: Standard OpenAI chat completion protocol. Compatible with the vast majority of services. Choose this by default.
• openai-responses: OpenAI's new Responses protocol, only used by OpenAI's own latest services.
• anthropic-messages: Anthropic (Claude) message protocol.

If unsure, choose the first one.

How to Fill in the Model Catalog

There is a Model Catalog area in the form. Two ways to fill it:

1. Click Fetch Available Models, and dsh will automatically request the service to pull down the model list, no manual typing needed.
2. If the service doesn't support listing models, click Add Model to manually fill in: first the Model ID (the original ID used in the request, like qwen2.5-7b), then the Display Name (what you see in the interface dropdown).

Click Create Provider once done.

Practical: Connect a Local Ollama

Take the most common local model scenario as an example. Assume you have Ollama installed and running qwen2.5:7b:

1. On the model page, click Add Custom Provider.
2. Fill in Provider ID as ollama-local.
3. Fill in Display Name as Local Ollama.
4. Fill in API Address as http://localhost:11434/v1.
5. Select API Protocol as openai-completions.
6. Fill in any placeholder for the API Key (local services usually don't validate).
7. Click Fetch Available Models, or manually add the model ID qwen2.5:7b.
8. Click Create Provider.

Afterwards, you can see Local Ollama in the model selector on the main interface.

⚠️ Address for Local Services Use localhost for services on the same machine. If Ollama is running on another machine, change the address to that machine's LAN IP and confirm the service is listening on a non-localhost port.

Part 2 · Workspace

The territory where dsh works. Select a workspace, and the session input box will unlock.

2.1 What is a Workspace

You will learn Understand the concept of a workspace: what it is, why you must select it first, and what it manages.

An Analogy

Imagine you hire a remote assistant who lives online and can't see your computer. What's the first thing you need to do to get them to help you? Tell them where your project is. Otherwise, they won't know which folder to look for files in, or where to put the modified ones.

The workspace is the answer to "where is the project".

Official Definition of a Workspace

In dsh, a workspace is a persistent record of a project directory. It remembers three things:

• Directory Path: The real location of the folder where you want the agent to work.
• Display Name: The name shown on the interface, defaulting to the directory name.
• Session Affiliation: All sessions created within this workspace.

In one sentence: Workspace = Directory + Name + Its Session List.

Why You Must Select a Workspace First

Because all of dsh's "hands-on" actions are based on the workspace:

Action	Dependency on Workspace
Read Files	Which directory to look for files in
Modify Code	Which directory to write changes back to
Run Commands	Which directory to execute commands in
Session Affiliation	Which project this conversation belongs to

Without selecting a workspace, the agent has no "territory" and naturally cannot truly work. This is why the session input box is locked on the main interface until a workspace is selected.

One Directory, One Workspace; Can Have Many

• One workspace corresponds to one directory. The path is normalized, so the same directory won't be created twice.
• Multiple workspaces can be added, corresponding to your multiple projects.
• Workspaces and your file system have a reference relationship: Adding a workspace does not copy or move any of your files. Deleting a workspace does not delete your files; it just removes this "record" from the interface.

What a Workspace Looks Like on the Interface

Open the dsh main interface. The top of the left sidebar is the Workspace section:

The section lists the workspaces you've added. Under each workspace, its sessions are expanded. The first workspace you add will immediately appear here.

2.2 Adding, Selecting, and Creating

You will learn Hands-on: add your first workspace. Find the entry, select the directory, confirm the addition, and finally see it in the sidebar.

Where is the Entry

There are two entry points for adding a workspace, both on the main interface:

1. The Select Workspace button at the top of the chat area. In a freshly installed dsh, the chat area will prompt you to select a workspace upon opening. Click it.
2. The Add button in the Workspace section of the sidebar. Hover your mouse over the Workspace section title in the sidebar, and an add icon will appear on the right. Clicking it also works.

Both entries lead to the same place: they open the system directory picker (the dialog you use to select folders in your file explorer).

Step 1: Select a Directory

After clicking the add entry, the system pops up a directory selection dialog:

1. Find the project directory where you want the agent to work, e.g., my-project.
2. Select this folder (note: select the folder itself, not go inside and select a file).
3. Click confirm.

Which directory is suitable to select Selecting the project root directory is most suitable, like your repository root or website source code directory. This way, the agent can read all files in your project. Don't select large, all-encompassing directories like C drive or user home directory; too large a scope makes the agent slow to find things and increases the risk of misoperation.

Step 2: Confirm Addition

After selecting the directory, dsh automatically does two things:

1. Creates a record in the workspace list, with the display name defaulting to the directory name.
2. Automatically selects this workspace, making it the current workspace.

Go back to the main interface and look at the Workspace section in the left sidebar. Your project directory name has appeared. Hover over it to see the full directory path.

At the same time, you'll notice the session input box at the bottom is now unlocked, ready to receive instructions.

Managing Workspaces

After a workspace appears in the list, hovering over the workspace row reveals an operations menu. Three commonly used ones:

Operation	What it does	Note
Rename	Change the display name	Only changes the interface display name, does not affect the real directory name.
Delete	Remove the workspace from the list	Has a confirmation popup. Does not delete your files or sessions. Sessions are moved to "Ungrouped".
Archive Sessions	Move sessions into the archive	Non-destructive, can be restored to view anytime.

Switching Between Multiple Workspaces

If you have multiple projects, just go through the add process again, one workspace per project. Afterwards, click any workspace name in the sidebar to switch the current workspace, and the corresponding sessions will switch along with it.

Each workspace is independent; sessions from this project won't mix into another project.

Part 3 · First Session

Send the first instruction and witness how the agent reads files, runs commands, and delivers results to you.

3.1 New Session and First Instruction

You will learn Create a new session, send the first instruction to the agent, and watch with your own eyes as it reads files, runs commands, and delivers results in your workspace.

Step 1: Create a New Session

The top left corner of the main interface is the New Session button. Click it to create a brand new session. Each click is an independent conversation, with contexts not interfering with each other.

After creation, the chat area shows a welcome page, and the bottom input box is unlocked (the input box becomes available once a workspace is selected). There's a prompt in the input box: Describe what you want to build.

Step 2: Enter the First Instruction

Type your first sentence in the input box. For the first time, recommend this "summary" type of instruction, which is read-only, safe, and immediately effective:

List the files in the current workspace directory and briefly explain what this project does.

You can also replace it with anything else you want it to do, such as:

Type	Example Instruction
Understand Project	"Summarize the module structure of this repository"
Find Something	"Find all places where TODO is written"
Modify Something	"Change the title of the login page to Welcome Back"
Run Tasks	"Run the tests and report the results"

The more specific the instruction, the better The agent works according to instructions. If the instruction is vague, it can only guess. Clearly state what you want it to do, the scope, and the output format in one go to save many back-and-forths later.

Step 3: Send and Observe

After typing, press Enter to send (or click the send button). After the message is sent, you will see two things happen simultaneously:

1. Your message appears in the chat area.
2. Below the message, a series of tool rows start scrolling. This is the trail of the agent working.

The first run will take some time. It needs to think about your instruction, then call tools to look at the files in the workspace, and finally summarize into an answer. Short tasks take a dozen seconds, long tasks a few minutes; both are normal.

Step 4: Wait for It to Deliver

After the agent finishes, the chat area will leave a complete record: your question, every step of its tool calls, and the final answer. At the bottom, there's a line of statistics telling you how long this task took, how many rounds of tools were called, and how many tokens were consumed.

Your first instruction will usually make the agent list the workspace and introduce the project. Its answer might be surprisingly detailed, which is exactly the evidence that it's "really working".

3.2 Understanding the Tool Call Tree

You will learn Understand what those tool rows in the conversation are: how the agent thinks, calls tools, and completes the work step by step.

What is a Tool Call Tree

In a normal chat, the AI gives you a piece of text and it's over. But dsh's agent is different; it needs to truly act: read files, search code, run commands. Every step it takes adds a row of record on the interface. These records strung together form the Tool Call Tree.

In one sentence: Tool Call Tree = the ledger of every step the agent took to work.

Look at a Real Tool Call Tree

Below is the actual tool call tree generated by the agent after I sent the instruction "list workspace files and introduce the project":

Looking from bottom to top, it's a process like this:

Tool Row	What it did
Context Injection · System Prompt	Equipped the agent with the factory settings on "how to work"
Context Injection · Skill Catalog	Loaded the list of available skills, letting it know what cards it holds
Think	First thought: what does the user want, what's the first step to take
Pwsh	Executed a command to list files in the workspace directory
Glob	Searched for files by pattern, e.g., looking for README files
Think	Looked at the results, thought about the next step: need to understand each project
Pwsh	Executed another command to read key info from each project
Think	Information gathered, started organizing the final answer

See the pattern? The agent's work rhythm is: think a bit, act a bit, see the result, think again, act again. Every tool call row is a real step it executed, not just for show.

Click on Tool Rows to See Details

Every tool row can be clicked to expand and see the full content of that step. For example, clicking a Think row shows the agent's thought process at that time:

Clicking a Pwsh row shows the actual command executed and its output. Clicking a Context Injection row shows the injected prompt content. If you want to confirm what the agent actually did to your project, click through row by row; everything is transparent.

Several Common Tool Rows

Different tasks use different tools. Get to know a few common ones:

Tool Row	Function	Common Scenarios
Think	Model's internal thinking	Almost before every action
Pwsh / Bash	Execute commands	List directories, run tests, install dependencies
Glob	Search by filename pattern	Find README, find config files
Read	Read file content	View code, view documents
Write / Edit	Write, modify files	Modify code, write documents
Context Injection	Inject system prompts, skills	At the start of every session

The more tools, the more the agent can do. The ones listed above are all built-in capabilities. Later chapters will show more (sub-agents, workflows, web search, etc.).

Statistics at the Bottom of the Message Stream

After a task is completed, a line of statistics is displayed below the tool call tree, for example:

1 round · 4 steps | LLM 14.9s · Tool Calls 45.5s | Cache Hit 71% | Input 76K tok · Output 1.6K tok

Let's break it down:

• 1 round: How many rounds this task ran (one round = one complete think + act cycle).
• 4 steps: Total number of tool calls made.
• LLM 14.9s: How long the model spent thinking.
• Tool Calls 45.5s: How long the actual actions like executing commands and reading files took.
• Cache Hit: How much content hit the context cache. Higher hit rate means more cost savings.
• Input / Output tok: The amount of Tokens consumed by this task.

As tasks get longer, these numbers help you judge whether time was spent on "thinking" or "doing".

Part 4 · Advanced Sessions

Ten advanced features hidden in the session: from switching models to the trace view, unlock them one by one.

4.1 Switching Models

You will learn Learn to switch models within a session and adjust the reasoning level based on task difficulty.

The Model is the "Brain", Changeable Anytime

After configuring a model, dsh defaults to the one you set. But in actual work, you'll find that different tasks suit different models:

• Simple tasks (looking up info, formatting) use lightweight models, fast and cheap.
• Complex tasks (refactoring code, designing architecture) use stronger models for deeper thinking.

The good news is switching doesn't require a restart; you can change it mid-session.

Where is the Model Selector

There are two entry points, both on the main interface:

1. Left side of the input box: There's a button showing "Select model, current DeepSeek-V4-Flash, reasoning level High".
2. Top status area: Click the area showing the current model name; it also opens.

Clicking opens the model selector:

Two Settings: Model + Reasoning Level

There are two items in the selector:

Model: Lists all configured and available models. Whatever providers you've configured, their models are selectable here. Click a model name to switch; it takes effect immediately.

Reasoning Level: Controls how "deeply" the model thinks. Options are generally High, Medium, Low tiers:

Level	Suitable Scenes	Cost
High	Complex reasoning, architecture design, difficult troubleshooting	Slower, more tokens
Medium	Daily development, medium tasks	Balanced
Low	Simple Q&A, formatting	Fastest, cheapest

Suggestion Start with the default tier. If the answer feels too shallow, bump it up a tier. If it feels too slow, bump it down. There's no absolutely correct setting; adjust based on the task feel.

What Happens After Switching

Switching is instant; the model name on the interface updates immediately. Note:

• Switching models does not clear the current session; previous conversation history remains.
• After switching, the new model is used starting from the next message.
• If the switched model doesn't have a configured key, it will prompt as unavailable. Go back to Part 1 to check.

4.2 Adding Attachments

You will learn Learn to feed files and images to the agent, letting it work based on your materials.

Why Feed Attachments

Relying solely on text for conversation leaves many scenarios unclear:

• You want it to build a page based on a design mockup. Describing colors and spacing is tedious; drag the image in, and it sees it directly.
• You want it to analyze some data. Drag the CSV file in; it can calculate after reading.
• You want it to modify code according to a document. Drag the document in; it modifies accordingly.

This is the purpose of attachments: let the agent directly "see" your materials, rather than relying on your description.

How to Add Attachments

The method is straightforward, just like attaching files in chat software:

1. Drag the file or image directly into the input box area; release to add.
2. Or click the attachment entry in the input box to select files.

After successful addition, a thumbnail or file bar for the attachment appears above the input box. Confirm it's correct and send as usual.

After sending, the attachment appears as part of the message in the conversation stream. The agent will "look" at the attachment first before answering you.

What Can You Actually Send

dsh supports common file types. The most used in practice are:

Type	Typical Use
Images	Design mockups, screenshots, flowcharts; let it implement based on them
Text Files	Code, documents, configs; let it analyze based on content
Data Files	CSV, JSON; let it calculate, extract, clean
Archives	Code for an entire project; let it understand the structure

How to Handle Large Files Files that are too large will eat up context space. If it's an entire project, it's better to set the project directory as a workspace (Part 2) and let the agent read it itself, rather than compressing and uploading.

Attachments Enter Context and Consume Tokens

Each attachment is converted into content the model can understand, consuming context tokens. The more and larger the attachments, the higher the conversation cost. Delete used files to keep the context within a reasonable range.

This is also why: Files readable via the workspace shouldn't be sent as attachments.

4.3 Commands and References

You will learn Learn to use slash commands to invoke skills and use references to bring skills and sub-agents into the session, doubling the efficiency of the input box.

Two Shortcuts Hidden in the Input Box

dsh's input box isn't just a place to type. Typing two symbols in the input box pops up two shortcut panels:

• Type /, and the command and skill list pops up.
• Type @, and the reference list pops up.

Get familiar with them first, then we'll talk about each.

Slash Commands: Let the Agent Work with Skills

Typing / in the input box pops up the command list. This list contains both dsh's built-in commands and the skills you've installed:

Select a skill, and it will be added to your instruction in a way that tells the agent "use this skill to work". For example, if you installed a video production skill, type / to select it, then add "make an intro video from this URL", and the agent will execute according to that skill's workflow.

The benefit of slash commands is turning complex capabilities into a single sentence. How skills are installed and used is managed by dsh's plugin system; you just need to know how to select.

References: Bring Skills or Sub-agents into Context

Typing @ in the input box pops up the reference panel:

The purpose of referencing is to "call out" something by name, letting it participate in this conversation. Things you can reference include:

• Skills: Specify which skill the agent should use.
• Sub-agents: Bring a sub-agent in to collaborate (detailed in Section 4.7).
• Files: Directly reference files within the workspace.

References are similar to slash commands but more flexible: you can use them within a sentence, like "Use @some-skill to translate this document into English".

How to Decide Which to Use

Situation	Use Which
Want it to work using a specific skill	Slash / or Reference @ both work
Want to reference a specific file	Reference @
Want to bring a sub-agent to collaborate	Reference @
Want to execute a built-in command	Slash /

Just remember one thing: To add capability to the agent, type /; to call out something by name, type @.

4.4 Permissions and Approval

You will learn Understand what permission modes are, how to switch them, and how to handle the approval popup when the agent wants to perform an "out-of-bounds" operation.

Permission Modes: Setting Boundaries for the Agent

When an agent works on your computer, there must be boundaries on "what it can and cannot do". dsh uses permission modes to manage this.

The permission mode determines two things:

• Sandbox: The scope within which the agent's commands execute (only touch the workspace, or the entire system).
• Approval: For operations exceeding the scope, whether to ask you or directly deny.

Where to Switch Permission Modes

On the left side of the input box is an Access Mode button showing the current mode, e.g., "Access Mode, Current: Workspace Write". Click it to pop up the permission selector:

Common tiers from low to high:

Mode	What it can do	Suitable for
Read Only	Only read, cannot modify anything	Just asking questions, viewing code, looking up info
Workspace Write	Can read/write files within workspace, run commands	Daily work (Recommended)
Full access	Can touch the entire system	Scenarios requiring global operations, use with caution

Switching takes effect immediately. Note: Switching permission mode only affects subsequent operations; already running tasks maintain the mode they started with.

Approval: Operations Exceeding Boundaries Will Ask You

Even with a mode set, the agent might encounter a situation where "this step exceeds permissions". At this point, dsh will stop and ask you, popping up an approval card on the interface:

1. Displays the operation content the agent wants to execute.
2. You choose Allow this once or Deny.

Key point: Allowance is one-time. Every time the agent performs an operation exceeding permissions, it must ask separately. Approval only lets through the current single step, not "once and for all". This is the core of dsh's security: the agent can never bypass you to act on its own.

What to Look at During Approval Don't just click "Allow" without looking. First, check the specific operation written on the approval card: which file it wants to modify, what command to run, what address to access. Decide after seeing clearly.

Approval Strategy: ask vs never

Behind the permission mode are two approval strategies:

• ask: Default. Asks you for every out-of-bounds operation.
• never: Never asks, directly denies. Suitable for unattended automation scenarios; rather fail than risk.

For daily use, keep it on ask. The never mode is mainly for automation, CI, and similar scenarios, to be expanded upon in advanced content later.

Practical Advice

• Daily use: Workspace Write, allows work while maintaining boundaries.
• Read-only inquiries: Switch to Read Only, the most reassuring.
• Full access: Only use temporarily when explicitly needed, switch back after use.
• Look carefully at approval popups before clicking; this is the last safety gate.

4.5 Setting Goals

You will learn Learn to use the goal feature to keep the agent focused on one thing, preventing it from being sidetracked by minor issues midway.

Why Goals Are Needed

When an agent works, a common situation occurs: you tell it "fix the login page bug", and while fixing, it starts optimizing the layout, tidying up code style, and eventually veers off course.

Goals are meant to cure this. You first clearly tell the agent "what this session needs to accomplish", and it will check against the goal at each decision round, pulling itself back if it deviates.

How to Set a Goal

Setting a goal doesn't require finding a special interface button; just tell the agent directly in the conversation. There are two ways:

Method 1: Say it together with the task

The goal for this session is: Fix the display issue of the login page on mobile. Start investigating now.

Method 2: Add mid-task

Set goal: Finish fixing the login page bug first, hold off on other optimizations.

After saying this, dsh will record the goal, and the current goal status will appear on the interface, letting you see at any time which direction this session is heading. Every step the agent takes will be checked against this goal.

What States Does a Goal Have

A goal isn't just "set and forget"; it has a lifecycle, and the interface shows which stage it's currently in:

Status	Meaning
In Progress	Actively progressing towards the goal
Paused	Temporarily set aside, possibly interrupted by other matters
Blocked	Stuck, needs your intervention (e.g., missing permissions, info)
Completed	Goal achieved

When stuck, the agent will explain the reason and wait for you to handle it. This is also its mechanism for actively "asking for help": if it can't proceed, it tells you, rather than making things up.

A Complete Example

See how this session stays focused thanks to the goal:

1. You send: Set goal: Complete the README for this project, only do this, then start.
2. The agent confirms the goal and starts reading the existing README and code.
3. Midway, the agent thinks about "fixing the formatting along the way", checks against the goal, finds it unrelated to the README, and skips it.
4. After the README is completed, the agent reports and marks the goal as Completed.

The whole process didn't deviate because every step had a goal to check against.

The more convergent the goal, the better "Complete the README" is much more effective than "improve this project". If the goal is vague, the agent can't judge what counts as deviation.

4.6 Plan Mode

You will learn Learn to use Plan Mode to have the agent first lay out the steps for you to see, and only act after your approval.

When Do You Need Plan Mode

For most tasks, it's fine for the agent to think and act as it goes. But some tasks aren't suitable for "thinking while doing":

• Large-scale changes: Like refactoring an entire module. If you realize the direction is wrong halfway through, the rework cost is high.
• Wide-reaching changes: Changing one place affects a dozen files. It's best to see the full picture first.
• Error-intolerant tasks: Like database migrations, where one wrong step spells trouble.

For these tasks, you want it to submit a plan first, get your nod, then act. Plan Mode is for exactly this.

How to Enter Plan Mode

Plan Mode is controlled via slash commands. Type in the input box:

/plan

After sending, dsh enters Plan Mode. Its effect is: For every subsequent step, the agent first thinks, then produces a plan, waits for your review, and will not directly execute.

To exit Plan Mode, type:

/plan off

You can also enter with a message, like:

/plan Help me refactor the permission validation part of the login module

This command simultaneously enters Plan Mode and submits your request as the next task for the agent.

What Happens in Plan Mode

After entering Plan Mode, when you send a task, the agent will:

1. First Research: Read relevant code, clarify the current state (at this stage, it only reads, doesn't modify).
2. Produce a Plan: Organize the steps to be taken into a plan and present it to you.
3. Wait for Your Review: You check this plan, approve it, or suggest modifications.
4. Execute After Approval: Only after you nod does it start truly acting.

The interface will display the Plan Mode status, letting you clearly know if it's currently "awaiting review" or "executing". Every modification the agent makes strictly follows the approved plan.

A Complete Example

Suppose you want to refactor a module:

1. Type /plan Refactor the permission validation of the login module.
2. The agent starts reading code, only reading, not modifying.
3. A few minutes later, it gives a plan: Step 1 extract common validation function, Step 2 replace three call sites, Step 3 add tests.
4. You check, feel Step 2 also needs to modify an old interface mentioned in a comment, and ask it to add that.
5. The agent updates the plan, you approve.
6. It executes step by step according to the plan, each step corresponding to an item in the plan.

Throughout the process, you know what it's going to do and where it's at.

Plan Mode is not a panacea Plan Mode is a "soft constraint". It guides the agent to plan first, then execute, but doesn't additionally restrict its tool permissions. Permission boundaries are still managed by the permission modes discussed earlier. For small daily tasks, there's no need to turn on Plan Mode; it just adds an extra review step.

4.7 Sub-agents

You will learn Learn to have the agent split tasks among sub-agents, with multiple sub-agents working in parallel, and the main agent coordinating and summarizing.

What are Sub-agents

An agent works as a single thread from start to finish. But some tasks naturally suit division of labor:

• Research tasks: Simultaneously check docs, check code, check community; three directions without interference.
• Large project overhauls: One sub-agent modifies the frontend, another the backend.
• Independent sub-tasks: Have one sub-agent specifically verify data, another specifically write tests.

Sub-agents are sub-agents delegated by the agent. The main agent breaks down the task, distributes it to sub-agents for parallel execution, and finally collects the results to summarize for you. It's equivalent to the main agent being a project manager, and sub-agents being the team members doing the work.

How to Trigger Sub-agents

No special button needed; just say it directly in the instruction:

Use two sub-agents to research in parallel: one checks the docs for this framework, one checks community practice cases, and summarize at the end.

When the agent judges a task suitable for splitting, it will also decide to use sub-agents on its own. You'll see sub-agent rows in the message stream: they display like tool calls, but when expanded, they contain the sub-agent's own complete conversation record.

Sub-agents on the Interface

Sub-agents have several presentation characteristics on the interface:

• Sub-agent Rows: Each sub-agent gets a row in the message stream, showing what task it was assigned.
• Full Transcript: Click open a sub-agent row to see the sub-agent's complete conversation (what it thought, what tools it called, how it delivered).
• Sub-agent Navigation: From the parent session, you can enter the sub-agent's session view, like opening a sub-conversation.
• Parallel Status: When multiple sub-agents run simultaneously, their statuses are displayed independently.

What Can You Do with Sub-agents

Besides "assigning work", you can also:

• Send messages to sub-agents: Supplement information midway, adjust direction.
• Interrupt sub-agents: Stop them if they go off course.
• View sub-agent list: See clearly which sub-agents are currently running and their status.

When to Use Sub-agents

Scenario	Benefit of Sub-agents
Multi-direction research	Parallel search, saves time
Frontend/backend or multi-module parallel changes	No blocking each other
Independent sub-tasks	Context isolation, no mutual interference

Tip Sub-agents suit tasks that are "splittable, each doing its own thing". Tasks that are tightly coupled, where changing one part affects the whole, are not suitable for splitting; it's more stable to let one agent handle it from start to finish.

4.8 Background Tasks

You will learn Learn to offload time-consuming tasks to the background for execution, so the conversation isn't blocked, and you can come back anytime to collect the results.

When Do You Need Background Tasks

Some tasks the agent does are very slow:

• Running a full test suite takes several minutes.
• Batch processing a bunch of files takes a long time.
• Building a large project, compilation takes a while.

If you let the agent run such tasks to completion, your conversation will just "spin", and you can't ask it to do anything else in the meantime. Background tasks are the solution: put these time-consuming tasks to run in the background, the conversation immediately becomes available again, and you can come back to collect the results after the task finishes.

How to Put a Task in the Background

Just like with sub-agents, say it directly:

Put this batch compression task to run in the background, and tell me the result when it's done.

The agent will register the task as a background task, and the conversation recovers immediately. You'll see a background task list appear at the top of the session, displaying the status of each task in real-time.

Background Tasks on the Interface

Background tasks have a dedicated spot on the interface:

• Session Header Task List: All background tasks for the current session are listed here.
• Real-time Status Display: Running, Stopping, Completed, Failed, Terminated—clear at a glance.
• Task Details: Click to see the specific progress and output of the task.

After a task finishes, the agent will report the result in the conversation. You can also check from the task list anytime.

Background Task Statuses

Status	Meaning
Running	Currently executing
Stopping	Received stop instruction, winding down
Completed	Finished running, results can be viewed
Failed	Encountered an error, check details for cause
Terminated	Manually terminated

Common types of background tasks include command-line tasks, sub-agent tasks, etc., all uniformly managed by the background task system.

Practical Advice

• Default long tasks to background: For tests, builds, batch processing, just say "run in the background".
• Manage when tasks are many: Too many background tasks will compete for resources; terminate unused ones promptly.
• Confirm results: Task completion doesn't equal correct results. Spot-check after receiving the report.

4.9 Workflows

You will learn Get to know workflows: orchestrate multi-step processes into scripts, automatically launch sub-agents, and run an entire pipeline in one go.

What is a Workflow

Sub-agents solve the "splitting" problem, background tasks solve the "waiting" problem, but one layer is still missing: process orchestration.

For example, you have a fixed routine: pull data, clean, generate report, publish. This process needs to be walked through every time. If you rely on manually sending instructions, repeating it over and over is tiring.

Workflows are about writing such processes into an orchestration script: the script defines in order what to do at each step, when to start sub-agents, and how sub-agents connect. After the agent writes the script, one command runs the entire pipeline.

Difference Between Workflows and Regular Tasks

Comparison	Regular Task	Workflow
Process	Decided on the fly, think while doing	Script-solidified, executed step-by-step
Sub-agents	Split on the spot	Orchestrated in script, auto-launched
Reusability	Start anew each time	One script runs repeatedly
Suitable for	One-off tasks	Repetitive processes

In one sentence: A regular task is "do it once"; a workflow is "define a process, run it henceforth".

How to Use Workflows

Workflows are currently a more advanced capability. Remember two points for usage:

1. Let the agent execute using a workflow: For repetitive processes, tell the agent "write this process as a workflow and run it". The agent will write the orchestration script and execute it. Every step in the script (including launching sub-agents) will proceed in order.
2. View the running process: As the workflow runs, the interface displays each step in a nested expandable manner. You can expand layer by layer to see: which sub-agent this step called, what the sub-agent did, what the result was.

When Is It Worth Using

• Fixed processes run repeatedly: Like generating a data report weekly.
• Multi-step strong dependencies: The output of step 1 is the input for step 2.
• Involving multiple sub-agent collaborations: Script unified orchestration, avoiding ad-hoc assembly on the spot.

Learning Advice Workflows are the most advanced feature in this chapter. Beginners should first aim to "recognize it, be able to use it to run existing processes". For deep orchestration and script writing, wait until you're familiar with the basic features before looking at advanced content.

4.10 Trace View

You will learn Learn to switch to the Trace View to review, from a "raw record" perspective, exactly what the agent did at each step.

One Session, Two Views

Open a session, and at the top of the chat area are two view tabs: Chat and Trace.

• Chat View: Default. Shows the "human-readable version": your messages, the agent's replies, collapsed tool rows. Suitable for daily viewing.
• Trace View: Shows the "raw version": the complete original record of every round in the session, verbatim.

Most of the time, the Chat View is sufficient. Switch to the Trace View when you want to figure out "what exactly did the agent do".

Chat View vs Trace View

These are two presentations of the same session. The Chat View looks like this:

It organizes the agent's workflow into a clear message stream. Switching the same session to the Trace view looks like this:

The Trace View is organized by turns, with each turn fully recording the following content:

Record Segment	Content
Turn	Which round, which step
USER	Your original input
CONTEXT	Injected runtime context (current permissions, workspace, available skills, etc.)
ASSISTANT	The agent's complete thought process
TOOL	The raw JSON of the tool call and the returned result

When to Use Trace View

• Troubleshooting "why did it do that": Chat View only gives conclusions; Trace View shows the thought process and original context for each step.
• Viewing context injection: Want to know what system prompts and skill lists the agent saw? It's all in the trace.
• Verifying tool calls: Chat View's tool rows are summaries; the trace has the complete parameters and raw returns of the tool calls.

How to Switch

Click the Trace tab at the top of the chat area to switch, and click Chat to switch back. Switching doesn't affect the session content; it's just a different way of viewing.

Small Tip The Trace View has a lot of information; it's for "checking details". For daily work, just use the Chat View; don't get overwhelmed by the raw records.

Part 5 · Session Management

The sidebar is the main console for sessions: multi-session switching, history recovery, not missing a single one.

5.1 Session List and History

You will learn Learn to use the sidebar to manage sessions: create, switch, search, restore history, as well as rename, fork, and archive.

The Sidebar is the Main Console for Sessions

dsh's left sidebar is not just navigation; it's the main console for sessions. All sessions are here, grouped by workspace, giving you a clear view of what conversations exist under each project.

From top to bottom, the sidebar contains: the New Session button, the Workspace section (workspaces + their session lists below), a session search box, view options, and a settings entry.

Creating a New Session

Two ways:

1. Click the New Session button at the top of the sidebar to create an independent session.
2. In the workspace row's menu, select New Session in this Workspace, and the new session is directly affiliated with that project.

Opening History Sessions

Want to go back to a previous conversation and continue? Directly click the corresponding session row in the sidebar, and the chat area will load the complete history of that session, allowing you to scroll through and continue chatting from start to finish.

Session rows also display some status info: running sessions have a running indicator, those awaiting your approval are marked, making it easy to spot sessions needing attention at a glance.

Searching Sessions

When you have many sessions, scrolling to find one is tiring. Use search:

1. Click Search Sessions in the sidebar (magnifying glass icon).
2. Enter a keyword, like "README".
3. Results are listed by relevance; click one to go directly.

The search scope includes session titles and content. If the title doesn't yield results, try searching the content.

Session Row Operations

Hovering over a session row reveals operation buttons. Clicking opens these common operations:

Operation	What it does	When to use
Rename	Give the session a more recognizable name	When the auto-generated title isn't satisfactory
Fork	Copy a new line from a node in this session	When you want to try a different direction based on an old conversation
Archive	Move the session to the archive, hide from list	For sessions temporarily not needed, keep for later retrieval

Fork is a powerful tool Forking doesn't touch the original session. It copies a new session from the position you select, leaving the original intact. Great for experiments and trying different approaches.

Workspace Row Operations

Workspace rows also have an operation menu: Rename (change display name), Delete (remove record, does not delete files or sessions; sessions go to Ungrouped). This was covered in Section 2.2, so we won't repeat it here.

View Options

The View Options button in the sidebar can adjust how sessions are displayed, such as sorting by recent update, manual sorting, grouping by workspace, or flattening into a single list. Choose according to your habit.

Part 6 · Settings and Personalization

Tune dsh to your shape: General, Plugins, Agent Presets, Themes.

6.1 General Settings

You will learn Go through dsh's general preference settings: preset, permissions, language, appearance, Enter behavior.

Where is the Settings Panel

Click the Settings button in the top right corner of the main interface to open the settings panel. The first tab is General Settings, where all daily-use preferences are located.

What's in General Settings

Setting Item	Function	Default
Agent Preset	What Agent new sessions default to (Standard Mode, etc.)	Standard Mode
Permissions	Default permission mode for new sessions	Workspace Write
Language	Interface language	Chinese
Appearance	Interface theme (Light/Dark/Follow System)	Follow System
Enter Behavior When Busy	What happens when you press Enter while the agent is running	Queue to send

Let's explain each one.

Agent Preset: Determines the agent type for new sessions. Switch to "Standard Mode", and new sessions will be fully-featured coding Agents. Section 6.3 details what types are available.

Permissions: Default permission mode for new sessions, corresponding to the tiers in Section 4.4. Keep it on Workspace Write for daily use; manually switch if global operations are needed.

Language: Interface language. Currently supports Chinese; switching takes effect immediately.

Appearance: Theme setting, choose from Light, Dark, or Follow System. Detailed in Section 6.4.

Enter Behavior When Busy: What happens when you press Enter while the agent is running. Default is Queue to send: after pressing Enter, the message queues up, and the agent automatically continues processing when done. Change the option if you want different behavior.

Open Configuration File

There's also an Open Configuration File entry in the settings panel. Clicking it shows dsh's actual configuration file. Beginners are advised not to directly edit the configuration file. Use the interface for settings first; editing the config incorrectly can easily cause problems.

6.2 Plugins

You will learn Get to know the plugins page in settings: how to view installed plugins and how to adjust the behavior of core plugins.

Where is the Plugins Page

In the settings panel, click the Plugins tab. A sentence at the top of the page sums it up: Configure and view the plugins installed in this deployment.

Core Plugin Configuration

The plugins page lists configuration items for several core plugins, which are the foundation of dsh's capabilities:

Plugin	Controls what
Terminal	Restricts every command the agent runs
Agent Loop	How the Agent dispatches tool calls
Web Search	DeepSeek search provider

Take Terminal as an example: it's responsible for safeguarding the agent's command execution. Here you can configure the execution scope of commands, whether to enable sandboxing, etc. It's part of the security boundary.

Plugin List

The plugins page also has a Plugin List view, listing all plugins currently installed in the deployment. For each plugin, you can see:

• Plugin Name: e.g., various capability plugins, UI plugins.
• Running Status: Whether it's running.
• Configuration Entry: For plugins with configurations, you can enter from here.

The Relationship Between Plugins and Skills

You might ask: Are plugins the same as the skills mentioned in Section 4.3?

Not exactly the same. Understand them as two layers:

• Skills are "instruction manuals" for the agent, telling it how to complete a certain type of task.
• Plugins are the "parts" of capabilities. Skills, tools, interface components are all assembled through plugins.

Skills are invoked in sessions using the slash / command; plugins are managed in settings. They are two sides of dsh's plugin system.

6.3 Agent Presets

You will learn Understand what Agent Presets are, learn to switch between presets, and know how to create a custom preset.

Presets Determine "What the Agent is Like"

Within the same dsh, the agent can have different "forms": some are fully-featured, some are streamlined, some can be extended by you. Agent Presets are the factory configurations for these forms, determining what an agent in a new session is like.

Click the Agent Preset tab in the settings panel to see all presets:

Four Built-in Presets

dsh comes with four built-in presets, ranging from full to minimal capability from top to bottom:

Preset	Capabilities	Suitable for
Standard Mode	Fully-featured coding Agent: file editing, Shell, file & web search, skills, plan, goals, sub-agents, workflows	Daily default (Recommended)
PTC Mode	All capabilities of Standard Mode, but tools presented via Code Mode SDK, model uses TypeScript programs to compose multi-step operations	Users who prefer programmatic control
Minimal Mode	Only keeps two tools: persistent bash and file editing	Minimal environments, focused command running
Creator Mode	All Standard Mode capabilities, plus runtime checks, plugin experimentation, and creation guidance	Used to create custom presets

Standard Mode is the daily choice for most people and is the default preset. It is the "fully-featured coding Agent" possessing all the capabilities discussed in previous chapters.

How to Switch Presets

Settings → Agent Preset → Click the target preset. After switching:

• New sessions use the new preset.
• Existing sessions keep the preset they started with.

The top status area of the main interface also displays the preset used by the current session, e.g., Standard Mode.

Creating a Custom Preset

Built-in presets not enough? Use Creator Mode:

1. First switch to Creator Mode; it comes with creation guidance.
2. Adjust the agent's behavior and plugin combinations according to the guidance.
3. Save it as your own preset.

Custom presets are suitable for scenarios with special requirements for agent behavior. This is advanced play; just know this path exists for now.

6.4 Themes

You will learn Switch the interface theme, choosing Light, Dark, or Follow System, to make dsh pleasing to the eye.

Where to Set the Theme

In the General Settings tab of the settings panel, the Appearance section is the theme setting. Three options:

Option	Effect
Light	White background, dark text, bright and clean
Dark	Black background, light text, night-friendly
Follow System	Follows the operating system's light/dark setting; dark when the system is dark

Switching takes effect immediately, no restart needed.

How to Choose

Purely based on personal habit:

• Mostly daytime work: Light, clear text.
• Often code late at night: Dark, eye-friendly.
• System already in dark mode: Follow System, consistent across the entire platform.

Small Suggestion If unsure, just choose Follow System. It automatically matches your entire computer's light/dark style, the most hassle-free option.

Themes Only Affect the Interface

The theme is just the interface appearance; it does not affect any functionality. Conversations, tool calls, settings all work exactly the same whether in Light or Dark mode.

Part 7 · Advanced & FAQ

Graduation chapter: CLI play beyond the interface, security boundaries, a complete hands-on practice, plus answers to common questions.

7.1 CLI Mode

You will learn Get to know dsh's command-line play: one-shot runs, custom configurations, plugin management, usable even without the graphical interface.

Beyond the GUI, There's the Command Line

The entire article so far has talked about the Web UI, but dsh isn't just a graphical interface. The dsh command itself is a multi-mode launcher. Besides dsh web, there are several interesting modes.

Four Entry Modes

Command	What it does	Suitable for
dsh web	Starts the graphical interface (the protagonist of the whole article)	Daily interaction
dsh --profile headless "task"	Runs a task once, prints the result, and exits	Automation, scripts, CI
dsh --profile <name>	Starts with a specified configuration profile	Custom scenarios
dsh plugin --profile <name> <params>	Manages plugins for that profile	Plugin install/maintenance

headless: Finish a Task with One Command

The most interesting is the headless mode. It doesn't need an interface; one command finishes the task and exits:

dsh --profile headless "Summarize the structure of the project in the current directory"

After running, the agent's answer is printed directly in the terminal. Suitable for writing into scripts, scheduled tasks, CI pipelines. Think of it as dsh's "command-line version".

profile: Your Exclusive Configuration Profile

dsh uses profiles to manage different runtime configurations. Each profile is an independent set of plugin combinations and configurations:

• web and headless are built-in, auto-initialized on first use.
• Other profiles are created via the dsh plugin command.
• Each profile has its own plugins, patches, and configurations, not interfering with each other.

What's Needed to Run headless

Just like the graphical interface, it needs a model key. The headless mode reads it via environment variables:

export DEEPSEEK_API_KEY="your key"
dsh --profile headless "task"

7.2 Permission Presets and Sandbox

You will learn Dig one layer deeper into the permission mechanism from Section 4.4: understand the three tiers of the sandbox, how permission presets bundle them, and the actual boundaries on Windows.

Permission Presets: One Tier Manages Two Things

Section 4.4 covered permission modes. Now let's explain the mechanism behind it: each permission preset actually bundles two independent things:

1. Sandbox Mode: What the agent's commands can do on the file system.
2. Approval Strategy: Whether out-of-scope operations ask you or are directly denied.

A single tier on the interface is a combination of these two switches behind the scenes.

Three Tiers of the Sandbox

The sandbox only manages file system effects. Three tiers from loose to strict:

Mode	Allows what	Typical Use
danger-full-access	No restrictions, can touch anything	When global ops needed
workspace-write	Workspace directory + temp area writable	Daily work
read-only	Read-only, write prohibited	Look but don't touch

Note: The sandbox only manages file reads and writes. Network access and process visibility are not managed by the sandbox; those are separate mechanisms.

Two Tiers of Approval Strategy

• ask: Asks you for out-of-scope operations; allowance is only for this one time.
• never: Doesn't ask, directly denies. For unattended scenarios, rather fail than risk.

How Presets Combine

The permission selector on the interface is backed by these combinations:

Interface Tier	Sandbox	Approval
Read Only	read-only	ask
Workspace Write	workspace-write	ask
Full access	danger-full-access	never

See the pattern? The higher the tier, the looser the sandbox; Full access even turns off approval directly. This is why Section 4.4 emphasized using Full access with caution.

Sandbox Implementation on Different Systems

The sandbox's "guardrails" are implemented by operating system mechanisms:

• Linux: bwrap or Landlock
• macOS: Seatbelt
• Windows: ACL restricted tokens

The strength of guardrails varies across systems. Some boundaries (like hard links) might only achieve "partial restriction". For daily use, remember one thing: Read-only and writing within the workspace is the most common and safest combination.

Practical Advice

• Daily use Workspace Write (workspace-write + ask), the baseline config for getting work done.
• For read-only inquiries, switch to Read Only.
• Full access only when explicitly needed, switch back immediately after use.
• Only consider the never approval strategy for automation and unattended scenarios.

7.3 Complete Hands-On Practice

You will learn String together the knowledge from the entire article and walk through a complete hands-on process: from setting up the environment to having dsh complete a real project task.

The Hands-On Task

In this part, we complete a real small project task: Generate a README for an existing project. It uses the mainline capabilities of the entire article: workspace, session, tool calls, goals, review.

Task objective:

Analyze the project in the current workspace and generate a README.md containing a project introduction, main features, and usage instructions.

Step 1: Confirm the Environment

Before starting, confirm three things, all indispensable:

1. Environment: dsh is started, and the browser can open the interface (Section 0.2).
2. Model: The top status area shows an available model (Section 1.1).
3. Workspace: Your project workspace is already in the sidebar, and the input box is usable (Section 2.2).

Once all three are ready, begin.

Step 2: Create a New Session, Set a Goal

Click New Session, and first set a goal to prevent the agent from going off course:

Set goal: Generate README.md for the project in the current workspace, only do this one thing.

Step 3: Send the Task Instruction

Clearly state the task:

Analyze what this project does, then generate a README.md containing a project introduction, main features, and usage instructions. Read the project's key files first before writing.

Note the three key points in the instruction: what to do (generate README), where the output goes (README.md), how to do it (read key files first, then write). The more specific the instruction, the more controllable the result.

Step 4: Observe It Working

After sending, keep an eye on the tool call tree in the message stream (Section 3.2):

• Pwsh / Bash: List directories, view files.
• Glob: Find README, package.json, source code entry points.
• Read: Read key files to understand the project.
• Think: Organize the structure of the README.

Throughout the process, you might see it repeatedly "read a bit, think a bit, read a bit more". This is normal; it's understanding your project.

Step 5: Review the Result

After the agent finishes, a draft of the README appears in the chat area, and a README.md file is added to the workspace. Don't rush to wrap up; do two things:

1. Check the file: Open README.md to inspect the content. Are the introduction, features, and usage instructions all in place?
2. Request modifications: If not satisfied, just say so, e.g., "Write the usage instructions in more detail, add an installation step". The agent will modify it.

Step 6: Wrap Up

Once satisfied, this task is complete. You can:

• Do a quick summary: "Summarize the process of this task" (and by the way, check the Trace View, covered in Section 4.10).
• Archive the session (Section 5.1) to keep the sidebar clean.
• Open a new session for the next task.

What This Practice Used

Phase	Capability Used	Chapter
Environment Check	Startup, Model, Workspace	Part 0-2
Prevent Deviation	Goal	4.5
Command Work	Session & Instruction	Part 3
Observe Process	Tool Call Tree	3.2
Security Boundary	Permission Mode	4.4
Wrap-up Management	Archive, Trace	5.1, 4.10

The main thread of a tutorial, all used in this small task.

Extension: Advanced Practice Directions

After completing this small task, you can continue in these directions:

• Plan Mode for large overhauls (Section 4.6): Have the agent propose a plan before refactoring.
• Sub-agents for parallel research (Section 4.7): Search in multiple directions simultaneously.
• Background tasks for long jobs (Section 4.8): Builds, batch processing without blocking the conversation.

7.4 Frequently Asked Questions

You will learn Consolidate the questions that appeared throughout the article into a quick reference table. Come here first when you encounter a problem.

Installation and Startup

Q: npx download is very slow or fails?

Check your network and proxy. You can temporarily switch to a domestic npm mirror:

npm config set registry https://registry.npmmirror.com

Q: What if the port is occupied?

Start with a different port:

npx @deepseek-ai/dsh web --port 8080

Then visit http://127.0.0.1:8080/.

Q: node -v version is too old?

dsh requires Node.js 22 or above. Go to the official website, download the latest LTS, and install over it.

Q: Browser can't open the interface?

Go by the address printed in the terminal. Confirm the port matches, the terminal has no errors, then refresh once.

Configuring Models

Q: After saving, the model is unavailable, prompts invalid key?

The key might not have been copied completely (the whole string starting with sk-), or it hasn't taken effect yet after creation. Try creating a new one on the DeepSeek platform.

Q: Prompts insufficient balance?

DeepSeek is pay-as-you-go. New accounts might need to top up. Check the billing page on the platform.

Q: Want to use another model?

Settings → Model → Add Provider (over 20 built-in), or Add Custom Provider to connect to an OpenAI-compatible service (Section 1.2).

Q: What if the API key is leaked?

Revoke and recreate it on the DeepSeek platform; the old key becomes invalid immediately. Don't screenshot the key and post it in groups or commit it to git.

Workspace and Sessions

Q: Added a workspace but it's not in the sidebar?

Confirm you selected a folder, not a file. The same directory can only be added once.

Q: Will files be lost if I delete a workspace?

No. Deleting only removes the grouping record; files and sessions are preserved.

Q: Too many sessions, can't find one?

Use the sidebar search box to search by title or content. Archive unused sessions (Section 5.1).

Q: Want to go back to yesterday's conversation and continue?

Click the session row in the sidebar; the history loads completely, and you can continue chatting directly.

Running and Results

Q: The agent went off course?

Set a goal first (Section 4.5) before sending the task. If it deviates, directly say "Stop, get back to the goal". You can also use Plan Mode to review the plan first (Section 4.6).

Q: The agent is running for too long?

Check the tool call tree to see which step it's stuck on. For long tasks, put them in the background (Section 4.8), or limit the scope in your instruction.

Q: Not satisfied with the agent's answer?

First, switch to a stronger model (Section 4.1) or increase the reasoning level. Then check if your instruction was specific enough. Vague instructions inevitably lead to vague results.

Q: The agent keeps popping up approval requests?

This means it wants to touch something outside the workspace. Look clearly at the operation content before deciding: allow what should be allowed, deny what shouldn't (Section 4.4).

Interface and Views

Q: What's the difference between Chat View and Trace View?

Chat View is the human-readable version; Trace View is the raw turn-by-turn record (USER/CONTEXT/ASSISTANT/TOOL). Use Trace View for troubleshooting details (Section 4.10).

Q: The interface is in English, want to switch to Chinese?

Settings → General Settings → Language → Chinese.

Q: The interface is too bright/dark?

Settings → General Settings → Appearance, choose Light/Dark/Follow System (Section 6.4).

Advanced

Q: How to run tasks unattended?

Use headless mode (Section 7.1):

export DEEPSEEK_API_KEY="your key"
dsh --profile headless "task"

Q: Want to restrict the agent's permissions more strictly?

Switch to Read Only mode (read-only), or stay on Workspace Write and deny out-of-scope operations during approval (Section 7.2).

Q: Want to add new capabilities to dsh?

Install plugins or skills. Plugins are viewed in Settings → Plugins; skills are invoked in sessions using / (Sections 4.3, 6.2). Writing your own plugins is advanced development; the official documentation has dedicated tutorials.

Conclusion

Here, this tutorial is fully covered. Let's review the path you've traveled:

• Part 0: Got to know dsh, set up the environment, understood the interface.
• Part 1-2: Configured the model, defined the workspace.
• Part 3: Sent the first instruction, understood tool calls.
• Part 4: Unlocked all advanced features in the session.
• Part 5-6: Managed sessions, tuned it to your own shape.
• Part 7: Learned about CLI, security mechanisms, completed a hands-on practice.

From "what is dsh" to "using dsh to complete a real task", you've made the leap from zero to one. Next, go to your projects and let the agent help you work. If you encounter problems, come back and flip through this tutorial.

---

Written at the End

About the Author

Wan Shaoye (Wanshao): Huawei HDE (HUAWEI Developer Experts), Huawei Cloud HCDE (Huawei Cloud Developer Experts), 51CTO HarmonyOS Developer Community Core Expert, HarmonyOS Application Developer Advanced Certification, HarmonyOS Application Development Training Instructor, ten years of full-stack internet development experience, continuously outputting practical content on AI and the HarmonyOS ecosystem.

See you in the next article.