DeepSeek Harness
DeepSeek Harness CLI and Headless Mode: Profiles, Flags, and Automation
Learn how the dsh launcher separates profile flags from app arguments and how headless mode runs one persisted task without a server.
What you will learn
- Launcher flags and profile app arguments have separate parsing boundaries.
- Headless mode prints one persisted task result and exits.
- Dump the composed config before automating a profile.
Before you start
- Basic HTTP and API knowledge
Leave with a concrete implementation checklist and a testable starting point.
Key takeaways
- Launcher flags and profile app arguments have separate parsing boundaries.
- Headless mode prints one persisted task result and exits.
- Dump the composed config before automating a profile.
Understand the launcher boundary
The CLI README describes dsh as a product launcher for profiles. Launcher flags come first; the first token it does not recognize starts the selected app's arguments, which prevents web-specific options from being mistaken for launcher options.
`dsh web` is an alias for the web profile, while `dsh --profile headless "job"` runs one fresh persisted session, prints the final answer, and exits. This distinction matters when you move from an interactive UI to automation.
Inspect before booting
Use `--dump-default-config` and `--dump-config` to inspect the composed tree without booting it. The output lets you verify bundle order, profile patches, home patches, and command-line overlays before a process owns ports or workspaces.
The profile directory contains a package.json with out-of-tree plugin dependencies, a dsh.profile manifest with ordered bundles, and the user's cordis.patch.yml. A patch that matches an id replaces the whole config row.
Automate carefully
Headless execution is useful for one-shot jobs and CI experiments, but it still creates durable session state. Give each independent job a clear session identity and isolate the workspace so a command cannot modify an unintended checkout.
Production runs require built package and frontend artifacts. The source workflow therefore runs `pnpm run build` separately, then uses `pnpm dsh` to execute the TypeScript entry with forwarded arguments.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Choose web for an interactive server or headless for a one-shot job.
- 2
Dump the profile config and verify patch precedence.
- 3
Isolate workspace and session identity for automation.
- 4
Build artifacts before using `pnpm dsh` from source.
Copy-ready example
dsh --help
dsh web --port 8080
dsh --profile headless "summarize this workspace"
dsh --profile web --dump-configFrequently asked questions
What does headless mode do?
It runs a fresh persisted session, prints the final answer, and exits without starting the Web UI server.
Sources
- DeepSeek Harness CLI READMESource checked 2026-08-27