What is an agent harness?

What an agent harness is

An agent harness is the program that runs around a language model and turns it into an agent. It holds the loop that keeps calling the model, the tool definitions the model is allowed to call, the permission rules that decide which of those calls actually run, the session state that survives between turns, and the working directory where the work happens. The model is swappable inside it.

That last sentence is the one to keep. A model on its own answers a question and forgets you. A harness asks the model what to do next, runs the command the model asked for, feeds the result back, and asks again. That repetition is what people mean when they say "agent". If the surrounding vocabulary is still fuzzy, the difference between an AI agent, an LLM and an assistant sorts out the words before you pick a tool.

The harness is not the model

The two get confused because vendors ship them under one brand name.

dsh and DeepSeek are different products. DeepSeek Harness, published at github.com/deepseek-ai/deepseek-harness on 13 August 2026 under the MIT licence, is a Node program you install on a machine. The DeepSeek models are weights served behind an API (application programming interface). Point dsh at a model from another vendor and it keeps working, because the harness only needs something that accepts messages and returns tool calls.

Claude Code and Claude are the same pair. Claude Code is a harness: a terminal program with a loop, a permission system, and file and shell tools. Claude is the model family it calls by default. Codex and Gemini CLI split the same way.

Here is the test that settles it every time. You install a harness. You call a model. If the thing has a version on your disk and a config file in your home directory, it is a harness. If it is a string inside that config file, something like deepseek-chat, that is the model.

What the loop actually does

One turn of a harness loop looks like this. Read it slowly, because almost every difference between harnesses is a difference inside these five steps.

1. The harness sends the conversation so far, plus a list of tool definitions, to the model.
2. The model replies with text, or with a request to call one of those tools.
3. The harness checks that request against its permission rules and either runs it or stops to ask you.
4. The harness runs the tool, captures the output and the exit code, and truncates the output if it is very long.
5. The harness appends that result to the conversation and goes back to step 1.

Step 3 is where harnesses differ most in daily use. A harness that asks before every command is safe and exhausting. A harness that never asks will eventually run a destructive command on a path the model got wrong. Every serious harness now has a middle setting: an allowlist of commands that run without asking, and a prompt for everything else.

Step 1 is where the rest of the difference lives. The conversation grows every turn and a model has a fixed context window, so the harness must decide what to drop, what to summarise, and what to write out to a file and read back later. That decision is most of the reason two harnesses driving the same model produce different quality of work.

Most harnesses now attach external tools over MCP (model context protocol), a standard way to expose a tool to any harness that speaks it, so one integration reaches several harnesses. Running MCP servers on a VPS covers that side of it.

Agent harness vs agent framework

This question comes up every time a new harness lands, and the answers disagree, partly because the vendors disagree. Here is the version that holds up.

A framework is a library you import. You write the loop, you decide when to call the model, you handle the tool results yourself. LangChain is the well known example: you get building blocks and you assemble the agent in code.

A harness is a program you run. The loop is already written, the tools already exist, the permission model already has a default. You get a working agent on the first command and you configure it from there.

The install test usually decides it. If you install it and then write code, it is a framework. If you install it and then talk to it, it is a harness.

The boundary is genuinely contested, and the clearest evidence is LangChain's own documentation. As of August 2026 it describes Deep Agents as an "opinionated, batteries-included" framework built on LangGraph, while the langchain-ai/deepagents repository calls itself "the batteries-included agent harness". Both descriptions are fair. Deep Agents is a Python SDK (software development kit) you import, so the install test calls it a library, and it ships enough default behaviour that people use it like a harness. Microsoft shipped a harness and hosted agents to general availability in August 2026, which shows the word is now a product category rather than jargon.

So ask the question that predicts your workload instead. If you write the loop, you own the loop: the retries, the context trimming, the permission prompts and the record of what happened. If the loop ships, you inherit someone else's answer to all of those, which is much faster to start and harder to change later.

How a harness differs from a chat window

A chat window and a harness both show you model output. The difference is whose computer the work happens on. In a chat window, any code the model runs executes inside the vendor's sandbox, on files you uploaded, and it disappears when the session ends. A harness runs tools on the machine you started it on, as the user who started it, against your real files, with your real credentials in its environment.

That is the whole upside and the whole risk in two sentences. The agent can finally do the work. The agent can also delete the work.

The harnesses people are actually running

This list is dated 19 August 2026 on purpose. The category is moving weekly and any roundup ages fast.

• Claude Code and Codex are vendor harnesses. Terminal first, tied by default to their vendor's own models, with the most polished permission handling. How Claude Code, Cursor, Codex and Copilot compare goes through them properly.
• DeepSeek Harness (dsh) is MIT licensed and built on one idea: everything is a plugin, so models, tools, sessions, sandboxes and the user interface are all swappable pieces. It sat at roughly 166,800 GitHub stars on 19 August 2026, six days after it was published.
• Hermes, from Nous Research, is a general autonomous agent rather than a coding tool. It was released under MIT in February 2026 and keeps its memories and skills in a local SQLite database on your own machine. Self-hosting Hermes on a VPS walks through it.
• Omnigent is a meta-harness: it drives other harnesses, including Claude Code and Codex, behind one API with shared sessions, spend caps and an operating system level sandbox. Omnigent as a multi-agent harness covers what that buys you.
• OneCLI is a sandboxed harness aimed at teams, built around a gateway that injects real credentials into outbound requests so the agent itself only ever sees placeholder keys.

The dsh quick start is a single command, and running it once is the fastest way to see what a harness is. It needs Node.js on the machine.

npx @deepseek-ai/dsh web

That starts the web UI (user interface) on http://127.0.0.1:3080. Read the README before you rely on it, because dsh describes itself as a developer preview and says plainly that there will be compatibility-breaking changes. Running DeepSeek Harness on a VPS covers the server install, and why that address starts with 127.0.0.1 explains the loopback default.

Routers sit above the harness

A model router is a local proxy between the harness and the provider API. Claude Code Router is the common example: it binds to 127.0.0.1:3456 by default, accepts the requests Claude Code would have sent to its own vendor, and forwards them to whichever provider you configured. The harness does not know anything changed.

Routers exist because the model is swappable, so they are good proof of the main point of this post. They also concentrate risk, because the proxy sees every prompt and holds every provider key. Treat it as infrastructure, not as a convenience. Where a harness keeps its API keys and model settings is the same problem one layer down.

What changes when the harness runs on a VPS

Four things change when the harness moves off your laptop and onto a server you rent.

It keeps running when you close the lid. A long task survives your commute and your battery. Start it inside tmux and detach from it:

tmux new -s agent
# start the harness, then press Ctrl-b and then d to detach
tmux attach -t agent

For anything that should come back after a reboot, a user service beats a terminal session:

loginctl enable-linger $USER
systemctl --user status my-agent.service

loginctl enable-linger is the part people miss. Without it, systemd stops your user's services as soon as your last SSH (secure shell) session closes, so the agent dies when you log out and nothing prints an error. Running dsh headless under systemd has the unit file. Once one session is living on that server, a second one costs you nothing extra, and two Claude Code sessions on the same box can message each other, so the one you started this morning can hand a job to the other without you relaying it by hand.

It holds your keys. The provider key now lives in a config file on that server. Check who can read it:

ls -l ~/.config

Any process running as your user can read that file, which includes the agent and anything the agent chooses to run.

It can reach your other machines. A VPS on the same private network as your other boxes gives the agent a route to them. That is exactly the point, and it is also the blast radius.

It is reachable from wherever you are. Most harnesses expose a web UI, and most bind it to loopback for a reason. Check yours:

ss -tlnp | grep 3080

127.0.0.1:3080 means only the server itself can connect. 0.0.0.0:3080 means anyone who finds the address can. Reach a loopback UI through an SSH tunnel rather than changing the bind address:

ssh -N -L 3080:127.0.0.1:3080 you@your-server

Then open http://127.0.0.1:3080 in the browser on your laptop. The traffic rides inside the SSH session, so nothing new is exposed to the internet.

Every one of those is also the security argument

Read the four properties again the way an attacker would.

It runs unattended, so nobody is watching the turn where the model misreads a path. It holds your keys, so one readable config file is your whole provider account. It can reach your other machines, so a prompt injection, meaning instructions hidden in a web page or a file the agent reads, now has a route to your database host. It is reachable from anywhere, so a web UI bound to 0.0.0.0 with no password is a shell on the public internet.

The fix in each case is dull, and it is the same fix every time. Give the agent its own unprivileged user account instead of yours:

sudo adduser --disabled-password --gecos "" agent

Keep the web UI on loopback and reach it over SSH. Give the agent the narrowest credentials that still let it finish the job, which keeping secrets out of AI agents goes into properly. For anything that runs while you are not watching, a throwaway machine beats a careful one: running coding agents in a disposable VM and running Claude Code safely on a VPS both take that route.

Do you need an agent harness?

If your work is one question at a time, a chat window is enough, and a harness only adds a loop you have to supervise. A harness starts paying for itself when a task takes many steps against real files, or when it has to keep working while you are asleep.

Most of this category is young. dsh says developer preview in its own README as of August 2026, and the rest are moving fast enough that a config file you write today may need editing next month. That is a reason to keep your setup small and reproducible, and a reason to write down what you changed. The same restraint helps inside the loop, where a skill that pushes the agent toward the smallest change that works leaves you a diff you can actually read at the end of an unattended run. Start with one harness on one server, give it one job and one narrow key, and widen its access only after that first job has been boring for a week. The self-hosted agents worth running today is a reasonable place to choose the first one.

FAQ

What is an agent harness in simple terms?

It is the program around the model. The model produces text and requests to use tools. The harness runs the loop that keeps asking, executes the tools the model requests, enforces the rules about which tools may run without permission, and keeps the session state and the files between turns. Swap the model and the harness still works, which is the clearest sign that the two are separate things.

Is Claude Code a model or a harness?

Claude Code is a harness. It is a terminal program with a loop, a permission system and built-in file and shell tools. Claude is the model family it calls by default. The same split applies to DeepSeek Harness (dsh), which is a Node program you install, and the DeepSeek models, which are served over an API. You install a harness on a machine. You call a model over the network.

What is the difference between an agent harness and an agent framework?

A framework is a library you import and write code against, so you own the loop, the retries and the context handling. A harness is a program you run, so all of that ships with defaults you configure instead of write. The line is blurry in practice: LangChain's Deep Agents is an importable SDK that its own repository calls a batteries-included agent harness, as of August 2026. Ask whether you will be writing the loop yourself. That answer decides which word fits your situation.

Do I need a VPS to run an agent harness?

No. Every harness named here runs on a laptop. A server changes four things: the agent keeps running when you close the lid, it holds your keys on a machine that is always on, it can reach your other servers, and you can return to the same session from any device. Each of those is also a security consideration, so give the agent its own user account and keep any web UI bound to 127.0.0.1.

Can I use a different model inside the same harness?

Usually yes, and that is the defining property of a harness. Most of them take a model name and a base URL in their config, so pointing one at another provider is an edit rather than a rewrite. Where a harness resists, a local router such as Claude Code Router sits between the harness and the provider and translates the requests, binding to 127.0.0.1:3456 by default. Be careful with that proxy, because it sees every prompt and holds every key.