System One Harness

1. What is System One Harness?

System One Harness is a Python command-line toolkit for developers and AI researchers. It is not a chatbot and has no interface to click through. Its job is to turn a particular kind of AI model, called a "System One" model, into an agent that works through a task step by step.

Unlike ChatGPT, a System One model does not write text. It only answers questions with fixed options (pick one of several, yes or no, a level on a scale), returns a probability with each answer, and does so very quickly. The harness is the control loop around it: it observes the situation, turns the allowed actions into questions, calls the model once per step, acts only when the model is confident enough, and records everything. The first supported model is Jev by TypeSafe.

The software is free and open source (Apache-2.0). To actually run it, though, you need an API key from OpenRouter or TypeSafe, and each model call is billed by usage.

A good fit if:

• You are a developer or are learning about AI agents and want to try a different approach: the AI may only choose from a declared list of actions and never invents commands.
• You are curious and willing to type a few commands to run the built-in example.

Not a fit if:

• You want a chat app or a ready-made assistant. There is none here.
• You have never used a terminal and do not want to create an API key.

2. What you need

• A computer running macOS, Linux or Windows. The official docs only show macOS/Linux commands; on Windows one command has to be written differently (see Step 4).
• Python 3.10 or newer: the programming language the tool is written in. Python comes with pip, its package installer. Download from https://www.python.org/downloads/
• Git: a tool for downloading source code from GitHub. Get it at https://git-scm.com
• An API key (a secret string used to call the model): from OpenRouter (https://openrouter.ai) or TypeSafe (https://typesafe.ai). Usage is billed; see the provider's site for pricing. In the documentation's sample, one five-step run cost about USD 0.0002.
• Optional: the Chrome browser, if you later want the agent to operate web pages.

The latest version at the time of writing is v0.4.0, released on 21 September 2026. (Parts of the README still say 0.3.1; the project's configuration file and the Releases page say 0.4.0.)

3. Step-by-step installation

There is one way to install: download the source and install it with pip. There is no .exe installer and no app store version.

Step 1: Check Python and Git

Open a terminal (PowerShell on Windows) and run these one at a time:

python --version

git --version

What success looks like: each prints a version number, and Python is 3.10 or higher. On macOS/Linux, if python does not work, try python3 --version.

Step 2: Download the source

git clone https://github.com/HarnessRouter/SystemOneHarness.git
cd SystemOneHarness

What success looks like: a folder named SystemOneHarness is created and your terminal is now inside it.

Step 3: Install

pip install -e .

The trailing dot is part of the command. This installs the tool with the two libraries it depends on and creates the s1 command on your machine.

What success looks like: pip finishes without errors. Check with:

s1 run --help

You should see the list of options for s1 run.

Step 4: Set your API key

The tool reads the key from an environment variable (a value held temporarily by the terminal window). Replace the part after the equals sign with your real key.

macOS / Linux:

export OPENROUTER_API_KEY=sk-or-...

Windows PowerShell (export does not exist in PowerShell, so use PowerShell's own syntax):

$env:OPENROUTER_API_KEY = "sk-or-..."

If you are using a TypeSafe key, name the variable TYPESAFE_API_KEY instead.

Note: The variable only lives in the terminal window you set it in. Close the window and it is gone; you will need to set it again next time. Never share your API key or paste it anywhere public.

Step 5: Run the built-in example

s1 run --env order:ship_fastest_gift

This is a bundled demo environment: a simulated order that must be marked as a gift and shipped with the fastest carrier.

What success looks like: the screen prints the goal, the model name, and then about five lines, one per step (add a note, pick the item, pack, choose a carrier, ship), each with a probability p= and a time in milliseconds. The last line contains status=completed along with the step count, total time and cost.

4. First use

Once the example runs, read the output with three things in mind:

• Each line is one decision. The model does not type commands; it selects one action from the list the environment allows.
• The p= number is the weakest confidence that step required. Riskier actions need a higher threshold. In the documentation's example the thresholds are 0.5 for read-only actions, 0.6 for writes and 0.8 for actions that cannot be undone.
• The final line tells you how the run ended. Every run finishes as completed, incomplete, failed or cancelled, with a stated reason.

To save the full record to a file, add --json:

s1 run --env order:ship_fastest_gift --json trace.json

A trace.json file appears in the current folder, holding the state, questions, probabilities and result of every step.

If you do not have an API key yet but want to confirm the install is healthy, run the test suite. It uses recorded model answers, so it needs no key:

pip install -e . pytest
pytest -q tests

When you are ready to go further, the tool can connect to four kinds of environment: your own program plus a YAML file that declares the actions, an MCP server (a standard for giving AI access to tools), the Chrome browser, or Python code. Each needs its matching extra installed, for example for MCP:

pip install -e ".[mcp]"

And for the browser:

pip install -e ".[browser]"

These steps require programming knowledge. Detailed guides live in the repository's docs/ folder: https://github.com/HarnessRouter/SystemOneHarness

5. Common problems and fixes

Symptom	Cause	Fix
Typing s1 gives "command not found"	Step 3 was skipped or run in the wrong folder, or Python's scripts folder is not on your PATH (the list of places the system looks for commands)	Go back into the SystemOneHarness folder and rerun pip install -e .. If it still fails, close and reopen the terminal
pip complains about the Python version	The machine is using a Python older than 3.10	Install a newer Python from https://www.python.org/downloads/ and retry
git is not found	Git is not installed	Install Git from https://git-scm.com and reopen the terminal
On Windows, export fails	export is a macOS/Linux command	Use the PowerShell $env:... form shown in Step 4
s1 run stops immediately with a key or authentication error	The API key is not set, was set in a different window, or is wrong	Set the key again in the window you are using and rerun. Check on the provider's site that the key is still valid
A run ends with the reason no_confident_action, or with the escalate action	The model was not confident enough to clear the threshold, so it stopped and handed over. This is by design, not a crash	Save the run with --json trace.json and read the handoff section: it records the state, the questions and the probabilities at the point it stopped
Your action file is rejected because of a free-text parameter	A System One model does not generate text, so every parameter must be enumerable	Change the parameter to a fixed list of choices, values taken from the observation, a true/false flag or ordered levels
Using --mcp or --browser reports a missing package	The matching extra is not installed	Run pip install -e ".[mcp]" or pip install -e ".[browser]"

6. Uninstalling and updating

Updating: go into the SystemOneHarness folder, fetch the new source and reinstall.

git pull
pip install -e .

Uninstalling: remove the Python package (its name is systemone-harness), then delete the SystemOneHarness folder you downloaded.

pip uninstall systemone-harness

If you are done with it for good, also revoke the API key you created on the OpenRouter or TypeSafe site.

7. Frequently asked questions

Does it cost anything? The software is free. You pay the model provider (OpenRouter or TypeSafe) for usage. By the documentation's own measurements, a run of the sample scenarios costs roughly USD 0.00004 to 0.0003; check the provider's site for current pricing.

Does it need an internet connection? Yes. Every step calls the model over the internet. The test suite in section 4 is the exception and runs without a key.

Is my data sent anywhere? The goal and each step's observation are sent to the model provider you chose in order to get an answer. Do not feed it sensitive data while experimenting.

Will it run on a weak computer? The tool itself is lightweight and depends on only two small Python libraries, because the model runs at the provider rather than on your machine.

Can it handle complex work? The authors are explicit about the limits: the measurements in the documentation only demonstrate small, clear-cut tasks. They make no claim of the same results for ambiguous situations, arithmetic, dates or long contexts full of irrelevant information.