# Harness engineering: own the harness files in an open-source repo

> Harness engineering is the practice of designing the full environment an AI agent operates within: the rules it follows, the checks it must pass, and the feedback loops that prevent the same mistake from recurring. Reliability is decided in that harness. Kortix is the open-source AI Operating System, and it keeps the harness in files you own.

URL: https://harnessengineeringguide.com/

For teams whose agents keep repeating the same mistake

**The open-source AI Operating System**

`harness.ts`

```ts
const cfg = loadConfig()                 // reads KORTIX_HARNESS, then the selected adapter's env
const selected = resolveHarness(cfg)
const runtime = selected.createService(cfg, projectEnv)
await runtime.lifecycle.start()
```

Source: https://github.com/kortix-ai/suna/blob/dev/apps/kortix-sandbox-agent-server/src/harness/README.md

One box, one harness, for the life of the box.

[Try Kortix](https://kortix.com) · [See the harness boundary](https://github.com/kortix-ai/suna/blob/dev/apps/kortix-sandbox-agent-server/src/harness/README.md)

Open source · Any model provider with your own keys · Approval gates you set

## Three controls a harness owns

Each one is a file a reviewer can open, diff and roll back.

### Guides and sensors: The check runs before the edit and after it.

A linter steers the change on the way in, a test reports on what came out, and the same failure cannot pass twice.

In the repo: `scripts/check.ts`

```diff
//   1. the package's `typecheck` script,
//   2. ESLint on the touched files (packages whose `lint` is ESLint),
//   3. ONLY the tests related to the touched files: a touched test file, and for
```

typecheck · ESLint · the tests for the touched files

Source: scripts/check.ts

### Permissions: An agent reaches only what the manifest grants it.

Each grant is a key on the agent in kortix.yaml, and a grant left out resolves to none, so a scoped specialist starts locked down.

In the repo: `kortix.yaml`

- connectors: all
- secrets: all
- kortix_permissions: all

Source: packages/starter/templates/base/kortix.yaml

### Swappable harness: The harness is a module the box resolves at boot.

A preflight answers what a switch would cost before anyone makes it, and the log records the switch when it happens.

In the repo: `harness.ts`

- KORTIX_HARNESS: pi
- unknown id: boot fails
- per-request switch: none

Source: apps/kortix-sandbox-agent-server/src/harness/README.md

## Where the harness lives in four agent tools

What matters is where the rules live, who can change them, and what runs the agent.

| | Kortix (the AI Operating System) (recommended) | Claude Code | Codex CLI | OpenHands |
| --- | --- | --- | --- | --- |
| Open source | Yes | No | Yes, code on GitHub | Yes, code on GitHub |
| Where the harness config lives | agents/*.md and kortix.yaml in your git repo | .claude/settings.json (committed) and ~/.claude/settings.json; CLAUDE.md holds the project instructions | ~/.codex/config.toml plus project .codex/config.toml | Settings UI, or environment variables when self-hosted |
| Where the agent runs | One isolated sandbox per session. Each session has its own isolated machine and branch. | Your machine, or a cloud session | Locally on your computer | Docker on your machine, or OpenHands Cloud |
| Approval control | Approval gates you set. Off until you set them. | Allow, ask and deny rules in settings | approval_policy and sandbox_mode in config | Asks first; flags to auto-approve |
| Model choice | Any model provider with your own keys | Claude models; third-party providers on some surfaces | ChatGPT plan, or an API key | Any LLM provider with your API key |

## The harness boundary is a file you can read today

Open source here means the adapter, the manifest and the rules around them are yours to read, fork and audit.

- [Read the harness boundary](https://github.com/kortix-ai/suna/blob/dev/apps/kortix-sandbox-agent-server/src/harness/README.md)
- [Kortix on GitHub](https://github.com/kortix-ai/suna)

## Questions the discipline raises

### What does harness engineering change about reliability?

It moves reliability into the environment around the model, the part [LangChain calls the harness](https://www.langchain.com/blog/the-anatomy-of-an-agent-harness). On public benchmarks, the same model can place significantly higher or lower depending entirely on how that harness is built. [Databricks](https://www.databricks.com/blog/ai-harness) paired GPT-5.5 with its OfficeQA Pro Agent Harness and scored 52.63%, up from 36.10% with GPT-5.4.

### Where do you start with harness engineering?

With the mistake that just happened. Fix it in the environment rather than in the prompt: a lint rule, a test, a hook, or one line the agent reads every session. Then commit those files and review them like any other code.

### Does harness engineering apply to non-coding agents?

Yes. [Guides](https://martinfowler.com/articles/harness-engineering.html) steer any agent before it acts and sensors check what it produced after, so a research agent gets a source check on the way in and a citation check on the way out. The checks change with the job; the structure does not.

## Run agents whose harness you can read.

Agents, skills, company memory and connectors in one git repo.

[Try Kortix](https://kortix.com)