From DeepSeek Harness Web UI to Python SDK: What to Pass
The biggest mistake when moving a first task from the DeepSeek Harness Web UI to the Python SDK is assuming the configuration travels with it. The SDK and its examples never silently read ~/.dsh; the dsh_home you pass is the only source, and it stores the generated sdk-minimal profile, installed plugins, and sessions/ logs (source). Migration is not copying a prompt; it is passing three values explicitly.
DeepSeek Harness: Separate profile, home, and workspace
Both sides have a profile, a home, and a workspace, but they are not the same objects. Align the concepts before migrating (source):
| Concept | Web UI | Python SDK |
|---|---|---|
| Profile | web profile, UI and plugins | sdk-minimal or sdk |
| Home | default $DSH_HOME | the dsh_home you pass |
| Workspace | the directory selected in the UI | the cwd / workspace you pass |
The table shows why Web configuration does not appear in the SDK. The SDK uses another home, another profile, and an explicit workspace.
This is isolation, not a defect. SDK runs are often automation, tests, or one-off jobs, and they need a clean, reproducible home. If the SDK read your daily ~/.dsh, a test could pollute real configuration.
DeepSeek Harness: Three explicit values
Migration comes down to workspace, dsh_home, and session_id. The official example runs minimal.py --workspace ... --dsh-home ... --session-id ... "task" (source).
What each does:
- workspace — the directory the agent may read and write. The Web UI selects it; the SDK requires an absolute path.
- dsh_home — where profiles, plugins, credentials, and session logs live. Without it, there is no isolated source.
- session_id — the session identity. Use a new id for independent work; reuse it only to continue a conversation.
In Python, these map to DeepSeekHarness(cwd=..., dsh_home=..., profile=...) and harness.run(..., session_id=...). Parameter names can vary by version; the three values do not.
Use absolute paths for both workspace and dsh_home. The SDK may start in a different working directory than your shell, so a relative path can point somewhere unexpected.
Session id has a reuse rule: a new id for independent work, and harness, home, and id together only when continuing the same persistent conversation. Reusing an id in a new home creates a same-named session with different content, which is hard to diagnose.
DeepSeek Harness: Where credentials come from
The SDK does not inherit the Web UI credential state; credentials come from the environment or the home you pass. The official example exports DEEPSEEK_API_KEY, and optionally DEEPSEEK_BASE_URL for a compatible proxy (source).
Two sources:
- Environment — good for one-off runs, CI, and containers; nothing is written into the home.
- SDK home — good for persistent providers and credential references; the home stores the profile and credentials.
Do not expect a key saved in the Web UI to appear in the SDK. The Web UI key lives in its home; the SDK uses another home unless you point it at the same one.
If the SDK reports a missing credential, check the environment first, then the home. Re-saving in the Web UI will not cross homes.
DeepSeek Harness: What sdk-minimal leaves out
sdk-minimal is deliberately small; do not expect Web-level capability. It does not apply dsh-base, so it has no text-file tools, settings, managed credentials, OTel telemetry, web tools, subagents, or local instruction discovery; it keeps persistent bash or pwsh, read_image, and working_directory (source).
Three consequences:
- No
str_replace_editor— use shell edits or add an editor patch explicitly. - No Team or subagents — choose the standard
sdkprofile and a team patch. - Fixed
danger-full-access— the persistent shell can modify any path the runtime sees; use a disposable checkout or container.
sdk-minimal fits “run one task, get a result.” For Web-like capability, choose sdk and add plugins and patches instead of forcing them into sdk-minimal.
DeepSeek Harness: The same task on both sides
The same task is written differently, but the goal can match. For “summarize the main packages” (source):
| Step | Web UI | Python SDK |
|---|---|---|
| Workspace | select a directory | pass an absolute cwd / workspace |
| Model | choose in Settings | pass provider and model, or rely on home |
| Credential | save in Settings | environment or home |
| Session | create in the UI | pass session_id |
| Run | send in the box | harness.run(prompt, session_id=...) |
The Web UI stores state in the interface; the SDK stores it in arguments and the home. Migration translates UI state into explicit values.
Translate first, then run. Do not edit while running. SDK errors are usually direct, but they only point in the right direction when the three values are correct.
DeepSeek Harness: Verify output, session log, and profile
“It printed something” is not enough; three places must agree. Three checks (source):
- Output —
result.final_responsecontains a result covering the object and output you asked for. - Session log — the
sessions/directory under yourdsh_homecontains a JSONL for the id. - Profile — the home contains the generated
sdk-minimalprofile and the expected plugins.
All three mean workspace, home, and session id are correct. Output right but log elsewhere usually means the wrong home. Log right but output wrong sends you back to the prompt and model.
If the SDK cannot find expected config, check which home it used before blaming plugins. Installation and API basics are in How to call DeepSeek Harness with Python; the home-isolation failure is in DeepSeek Harness Python SDK cannot read ~/.dsh.
The last rule: run the task in the Web UI first, then move the sentence that worked into the SDK. A task that fails in the Web UI will not succeed in the SDK; the SDK changes the entry point, not the missing workspace, model, or credential.
Three explicit values, one isolated home, one minimal profile: migration is translation, not magic.
FAQ
DeepSeek Harness does not work that way. The DeepSeek Harness SDK and its examples never silently read ~/.dsh, and Web UI state is not inherited. Pass workspace, dsh_home, and session_id explicitly.
DeepSeek Harness uses only the home you pass. That home stores the generated sdk-minimal profile, installed plugins, and sessions JSONL; without it, there is no isolated config or credential source.
DeepSeek Harness does not work that way. DeepSeek Harness sdk-minimal does not apply dsh-base, so it has no text-file tools, settings, managed credentials, web tools, or subagents, only basics such as bash or pwsh, read_image, and working_directory.
DeepSeek Harness does not share state directly. The DeepSeek Harness web app is a separate CLI application and cannot serve a Python SDK client; each side has its own profile and home. Reuse harness, home, and session id only to continue the same conversation.
Related Terms
- dsh_home
- dsh_home is an isolated DeepSeek Harness home for profiles, plugins, credentials, settings, and session logs; the SDK uses only the home you pass.— DeepSeek Harness docs - Python SDK
- sdk-minimal
- sdk-minimal is the minimal DeepSeek Harness Python SDK profile; it skips dsh-base and keeps the SDK protocol, model adapter, local execution, and persistence.— DeepSeek Harness docs - Python SDK
- workspace
- A workspace is the filesystem location a DeepSeek Harness session may read and write; in the SDK it must be passed explicitly, not inherited from the Web UI.— DeepSeek Harness docs - Python SDK
- session_id
- A session_id identifies a DeepSeek Harness session; use a new id for independent work and reuse it only to continue the same conversation.— DeepSeek Harness docs - Python SDK
Sources
- DeepSeek Harness docs - Python SDK· deepseek-harness
- DeepSeek Harness reference - Python SDK· deepseek-ai