DeepSeek Harness Quickstart: 4 Gates to First Success
A DeepSeek Harness quickstart is not four clicks. It is four gates that open in order: the process prints an address, the model selector works, the workspace unlocks the message box, and the first task returns a result. Each gate has one observable pass criterion. If you treat the four steps as a checklist of clicks, an earlier failure will look like a later problem.
DeepSeek Harness: Why the quickstart works as gates
A gate is a dependency, not a timestamp. The later step often appears to misbehave when the earlier step never finished. A model that is not configured can still leave an enabled input box, and a page that looks fine can still have no workspace selected. (source)
The official order is: start the Web UI, open Settings → Models and save a key, add and select a workspace, then start a session and send a task (source). That order is also the dependency order: the model decides whether a request can leave, the workspace decides what the agent can touch, and the task exercises both.
The four gates are not an official term. They are a way to rewrite the official steps into four states you can judge. The official page says what to do; the gates say what “done” looks like.
Keep this separate from installation acceptance. Installation acceptance checks binaries, ports, and plugin directories. The four gates check whether you can finish one real task in the browser. Passing one does not prove the other.
DeepSeek Harness: The four gates and their criteria
Each gate has one criterion. Do not accept “the page opened” or “the button clicked” as proof. This table is the backbone of the article (source):
| Gate | Pass criterion | Smallest check | Look here first |
|---|---|---|---|
| 1 Startup | The terminal prints an address and the process stays alive | Read the last lines in the startup terminal | Terminal error, port conflict |
| 2 Model | The selector works and the next request returns | Save a key, send one short task | Key, provider, model list |
| 3 Workspace | The input box unlocks after a directory is selected | Open Select Workspace and pick the project | Permissions, actual selection |
| 4 Task | A session returns a result and shows what it did | Send a read-only task | Approval wait, model error, exited process |
Use the table forward: finish a step, check its criterion, then move on. Use it backward when a task produces nothing: start from gate four, check whether the input was available, then whether the model worked, then whether the process is still alive.
The third column is a smallest check, not a full test. It should take seconds: read one terminal line, send one short message, select one directory. A complex first task mixes model, workspace, approval, and plugin variables into one failure.
The criteria are deliberately observable because the first run is mostly a discrimination problem. Logs, errors, and UI states can appear together. “Saved successfully” is a UI response; “the request returned” is the model gate. “The directory is in the list” is a list state; “the input unlocked” is the workspace gate.
DeepSeek Harness: Startup and model: the first two gates
Gate one is the printed address, not the rendered page. After you start dsh, the process prints the Web UI address; the gate opens when the address appears and the process keeps running (source). If there is no address, do not refresh yet: check whether the process exited, hit a port conflict, or is still starting.
Gate two is a request that returns, not a filled-in key field. Open Settings → Models, enter a DeepSeek API key, and save. The official docs say model changes take effect on the next request and do not need a server restart (source). Send one short task to prove it.
A three-step check avoids most false positives:
- Selector — at least one model is visible and a non-empty model is selected.
- Short task — ask for one sentence about the current project.
- Return — a normal reply opens the gate; credential, unknown-model, or connection errors keep it closed.
Saving only proves the configuration was written. It does not prove the key or endpoint works. Those failures appear at request time, which is why the model gate needs both a saved setting and a returned request.
Do not restart the process to “make it apply.” The official behavior is next-request activation. Restarting only destroys the first observation you need.
If you use a third-party provider or a custom model API, the gate is the same but the checks grow: provider ID, base URL, protocol, and model ID must match. See DeepSeek Harness model providers.
DeepSeek Harness: Workspace and task: the last two gates
Gate three is an unlocked input box, not a directory that merely appears in a list. A fresh Web UI selects no workspace. The dsh process treats its startup directory as the default filesystem location, but the UI still needs you to add that directory and select it; the message box is unavailable until then (source).
The startup directory and the workspace are related but not identical. The first is where the process started; the second is this session’s operating boundary. For a first run, use the startup directory to reduce variables, then add more workspaces later. See How to choose a DeepSeek Harness workspace.
Gate four is a returned task that shows its work. The official example is “Summarize this repository and identify its main packages.” The agent can read and edit workspace files, run commands, delegate work, and maintain a plan; operations that need approval under the current policy ask you first (source).
When the task returns, check three things:
- What it read — does the answer mention files or packages in the selected directory?
- What it did — did it read, list, or run something, rather than only produce generic prose?
- Where it stopped — did it wait on approval, or fail with an error you can trace to the model gate?
A read-only first task separates “can the model work?” from “did it edit correctly?” Confirm the first before asking for the second. See How to write the first DeepSeek Harness task.
DeepSeek Harness: Three common misreads
Most first-run mistakes are not clicking errors; they are misclassifying one stop as another. These three cover most of them (source):
- A blank page is not a model problem. It belongs to startup and access. Check the terminal and the printed address first, then see DeepSeek Harness Web UI blank or unreachable.
- A grey input box is not a browser problem. The usual cause is no selected workspace. Check Select Workspace before clearing cache.
- An approval wait is not a hang. The task is waiting for your decision. Read the prompt, then allow, reject, or cancel; do not kill the process.
All three share the same mistake: treating a later gate as the current one. The value of gate thinking is knowing where to step back to.
DeepSeek Harness: The minimum usable state after all four gates
Passing four gates does not mean “fully configured”; it means you have a repeatable minimum loop. The loop can start, send a request, touch the selected directory, and return a result. That is enough to move on, but not enough to assume everything is correct. (source)
The minimum usable state has four parts:
- Stable startup — the terminal prints an address and survives normal operations.
- Usable model — a model is selected and a request returns.
- Effective workspace — the agent can read files in the selected directory.
- Closed task loop — a first task completes with approval, execution, and a result visible.
Fix the missing part before adding complexity. Do not use a harder task to “test whether it works”; a harder task only adds variables.
To extend the Web UI, start with the plugin market: install DSH Plugin Hub, then browse and install community plugins from Settings → Plugin Market. If a plugin does not take effect, check the profile and the page refresh, not the four gates.
The detailed branches follow in this batch: saved keys that stay hidden, a disabled input box, model list refresh, model switching, first approval, and stuck-task triage.
FAQ
The DeepSeek Harness startup step succeeds when the process prints a Web UI address and keeps running. Check the terminal first; refreshing the browser cannot make a missing address appear.
DeepSeek Harness applies model changes on the next request. Saving writes the configuration, but only a request that returns proves the model gate is actually open.
A fresh DeepSeek Harness Web UI selects no workspace. The dsh process uses its startup directory as the default filesystem location, but the UI still needs you to add and select a workspace before the box unlocks.
In DeepSeek Harness, it means the model, workspace, and execution path worked once. DeepSeek Harness plugins, approval policy, updates, and long-term configuration still need their own checks.
Related Terms
- four gates
- The four gates are the DeepSeek Harness first-run checkpoints: startup, model, workspace, and task; a later gate can look broken when an earlier one is not open.— DeepSeek Harness docs - Using the Web UI
- pass criterion
- A pass criterion is the observable evidence that a DeepSeek Harness step is complete, such as a printed address, a usable selector, an unlocked input, or a returned result.— DeepSeek Harness docs - Using the Web UI
- workspace
- A workspace is the filesystem location a DeepSeek Harness agent may read and edit; it must be added and selected in the Web UI before the message box unlocks.— DeepSeek Harness docs - Using the Web UI
- model routing
- Model routing is the DeepSeek Harness configuration that decides which provider and model handle a request; changes apply on the next request without a server restart.— DeepSeek Harness docs - Configuring models
Sources
- DeepSeek Harness docs - Using the Web UI· deepseek-harness
- DeepSeek Harness docs - Configuring models· deepseek-harness
- DeepSeek Harness README - Run· deepseek-ai