Quick Answer
DeepSeek Harness (dsh) isn't only the Web UI at http://127.0.0.1:3080. It also supports a headless coding agent: no browser, just DEEPSEEK_API_KEY via env vars or .env, running an agent in the background that reads files, executes commands, and edits code automatically.
This fits CI auto-fix, scheduled jobs, and scripted bulk refactors — anything where no human is watching and the agent should run to completion.
What Headless Mode Needs
Headless mode only needs a working model backend. Minimal config:
export DEEPSEEK_API_KEY="sk-your-key"
export DEEPSEEK_BASE_URL="https://api.moyi-api.com/v1"
The key can also go in a .env at the repo root (add it to .gitignore):
DEEPSEEK_API_KEY=sk-your-key
DEEPSEEK_BASE_URL can't go in .env: dsh 0.2.x refuses to start if it does, because only the environment that launches dsh may set it, so export it. We tested this with dsh 0.2.1-rc.3 on November 2, 2026: with the key in the repo-root .env and DEEPSEEK_BASE_URL exported, requests reached the Moyi API gateway.
Once configured, the headless agent calls tools exactly like the Web UI agent — just without a visual interface, returning output via stdout or a report file.
With these two variables, dsh 0.2.x keeps its built-in DeepSeek provider: the default model is deepseek-flash, and DEEPSEEK_DEFAULT_MODEL is ignored. To make the headless agent default to deepseek-v4-pro or use other Moyi API models, add Moyi API as a provider — see Connect DeepSeek Harness to Moyi API.
One-Shot Run: A Task That Finishes and Exits
The most common headless use is a one-shot run — give a task, the agent runs to completion (or hits the budget cap), then exits:
dsh headless "Fix the N+1 query in src/services/reporting.py and make the related tests pass"
The agent reads files → understands → edits → runs tests → fixes from results, until done. This run-to-completion model suits CI steps perfectly: hand it deterministic jobs like "fix lint errors" or "add tests" and it's faster than doing them by hand.
ACP Automation Server: Persistent Headless Sessions
The more advanced path is the ACP automation server — it serves fresh agent sessions over JSON-RPC stdio, also requiring DEEPSEEK_API_KEY. This suits repeated, scripted agent invocations where you don't want to spawn a process each time.
Choosing between the two:
| Form | Fits | Trait |
|---|---|---|
| One-shot run | CI, scheduled jobs | Run-to-completion, simple |
| ACP server | Long-lived integration, scripted calls | Persistent, session reuse |
Common Pitfalls
The headless agent won't start / says no API key?
Confirm DEEPSEEK_API_KEY is exported in the same shell, or the .env is at the repo root and loaded. Verify with echo $DEEPSEEK_API_KEY first.
How do I know a headless task finished?
Watch the exit code and stdout. One-shot runs exit on completion; ACP sessions emit a clear session-end event.
Can a background run get out of control?
Yes — if the task boundary is vague. Headless mode has no UI to interrupt in real time, so: give a clear task boundary, restrict the working directory, and set a budget cap where possible. Don't let it roam a large repo freely.
Does headless use the same tools as the Web UI?
Yes. Tools come from the same plugins/presets; the only difference is the visual interface. Headless output returns via stdout or a report.
Can I schedule it?
Yes. Wrap the headless command in cron / launchd / CI with .env configured, and you get persistent automation like "auto-fix lint nightly" or "weekly refactor."
To stand up a background coding agent, get a key at Moyi API, configure the env vars, and wire dsh's headless command into your scripts or CI.