harnessie.com / docs / Quickstart

Quickstart for people, not just developers

This is the gentlest path into Harnessie. It assumes you have never cloned a repository, never written YAML, and are not sure what a terminal is for. That is fine. Every command here is safe, nothing reaches the internet or spends money until you decide it should, and the tool checks your machine for you before anything runs.

If you are already comfortable in a terminal, the faster five-minute path is Getting started, and the full reference is the user guide.

What Harnessie is, in one breath

A harness is the structure you put around an AI model so it can do real work while you stay in control. It decides what the AI is allowed to do, checks the work before moving on, and writes down everything that happened so you can read it back. Harnessie is built to be a safe first one: it runs on your own machine, and its first run costs nothing because it uses a pretend "mock" model instead of a paid one.

New words (harness, agent, workflow, gate, brain, and so on) are collected in the Glossary at the end. You do not need to memorize them; glance down when one shows up.

What you need

You do not need an API key, a credit card, or a cloud account to finish this quickstart.

Step 1: Get Harnessie

One line installs the harnessie command from the Python package index:

pip install harnessie

If pip is not found, try python3 -m pip install harnessie. If you use pipx, uv, or Homebrew, pipx install harnessie, uv tool install harnessie, and brew install snapsynapse/tap/harnessie work the same way. You do not need to download or clone anything.

Step 2: Let the tool check your machine

Create your own project and let Harnessie tell you whether everything is ready:

harnessie init my-first-project

This scaffolds a small project (a config file, an example workflow, the agent instructions) and then runs a guided first check. You will see something like:

Guided first run — is this machine ready?

  [ok  ] Python: Python 3.12 meets the 3.11+ requirement.
  [ok  ] Sandbox: OS sandbox backend detected: seatbelt. Shell work will be confined.
  [ok  ] API keys: No API key needed: this scaffold uses the mock brain, so your first run costs zero dollars.
  [ok  ] First run: Zero-dollar mock run: 2/2 eval baseline checks passed. Your harness works end to end and billed nothing.

You are ready. Run your first workflow:
  harnessie run workflows/build-and-verify.yaml --goal "your goal here"

Read each line. If Python is too old, it says so. If your computer has no sandbox (the safety cage around any command the AI runs), it says so plainly and explains that shell work will simply be blocked until you add one, which is protection, not breakage. The last line proves the harness works, using the mock model, for zero dollars.

Step 3: Run your first real workflow

Move into your project and run the built-in workflow, which plans a small change, makes it, and checks it:

cd my-first-project
harnessie run workflows/build-and-verify.yaml --goal "a to-do list saved to a text file"

Before it starts, Harnessie prints a cost preview. Because the scaffold uses the mock model, it will say MOCK (zero-dollar, nothing is billed). The run then prints a plain summary at the end. Every run gets an id; note it down, or copy it from the summary.

To use a real, paid AI model later, you edit one file (config/models.yaml) and set the model's key as an environment variable in your terminal. You never paste a key into a file. Harnessie refuses to start a paid run that has no spending ceiling, so you cannot accidentally run up a bill.

Step 4: Read what happened

A run never just says "done". Ask for a plain-language report:

harnessie report <run_id>

Put your run's id in place of <run_id>. The report tells you, in ordinary sentences, which steps completed, whether the run stopped and is waiting for you, and the single next thing to do. For the complete, hash-verified trail of every action, run harnessie audit <run_id>.

Step 5: When a run stops and waits for you

Silence is never treated as success. A run ends in a named condition, and each one names one action:

Re-running is safe: a resume only re-does the steps that did not already pass.

Running on Windows

Harnessie's safety depends on an operating-system sandbox that confines any command the AI runs. macOS and Linux provide one. Bare Windows (the Command Prompt or PowerShell) does not provide one that Harnessie can use, so on bare Windows the harness fails closed: any workflow step that runs a shell command is blocked rather than run without a cage. That is deliberate. An unconfined command is exactly the risk the sandbox exists to remove, so running without one would quietly break the core safety promise.

The supported path on Windows is WSL2 (Windows Subsystem for Linux), which gives you a real Linux environment inside Windows:

  1. Open PowerShell as Administrator and run wsl --install. Restart when asked.
  2. Launch the installed Ubuntu app and finish its first-time setup.
  3. Inside that Ubuntu window, follow this quickstart from Step 1. It is now a Linux machine, and the Linux sandbox (bubblewrap) applies.

Everything mock and offline works on bare Windows too (the checks, the eval baseline, reading reports), because none of it runs a sandboxed shell command. It is only shell-using workflow steps that require WSL2. If you are only exploring, you can start on bare Windows and move to WSL2 when you want to run a real workflow.

Glossary

Terms in the order a newcomer meets them, each in one plain sentence.

Where to next