Backend

DeepSeek Harness: Local AI Agent Writes a Working CLI Tool in 11 Steps, 3 Tests Green

By 废柴程序员_熊熊 · Nov 3, 2026

Read original on juejin.cn ↗ Google Translate ↗ Alt translation

The tool proves a local, self-hosted agent can do meaningful coding work with data kept on your machine, but its preview label, Node 22 requirement, and the split credential paths between Web UI and headless mode mean you should evaluate it for personal or CI use, not production workflows.

Summary

DeepSeek Harness is now officially open source under MIT, written in TypeScript, and built on Cordis with an everything-is-a-plugin architecture. It is not a model; it is the shell that orchestrates file I/O, command execution, task planning, sessions, permissions, and plugins. The default web UI listens on 127.0.0.1:3080, requires a one-time token from startup output, and stores API keys write-only in ~/.dsh/.credentials.yaml (600 perms).

The installation has two traps that are absent from the README. Node 20 will install fine but crash on first run with an obscure parseEnv error; Node 22 or newer is required. npm 11 blocks install scripts by default, so node-pty and koffi never compile; you must pass --allow-scripts with the exact package list. The default workspace is ~/Documents/deepseek-harness/default-workspace, not the launch directory.

In a real coding test, the agent produced a 400-line zero-dependency CLI tool, 149 lines of tests, and an 83-line README in 11 steps, consuming 244K tokens with a 95% cache hit. It self-discovered and fixed a bug where width normalization assumed a single table. Scheduled tasks, sub-agents, MCP overlays, and custom model providers are built-in. Headless mode runs a single prompt in about 4 seconds, but it requires the DEEPSEEK_API_KEY environment variable and will not read the key you saved through the Web UI.

Takeaways

— DeepSeek Harness requires Node 22 or newer; Node 20 installs but crashes on first run with a parseEnv syntax error.

— npm 11 blocks install scripts by default; the global install must include --allow-scripts with packages node-pty, koffi, and others or the terminal feature stays empty.

— The web UI listens only on 127.0.0.1:3080 and returns 401 without the startup token; SSH port forwarding is the intended way to access it from another machine.

— API keys are write-only: saved once, the settings page never reveals them, and they persist in ~/.dsh/.credentials.yaml with 600 permissions.

— The default workspace is ~/Documents/deepseek-harness/default-workspace, independent of where the service was launched.

— In a real test, the agent wrote a Markdown-to-CSV CLI tool in 11 steps: 5 files, +678 lines, 244K tokens, 95% cache hit, 212 tok/s, and 3 tests passing in 328 ms.

— The agent caught its own bug involving width normalization across multiple tables and fixed it without prompting.

— Access modes include read-only, workspace-only modification (default), and full access; the default confines file and command operations to the current workspace.

— Scheduled tasks use RFC 5545 recurrence and a built-in scheduler, but the minimum interval between deliveries is 1 minute.

— Headless mode ignores the Web UI's stored credentials; you must export DEEPSEEK_API_KEY in the launching environment or it returns MISSING_CREDENTIAL.

— A headless task that counted lines in workspace files completed in 4.019 seconds, including reads, command execution, and answer generation.

— Sub-agent configuration supports per-agent model selection, letting cheap models handle file reads and commands while a strong model decomposes tasks.

Conclusions

The 95% cache hit rate in the benchmark run is the strongest signal about cost behavior: most of those 244K tokens were re-read context, not new generation, so consecutive jobs on the same repository may become dramatically cheaper after the first pass.

The write-only API key design is noticeably more careful than typical agent tools that echo keys back to the frontend or store them in plain config files, and it sets a security baseline worth copying.

The credential mismatch between Web UI and headless mode is the kind of rough edge you expect from a preview version: the plugin architecture centralizes features but not the credentials store, which can quietly bite CI users.

Defaulting to workspace-only modification makes sense for a tool that runs arbitrary commands, and the trade-off against full access is well communicated in the UI, but the preview label still undercuts production confidence.

Concepts & terms

Everything-is-a-plugin architecture

A design where every component of the agent—model providers, tools, terminal, UI panels, scheduled tasks—is implemented as a plugin. In DeepSeek Harness this is built on Cordis, making the plugin page look like an app store rather than a fixed set of toggles.

Cordis

A plugin-oriented framework for building modular applications; DeepSeek Harness uses it as the underlying architecture for its everything-is-a-plugin model. Config changes are applied as ordered patch layers, which is why editing one config file can swap a model provider.

MCP (Model Context Protocol)

An open protocol that lets agents connect external tools and data sources. In Harness, MCP servers are mounted via a --patch overlay, and their tools appear in sessions as mcp__<service>__<tool>. The official repo ships memory-system configs but leaves them disabled to avoid endorsing third-party services.

RFC 5545 recurrence rule

A standard format for describing repeating events, used by Harness's built-in scheduler. When you ask for a daily reminder, it creates a task with an RRULE that specifies frequency and interval, and the scheduler delivers the instruction to a session at the scheduled times.

Source: juejin.cn ↗ Google Translate ↗ Backup ↗