# Pi harness, defined: the open-source loop around the model > Pi is a minimal agent harness. It runs the model loop, calls four built-in tools and writes the transcript. Kortix is the open-source AI Operating System, and it runs Pi inside a machine that supplies the rules the harness leaves out. URL: https://picodingagentguide.com/pi-harness What Pi does not do by default **The open-source AI Operating System** `README.md` ``` Pi does not include a built-in permission system for restricting filesystem, process, network, or credential access. By default, it runs with the permissions of the user and process that launched it. ``` Source: https://github.com/earendil-works/pi Pi's own README, before it lists any way to add isolation around the process. [Try Kortix](https://kortix.com) ## What a harness is A harness is the loop that turns a model into an agent. It builds a request from the system prompt and the conversation, sends it to the model, reads the tool calls that come back, runs them and records the results. Pi describes itself in one sentence: [Pi is a minimal agent harness](https://pi.dev/). Model, harness, framework and runtime get used as if they were one thing. They are four layers, and each answers a different question. - **Model.** The network that predicts tokens. It cannot read a file or run a command. It can ask for one. - **Harness.** The loop and the tool surface that turn those requests into actions, plus the transcript it writes. - **Framework.** A library you import to write that loop yourself, with your own tools, retries and state. - **Runtime.** The machine a session runs on, the rules on which tools may run there, and what happens to the work at the end. Kortix's docs use the word runtime for the harness itself: "A harness is the agent runtime inside a session's sandbox. It runs the model loop, calls tools and writes the transcript." That sentence stops at the sandbox wall. Everything outside it, from the machine image to the person who merges the branch, is the runtime a team actually manages. The model and the harness decide what a session can do. The runtime decides whether a team can leave it running. ## What Pi's harness actually does The loop is short enough to describe in a paragraph. A message lands on the active branch, Pi builds a request from the system prompt, that branch, the available tools and the model settings, and the provider streams back text and tool calls. Pi records the response, runs each tool call and records the result. A turn ends there, and another starts only if the results or the queue ask for one. ### Four tools, four modes Pi enables four built-in tools by default: read, bash, edit and write. Almost everything else a coding agent does, from running a test suite to calling an internal API, arrives through bash or through an extension someone installed. Pi runs in four modes: interactive, print/JSON, RPC and SDK. Print mode is `pi -p "query"`, JSON mode writes agent events as JSONL, RPC speaks JSONL over stdin and stdout, and the SDK creates sessions in process. That reach is why Pi turns up inside other tools as well as in a terminal. ### Providers and context Pi reads provider keys from the environment and documents Anthropic, OpenAI, Google, Azure, Bedrock, Mistral, Groq, xAI, Hugging Face and Ollama, among others; `/model` switches mid-session. On the context side, `AGENTS.md` loads at startup from `~/.pi/agent/`, from parent directories and from the current directory, and `SYSTEM.md` replaces or appends to the system prompt. Compaction summarizes older messages as the window fills. Sessions are stored as trees in a single file, so `/tree` returns to any earlier point and the path you take from there is another branch of the same session. `/export` writes HTML and `/share` uploads a gist. A team reading a transcript later can see where a wrong turn began, then take the earlier branch instead. ## What a minimal harness hands back to you The README states the default in two sentences. [Pi's usage docs](https://pi.dev/docs/latest/usage) put the practical consequence plainly: "Pi does not ask before every tool call." On a laptop that is a fair bargain. The person at the keyboard sees each call, can stop it and reads the diff before it goes anywhere. The calculation changes on a shared machine, in CI or on a schedule, where the same default hands the model everything the process can reach. Pi's answer is to keep the core small: it ships powerful defaults and skips features like sub-agents and plan mode, and its docs list those, plus permission gates, path protection and sandboxing, as things to build or install. Pi's package catalogue has an extension for most of them. That approach works, and it moves the work of supervision onto whoever runs it. An extension runs inside the Pi process with the same operating-system permissions, so the boundary after installing one sits where it sat before. [Pi coding agent extensions](/pi-coding-agent-extensions) covers what that costs and how to choose. ## The half a harness does not ship A Kortix session puts the harness on a machine the platform owns, and the thing a team manages is the session. Every new session runs Pi, and `runtime:` in `kortix.yaml` selects nothing, so there is no harness to pick there. What gets configured is the session around the loop: a branch cut from `base_ref` and named with the `session_id`, `permission` rules that resolve each tool to `allow`, `ask` or `deny` before it runs, and a change request that a person reviews and merges. The steps are in [Kortix's session docs](https://kortix.com/docs/work/sessions). Kortix's own capability table reads as a boundary document. A Pi session serves subagents through the `task` tool, conversation compaction, project slash commands, steering mid-turn and the v2 session log. Rewind, fork, a harness-side MCP connection, a todo list, a shell turn and attaching the harness's own terminal client are listed as not served, and a request for one answers `501` with `code: "feature_not_supported"`. A request for the runtime config document answers `404`. Pi also has a tool of its own, `codemode`, where the model writes a script that calls the other tools and only the script's output returns to it. The pi-only directory, `harnesses/pi/`, holds `settings.json`, `extensions/`, `skills/` and `prompts/`, so what the harness loads can live in the repo with everything else. Those fields, and the table that names what a Pi session serves, are documented in [Kortix's docs](https://kortix.com/docs/project/agents). ## When Pi on its own is the right answer Pi on a laptop is a good tool for one developer with their own repository and their own provider keys. The loop, the four tools and a session tree are enough for that setup, and the person at the keyboard is the runtime: they watch each call, read the diff and answer for the result. The calculation changes with a second person, with a session that should outlive the laptop, or with a rule that has to hold when nobody is watching. Those are the cases [running Pi in the cloud](/run-pi-in-the-cloud) covers, and the [Pi coding agent guide](/) covers the install and the first session in a terminal. ## Harness questions, answered The three the word raises most often. ### Is a harness the same as a runtime? No. A harness is the loop that runs the model and calls its tools. The runtime is the machine that loop runs on, the rules on which tools may run there, and who reviews the result. Pi supplies the first; Kortix supplies the second. ### Is pi a harness or an agent? Pi is a harness. It runs the model loop and its tools, and an agent is what a session runs: a prompt, a model and tool rules. In Kortix those live in `agents/.md` and `kortix.yaml`. ### Does a harness need a sandbox? Yes, once it runs anything you did not write. Pi runs with the permissions of the user and process that launched it, so a sandbox is what bounds a session. In Kortix every session gets its own isolated machine. ## Run the harness where the rules live. Every new session in Kortix runs Pi on a machine the platform owns, with the permission rules and the change request around it. [Try Kortix](https://kortix.com) ยท [Run Pi in the cloud](https://picodingagentguide.com/run-pi-in-the-cloud)