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-teamo-your-key"
export DEEPSEEK_BASE_URL="https://api.teamorouter.com/v1"
Or in a .env at the repo root (add it to .gitignore):
DEEPSEEK_API_KEY=sk-teamo-your-key
DEEPSEEK_BASE_URL=https://api.teamorouter.com/v1
DEEPSEEK_DEFAULT_MODEL=deepseek-v4-pro-free
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.
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:
# illustrative: feed a task to the headless agent
dsh run "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 |
Run the Headless Agent on the Free Tier
Headless agents pair well with the free tier, since run-to-completion tasks have predictable request counts:
export DEEPSEEK_DEFAULT_MODEL="deepseek-v4-pro-free" # 200/day
A single "fix bug + run tests" task burns roughly 10–20 requests (read files, edit, run tests, fix round-trips). At 200/day that's 5–10 such tasks — enough for personal automation. For volume, switch to paid deepseek-v4-pro (no account limit, flat $1.74/$3.48).
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 TeamoRouter, configure the env vars, and wire dsh's headless command into your scripts or CI.