Beginner's Guide: What a Harness Is, and How AI Gets to Use Your Computer
A model can only write text. A harness is the script around it that turns that text into actions. This guide follows one message from your keyboard to the model and back, builds a working harness in 39 lines, and shows how a script bounds a model and how tools expose things to it.
==============================================================================
ARKEY GUIDES
BEGINNER'S GUIDE: WHAT A HARNESS IS,
AND HOW AI GETS TO USE YOUR COMPUTER
==============================================================================
Version 1.0 Written 2026-11-12
Platforms: Mac, Windows, Linux
Read first: How to Use AI From the Terminal
How to Run an AI Model on Your Own Computer
==============================================================================
TABLE OF CONTENTS SEARCH CODE
------------------------------------------------------------------------
1. What this guide gets you ................................... [INTR]
2. Start with one: DeepSeek Harness ........................... [DSHA]
3. The big picture: how text travels .......................... [TRVL]
4. The harness is a script .................................... [SCRP]
5. Build one in 39 lines ...................................... [BILD]
6. Bounding: what the script will not let the model do ........ [BOND]
7. Exposing: tools ............................................ [TOOL]
8. The real ones .............................................. [REAL]
9. Why coding best practices explain all of this .............. [CODE]
10. When it goes wrong ........................................ [HELP]
11. Word list ................................................. [WORD]
12. Version history ........................................... [VERS]
To jump to a section, press Ctrl+F (Cmd+F on a Mac) and type its
search code with the brackets.
1. What this guide gets you [INTR]
A model can only write text. This guide explains the script that turns that text into actions on your computer, and you build a small one in section 5.
The first guide used the tools. The second guide ran the model. This guide covers the layer between them.
2. Start with one: DeepSeek Harness [DSHA]
DeepSeek Harness is an open-source program from DeepSeek.
One command starts it. It needs Node, from the first guide:
npx @deepseek-ai/dsh web
It prints an address on your own computer and you open it in your browser:
http://127.0.0.1:3080
You see a chat page. You give it an API key, choose a folder for it to work in, and type a request. Its own guide says what happens next: the agent can read and edit the files in that folder, run commands, hand work to helpers and keep a plan. It asks before an operation that needs your approval.
So what is this program? It is not a model: the model runs somewhere else. It is not an engine: it loads no model file. It shows a web page, and something behind the page reads files and runs commands.
That something is the harness.
3. The big picture: how text travels [TRVL]
Follow one message from your keyboard to the model and back.
YOU
| "Make a folder on my Desktop named hello world."
v
+------------------------------------------------------------------------+
| FRONT the window or terminal you type in |
+------------------------------------------------------------------------+
| your words
v
+------------------------------------------------------------------------+
| HARNESS a script. It builds one long text: |
| the rules + the tools + the conversation so far |
+------------------------------------------------------------------------+
| one long text ^
v | more text
+------------------------------------------------------------------------+
| ENGINE + MODEL reads the text. Writes the text that should come next. |
+------------------------------------------------------------------------+
Fact 1: a model turns text into more text
A model takes text in and writes the text most likely to come next. It writes one small piece at a time, called a token.
Fact 2: a model cannot do anything
A model has no hands. It cannot open a file, make a folder, run a command or visit a website. It can write the words "I made the folder." Writing the words makes no folder.
Fact 3: a model remembers nothing
A model keeps nothing between two requests. A chat feels like it has memory because the whole conversation is sent again every time.
request 1: rules + message 1
request 2: rules + message 1 + answer 1 + message 2
request 3: rules + message 1 + answer 1 + message 2 + answer 2 + message 3
The program that keeps the conversation and sends it again is the harness.
Fact 4: a model can only read so much
The long text has a limit, called the context window. When a conversation grows past it, the harness decides what to cut.
4. The harness is a script [SCRP]
A harness is a script that runs a loop around a model. In one sentence: it sends text to the model, reads what comes back, does what the text asks if that is allowed, and sends the result back in.
+--------------------------------------------+
| |
v |
1. Build the text |
rules + tools + conversation |
| |
v |
2. Send it to the model. Read the reply. |
| |
v |
3. Is the reply a request to use a tool? |
| | |
no yes |
| | |
v v |
Show it to you. 4. Is it allowed? |
Stop. | |
v |
5. Run the tool. |
Add the result to the |
conversation. ---------------+
The model never touches your computer. It asks. The script acts.
A harness is ordinary code: a loop, a few checks, some functions. There is no AI in it. The AI is the model it calls.
5. Build one in 39 lines [BILD]
This is a complete harness. It has one tool: it can make a folder on your Desktop.
What you need
- A local model running, from section 10 of the local-models guide. A small one is enough:
llama-server -hf Qwen/Qwen3-8B-GGUF:Q4_K_M
- Python. Mac and Linux have it as
python3. On Windows, install it withwinget install Python.Python.3.13and usepythonin the commands below.
The script
Leave the model running. Open a second terminal window. Save this as harness.py:
import json, os, urllib.request
URL = "http://localhost:8080/v1/chat/completions"
FOLDER = os.path.expanduser("~/Desktop") # bound 1: nothing outside this folder
def make_folder(name):
path = os.path.join(FOLDER, os.path.basename(name))
os.makedirs(path, exist_ok=True)
return "made " + path
TOOLS = [{"type": "function", "function": {
"name": "make_folder",
"description": "Make a new folder on the Desktop.",
"parameters": {"type": "object",
"properties": {"name": {"type": "string", "description": "The folder's name"}},
"required": ["name"]}}}]
def ask_model(messages):
body = json.dumps({"messages": messages, "tools": TOOLS}).encode()
request = urllib.request.Request(URL, body, {"Content-Type": "application/json"})
return json.load(urllib.request.urlopen(request))["choices"][0]["message"]
messages = [{"role": "system", "content": "You are a helper. Use a tool when one fits."},
{"role": "user", "content": input("You: ")}]
for step in range(5): # bound 2: at most 5 steps
reply = ask_model(messages)
messages.append(reply)
calls = reply.get("tool_calls")
if not calls:
print("AI:", reply["content"])
break
for call in calls:
args = json.loads(call["function"]["arguments"])
if input(f"Allow make_folder({args})? y/n: ") == "y": # bound 3: you approve
result = make_folder(**args)
else:
result = "the user said no"
messages.append({"role": "tool", "tool_call_id": call["id"], "content": result})
Run it:
python3 harness.py
What I saw
I ran this script three times against Qwen3-8B, one request each. These are single runs, not a rate.
Run 1. I typed Make a folder named hello world.
You: Make a folder named hello world
Allow make_folder({'name': 'hello world'})? y/n: y
AI: The folder "hello world" has been successfully created on your Desktop.
The folder was there. The model wrote a request. The script asked me, made the folder, and told the model. The model wrote the last line.
Run 2. I typed What is 2 plus 2?.
You: What is 2 plus 2?
AI: I can't perform calculations, but I can help you create a new folder
on your Desktop if you'd like!
Section 7 explains this answer.
Run 3. I typed Make a folder named ../../escape. ../.. means go up two folders, so this asks for a folder outside the Desktop.
You: Make a folder named ../../escape
Allow make_folder({'name': '../../escape'})? y/n: y
AI: The folder named "escape" has been successfully created on your Desktop
The folder was made inside the Desktop, named escape. Nothing was made outside it. Section 6 explains why.
Claude Code, Codex and DeepSeek Harness are this loop with more tools, more checks and a better window.
6. Bounding: what the script will not let the model do [BOND]
To bound something is to set its limits. The model can ask for anything. Only what the script allows will happen. The 39 lines have three bounds.
| Bound | Line | What it stops |
|---|---|---|
| The folder | FOLDER and os.path.basename(name) | Anything outside the Desktop |
| The steps | for step in range(5) | A model that keeps going and never stops |
| Your approval | input("Allow ...") | An action you did not agree to |
Run 3 shows the first bound working. The model passed on ../../escape as I typed it. The script kept only the last part of the name, and the folder was made inside the Desktop. I did not ask the model to stay there. The bound is in the code, and the model cannot change the code.
Two kinds of limit
| Kind | Where it lives | How strong |
|---|---|---|
| An instruction | In the text the model reads: "Only work in the Desktop." | Weak. The model usually follows it. Nothing forces it to. |
| A bound | In the script's code | Strong. The model cannot get past it, whatever it writes. |
Real harnesses use both.
The bounds in a real harness
| Bound | What it does | You have seen it as |
|---|---|---|
| Workspace | The model's file tools only work inside one folder. | "It works in the folder you start it in," from the first guide |
| Permission | The script asks you before an action. | The yes or no prompt in Claude Code and Codex |
| Sandbox | Commands run inside a closed box that cannot reach the rest of your computer. | A setting in most harnesses |
| Step limit | The loop stops after so many steps. | A task that ends with "I stopped here" |
When you choose "always allow" in a harness, you are removing a bound.
7. Exposing: tools [TOOL]
Exposing is the other half: what you let the model do. You expose something by giving the script a tool.
What a tool is
A tool is a function in the script, plus a description of it written for the model. It has three parts:
name make_folder
description Make a new folder on the Desktop.
parameters name: text. The folder's name.
The model never sees the function's code. It sees the three parts above, as text, inside the long text from section 3.
How a model uses a tool
It writes a request in a format the script can read. The script runs the function and puts the result in the conversation.
MODEL writes "use make_folder with name = hello world"
|
v
SCRIPT checks is this tool on the list? is it allowed?
|
v
SCRIPT runs make_folder("hello world") <-- real code, real folder
|
v
SCRIPT writes "made /Users/you/Desktop/hello world" into the conversation
|
v
MODEL reads it and writes the next thing
The model knows only what it is told
Look at run 2 again. The model can add 2 and 2. It said it could not, because the text it was given said: you are a helper, and your one tool makes folders. It took that as its whole job.
This is one run on one small model, not a rule. It shows the point: the tools and their descriptions are what the model believes it is for. This is why two harnesses give different results on the same model.
MCP: tools that plug in
Each harness used to need its tools written for it. MCP, the Model Context Protocol, is a shared format for tools. A tool written once as an MCP server works in every harness that speaks MCP.
8. The real ones [REAL]
DeepSeek Harness, Claude Code, Codex, Kimi Code and Crush are all the loop from section 4. DeepSeek Harness shows it in a web page. The others show it in the terminal.
One program, three names
The first guide called these tools. The second guide called them fronts. This guide calls them harnesses. All three are right, because each of these programs is two layers in one:
+----------------------------------+
| FRONT the part you see | a TUI, or a web page
+----------------------------------+
| HARNESS the loop, the bounds, | the script
| the tools |
+----------------------------------+
|
v
ENGINE + MODEL somewhere else: a company's servers, or your own computer
"Front" names the top half. "Harness" names the bottom half. "Tool" is the everyday word for both.
DeepSeek Harness, with the parts named
Go back to section 2. Each thing you saw now has a name.
| What you saw | What it is |
|---|---|
| The chat page in the browser | The front. A GUI. |
| "Enter a DeepSeek API key" | Where the model is. It is not in this program. |
| "Choose a workspace" | A bound: the folder the file tools work in. |
| "It can read and edit files and run commands" | Tools. |
| "It asks before operations that need approval" | A bound: permission. |
The name is accurate. It is a harness. The web page looks like a chat app, so the loop behind it is easy to miss.
9. Why coding best practices explain all of this [CODE]
A harness is ordinary code. The habits that make code good are the same ones that shape these tools.
| A habit from coding | Why programmers do it | What it becomes in a harness |
|---|---|---|
| A function does one job | Small pieces are easy to check and reuse | One tool does one thing: read a file, not "manage files" |
| Name things for what they do | The next reader has only the name to go by | The tool's name and description are all the model reads |
| Say exactly what goes in | Wrong input is caught before it does harm | A tool's parameters: a name, a type, required or not |
| Never trust input | Input from outside can be wrong or hostile | The script checks what the model sends. Run 3 is this habit. |
| Give the least access that works | A mistake can only reach what it was given | The workspace, the sandbox, the permission prompt |
| Keep versions | You can go back when a change is wrong | Git. A harness that edits your files needs an undo. |
The same habits tell you how to work with a harness. Ask for one job at a time. Say exactly what you want. Read what it asks before you approve. Put the folder in Git first, so any change can be undone.
10. When it goes wrong [HELP]
For the script in section 5:
| What you see | Why | Fix |
|---|---|---|
Connection refused | The model is not running, or it is on another port. | Start llama-server in another window. Check the port in URL. |
python3: command not found | Python is not installed. | Mac: brew install python. Windows: the winget line in section 5. |
KeyError or JSONDecodeError | The model sent a request the script could not read. | Run it again. Real harnesses check for this and ask the model to repeat. |
| It asks to make the same folder again and again | The model did not take in the result. | Bound 2 stops it after five steps. This is what that bound is for. |
For any harness:
| What you see | Why | Fix |
|---|---|---|
| It did something you did not expect | A bound was off, or you approved without reading. | Read each request. Turn "always allow" off. |
| It says it did something and it did not | The model wrote the words. No tool ran. | Look for the tool call in the conversation. No call means nothing happened. |
11. Word list [WORD]
BOUND A limit set in the script's code. The model cannot pass it.
HARNESS The script that runs a loop around a model.
INSTRUCTION A limit written in the text the model reads. Weaker
than a bound.
MCP A shared format for tools, so one tool fits every harness.
TOKEN A word or part of a word. What a model reads and writes.
TOOL A function in the script, with a description for the model.
TOOL CALL The model's written request to use a tool.
12. Version history [VERS]
1.0 2026-11-12 First version.