DeepSeek Harness Hands-On: Build Your Own Coding Agent for Free

DeepSeek Harness: The Model Is the Brain, Harness Is the Shell

DeepSeek recently open-sourced a project called DeepSeek Harness, which shot past 190,000 GitHub stars in a short time and has been dubbed the "free alternative to Claude Code" by many developers. One developer didn't stop at reading the docs — they walked through the full installation, configuration, and hands-on testing process to see whether it can genuinely power a coding Agent of your own.

The key to understanding this project lies in distinguishing two concepts: the model and the Harness. The model is the brain; everything surrounding that brain — context, tools, plugins, MCP servers, permissions, memory — belongs to the Harness. The core insight is this: Claude Code is also a Harness, but one where all the internal decisions have been made for you and locked away. DeepSeek Harness exposes all of those same decisions and lets you intervene at runtime.

What does that mean in practice? In a typical coding Agent, pull out one component and it breaks — lose a dependency mid-task and it crashes too (unless you hard-coded a Plan B in advance). In DeepSeek Harness, every component declares its own dependencies, and every change made at runtime retains an "undo" capability. Nothing is hard-coded, so nothing requires a full restart.

The word "Harness" in software engineering originally referred to a test framework or driver shell — a scaffolding layer that wraps core logic to provide a runtime environment, tool integration, and state management. In the AI Agent context, a Harness is responsible for: deciding what context the model can see, which tools it can call, how errors and retries are handled, and how state is saved and restored. Products like Claude Code, Cursor, and Codex are essentially Harnesses pre-designed by their respective vendors, with the internal decisions encapsulated and hidden. DeepSeek Harness differs by making this layer fully open and programmable — which is also why it can connect to any model, not just DeepSeek's own API.

Installation & Configuration: The Model Is a Plugin Too, and Costs Can Drop to Zero

Installation is straightforward. Copy the install command from the official site or GitHub repo, paste it into your terminal, and hit Enter. The whole process takes about five minutes. Once complete, a local web app dashboard opens automatically and prompts you to enter a DeepSeek API Key on first load.

Here's the notable part: you don't actually need a DeepSeek key. You can click "Configure Later" and connect any model you want. In the settings under the Models page, you can add a Provider — for instance, a GLM subscription at $10/month. Once the connection turns green, you're good to go.

This reflects the project's core design philosophy: the model itself is a plugin. The fact that DeepSeek built this Harness doesn't lock you into their paid API. If you want to run it at truly zero cost, you can add a custom Provider and point it to a locally deployed model (via Ollama, for example) using its Base URL and API Key.

That said, there's an honest caveat worth noting: free hosted models all come with rate limits. Google's free Gemini tier can be connected, but they've stopped publishing quota details. The only truly unlimited free path is running model weights locally on your own machine — if your GPU can handle it, Ollama offers a one-click installation with no metering whatsoever.

Ollama is a local LLM runtime that lets developers download and run open-source model weights (such as Llama 3, Mistral, Qwen, etc.) on their own machine with a single command, exposing a local interface compatible with the OpenAI API format (defaulting to http://localhost:11434). Because it runs entirely locally, there are no network requests, no token billing, and no privacy risks. DeepSeek Harness supports custom Provider Base URLs, so simply entering Ollama's local address is enough to create a fully zero-cost, zero-network-dependency coding Agent loop. The bottleneck is local GPU VRAM: a 7B-parameter model needs roughly 8 GB of VRAM, while 70B-scale models require multiple high-end GPUs — that's the hardware threshold for the "completely free" approach.

Full Traceability: Every Call Is Replayable

What really made this tool worth taking seriously is its traceability. While a task is running, you can watch everything it does in real time: context, assistant turns, tool calls, every error — all traceable, not as a summary, but word for word.

Opening the trajectory of a run reveals: the exact system prompt used, the context injected verbatim, which skills were loaded and which weren't (and why), the payload and return value of every tool call, the reasoning process, and the time taken at each step. This level of transparency is something neither Claude Code nor Codex can offer.

To verify that "components can safely come and go" wasn't just marketing copy, the process was tested by killing a task mid-execution and then asking it to "continue from where it left off." It did — picking up precisely where it stopped, using the preserved data: the same context, the same user preferences, the same assistant and tool call history.

It's worth noting that this is a developer preview, with the only marked release being a Release Candidate, and the README explicitly states in capital letters that "breaking changes will occur." But precisely because of the componentized, state-recoverable design, even when something breaks, it can "come back to life."

"Trajectory" is a standard term from reinforcement learning and Agent systems, referring to the complete sequence of states and actions from the start to the end of a task. In a coding Agent, a trajectory typically includes: initial prompt → model reasoning → tool call (e.g., read file, execute command) → tool response → further reasoning → … → final output. Most commercial products only show the final result or a simplified log, while trajectory-level traceability means you can inspect "why the model made this decision" at any node — which is directly valuable for debugging failed tasks, optimizing prompts, and auditing security boundaries. This is also why a task can be resumed precisely after interruption: the state is fully persisted in the trajectory data, not just held in memory.

Everything Is a Plugin: Build a Tool the Official Version Never Had

DeepSeek's homepage tagline is literally "Everything is a plugin" — and it's more literal than you'd expect. In the Plugins settings page, nearly everything is a toggleable plugin, including the sidebar, commands, and more. You can freely add and create plugins within the Harness.

Using Creator Mode — a preset that auto-loads plugin development skills — a simple prompt was given: build a plugin that triggers a desktop notification when a task finishes running, with the token count and cost written directly into the notification. This is exactly the feature that's been missing from every coding Agent — you're often running a nine-minute task in another window and forget about it entirely, never seeing when it completes.

After a few iterations (fixing black-on-black text, switching to white text, fixing the counter), the notification plugin was actually built and working. This kind of create-from-scratch, freely toggled, fully customizable capability is something Claude Code and Codex simply can't provide.

Relationship with Claude Code: Not a Rival — It Can Actually Drive It

There are two packages in the repository that almost nobody talks about: sub-agent-claude-code and sub-agent-codex. These aren't model Providers — they actually spawn Claude Code and Codex as subprocesses and hand tasks off to them.

This gives your Agent two additional tools — sub-agent-claude and sub-agent-codex — and it can autonomously decide that a certain task is better handled by Claude Code, then invoke it accordingly. Three important things to understand here:

• One-shot calls: Each invocation spawns a fresh process and an unrecoverable conversation. One task, one answer — no follow-up.
• Dormant by default: Both Providers are lazy-loaded and won't be available to your Agent unless your preset actively includes them. They're off by default.
• Credential stripping: It intentionally strips credential-related environment variables, so API keys already present in your shell won't be passed to the subprocess — you must pass them explicitly.

This makes it not a competitor to the Agent you're already paying for, but a layer that can orchestrate it. Any framing of this as "DeepSeek vs. Claude Code" or "vs. your existing Agent" is pointing in the wrong direction. The documentation itself states that Anthropic, OpenAI, Bedrock, Vertex, and Codex are all in DeepSeek Harness's built-in Provider list. You can add Anthropic, enter your key, and run Opus inside this free Harness — while getting full traces and plugin capabilities on top.

The sub-agent pattern is a common design pattern in multi-agent system architectures: a primary orchestrator Agent handles task decomposition and routing, dispatches subtasks to specialized sub-agents, and aggregates the results. DeepSeek Harness's approach of spawning Claude Code and Codex as subprocesses effectively implements a lightweight Multi-Agent orchestration. One important caveat: this invocation method means the main Agent cannot access the sub-agent's internal reasoning — only its final output, which is consistent with Claude Code's inherently closed Harness design. The practical value of this architecture is that subtasks requiring Claude Code's strengths (such as deep code comprehension or Artifact generation) can be routed there on demand, without needing to migrate your entire workflow into Claude's ecosystem.

Core Takeaway: Harness and Model Were Always Two Separate Costs — Now One of Them Is Zero

The conclusion is straightforward: for the past two years, the Agent and the model were sold as one bundled product. If you wanted a good model, you had to accept the Harness that came with it. That's no longer true.

The real question was never "choose DeepSeek or choose Claude" — it's that the Harness and the model were always two independent expenditures, and now one of them (the capabilities that used to cost money on the Harness side) has dropped to zero. The only realistic constraint remaining is that connecting Claude requires an API Key rather than a Claude subscription, and the Claude API is not cheap.

The practical recommendation: if you're starting from scratch today, install it, point it at a free or cheap model, and spend a week using it to handle tasks that don't require a top-tier brain. See how much of your monthly workload that covers. For cost-conscious developers who want a fully controllable coding Agent, this is genuinely worth trying hands-on.