DeepSeek Harness Headless Mode
The built-in headless profile runs one DSH task from the command line, prints the final answer and exits without starting the Web UI or a listening server.
On this page
Can DeepSeek Harness run without the Web UI?
Yes. DSH ships a built-in headless profile for one-shot command-line tasks. It creates a fresh persisted agent session, runs one task, prints the final assistant answer and exits.
The headless profile opens no browser and no listening port, which makes it suitable for scripts, CI steps, batch jobs and terminal-only automation.
Run a DeepSeek Harness headless task
npx @deepseek-ai/dsh --profile headless "run the tests"The quoted text is the single task for that invocation. Replace it with the job you want the agent to perform.
npx @deepseek-ai/dsh --profile headless "summarize this repository"Use --help to inspect the current command behavior without running a task.
What headless mode outputs
stdout
The final non-empty assistant answer is written to standard output after the run finishes.
stderr
Provider reasoning deltas can be written to standard error; errors are also reported there.
Exit code 0
The final turn completed successfully.
Exit code 1
The run aborted, errored or did not produce a completed final turn.
Because the process exits when the task is done, a successful invocation does not leave a Web server or background agent waiting for another message.
Use DSH headless in scripts or CI
The process-level exit code is the useful automation boundary. A shell or CI runner can treat zero as completion and a non-zero exit as failure.
npx @deepseek-ai/dsh --profile headless "review the failing tests"
status=$?
if [ "$status" -ne 0 ]; then
echo "DSH task failed" >&2
exit "$status"
fiReasoning can be written to stderr. CI systems often retain stderr, so treat those logs as potentially sensitive model output and control who can read them.
Current headless-mode limits
- One task per invocation. The process exits after that task; there is no interactive follow-up prompt.
- The profile runs through the DSH launcher and relies on the launcher-owned exit mechanism.
- Only reasoning and the final assistant answer are printed; intermediate tool output is not streamed as a general CLI transcript.
- There is no pre-token heartbeat before the provider emits output, so a slow first token can look quiet.
Headless mode vs the DSH Web UI
Use headless when
You need one automated task, a shell-friendly result, an exit code, CI integration or a terminal-only job.
Use the Web UI when
You need an interactive multi-turn session, visible approvals, browsing through sessions or a graphical workflow.
DeepSeek Harness official dsh-headless README. DSH remains in developer preview, so CLI behavior can change between releases.