# Harness Engineering Guide: A Structured Reference for Building AI Agent Runtimes > The Harness Engineering Guide is an open reference from Nexu covering the design of AI agent harnesses, from the basic agentic loop to multi-agent orchestration, context engineering, and production deployment patterns. Each article includes runnable code examples, and the guide is published at harness-guide.com alongside the GitHub repository. **nexu-io/harness-engineering-guide** — 🔧 The open guide to Harness Engineering — concepts, tutorials, papers, tools, and resources for building and managing AI agent runtimes. - Repository: https://github.com/nexu-io/harness-engineering-guide - Stars: 661 · Forks: 83 - Language: TypeScript - License: MIT - Published: 2026-09-10 · Updated: 2026-09-10 · Language: en - Canonical page: https://hysenlabs.com/projects/nexu-io-harness-engineering-guide ## What a Harness Is and Why This Guide Exists The README defines a harness as 'the runtime wrapper that turns a bare language model into an agent.' A language model on its own can generate text; a harness adds the infrastructure that makes it agentic: tool execution, memory management, context assembly, and safety enforcement. The guide covers this from the perspective of engineers who want to build harnesses rather than use pre-packaged agent frameworks. Nexu, the organization behind the guide, describes itself as building an open-source Claude Co-worker and Managed Agent platform. The guide is the public documentation of the concepts underlying that work. This origin shapes the content: articles like the Managed Agents Architecture piece, the Classifier-Based Permissions article, and the Sub-Agent and Multi-Agent Orchestration sections reflect patterns that appear in production agent systems rather than pedagogical simplifications. The guide is hosted at harness-guide.com and available in both English and Chinese. It uses a GitHub repository as the canonical source, with `guide/` for English articles and `zh-guide/` for Chinese translations. ## Repository Structure and How to Navigate It The repository is organized into four areas. The `guide/` directory holds the English articles as Markdown files, one per topic. The `zh-guide/` directory mirrors the structure in Chinese. The `site/` directory contains the tooling to publish the content to harness-guide.com. The `skills/` directory holds a SKILL.md file that packages the guide as an installable skill for AI coding agents. The Getting Started section covers three articles: what a harness is, building a working harness in 50 lines of Python, and a comparison of raw harnesses versus frameworks like LangChain or CrewAI with a decision tree. The Core Concepts section covers the agentic loop (including turn budgets, parallel tool calls, loop detection, and streaming), the tool system (tool registry, static versus dynamic loading, MCP protocol), memory and context (context assembly, session management, two-tier memory, AGENTS.md and MEMORY.md patterns), and guardrails (permission models, trust boundaries, sandboxing, prompt injection defense). The Practice section includes context engineering, sandbox configuration, skill systems, sub-agent patterns, error handling, multi-agent orchestration, scheduling, long-running harness design, managed agent architecture, eval infrastructure noise, classifier-based permissions, eval awareness, agent teams, and the initializer plus coding agent pattern. The Reference section holds an implementation comparison and a glossary. ## Building Your First Harness: The Guide's Starting Point The guide's `guide/your-first-harness.md` article promises a working harness in 50 lines of Python with complete, runnable code. According to the README, the full code is presented so readers can copy and run it directly. This is the stated design principle for the entire guide: every article includes real code examples, not pseudocode. The `guide/harness-vs-framework.md` article addresses a decision that engineers face early: when to write a raw harness versus adopting LangChain, CrewAI, or similar orchestration frameworks. The README describes this article as including a decision tree and a side-by-side code comparison. This comparison is useful because the tradeoffs between a raw harness (more control, more code) and a framework (faster start, more constraints) are not purely technical; they depend on the use case, team familiarity, and how much the agent's behavior needs to be customized. The guide's Showcase section includes two case studies from Nexu's own engineering work: rebuilding an Electron packaging pipeline that reduced build time from 15 minutes to 4 minutes and install time from 10 minutes to 2 minutes, and a post-mortem on over 1,000 ghost accounts that drained a platform in 15 days. These are operational articles rather than abstract tutorials. ## Coverage of Production Patterns: Context, Sandboxing, and Orchestration Several articles in the Practice section address production-grade concerns that beginner tutorials skip. The context engineering article covers priority-based context assembly, three lines of defense for compression, and token budgeting. Token budget management is a practical constraint in long-running agents: without it, context windows fill and the agent's behavior degrades or the call fails. The sandbox article covers Docker and Firecracker setups, network isolation, and filesystem restrictions. Sandboxing is necessary when an agent can execute code or run system commands; without it, a prompt injection that causes the agent to run malicious code affects the host system directly. The article distinguishes between Docker-level isolation (fast to set up, coarser boundary) and Firecracker (microVM, stronger isolation, higher overhead). The multi-agent orchestration article covers pipeline, fan-out, and supervisor patterns, with context isolation and real-world examples from Multica, Paseo, and OpenClaw. The agent teams article describes an experiment where 16 parallel Claude agents built a 100K-line C compiler, using a Ralph-loop coordination mechanism, git-based work sharing, and GCC as an oracle for correctness checking. These concrete case studies make the orchestration patterns easier to evaluate against specific workloads. ## Limitations: Snapshot Coverage and No Tutorial Progression The guide covers a wide range of topics but does not provide a structured tutorial progression. Articles are organized by topic, not by difficulty or dependency. A developer reading the guide linearly from Getting Started to Practice to Reference may find some Practice articles require background that is not explicitly built up in the earlier sections. The guide's articles reflect the state of harness engineering as of their writing. The last push to the repository was on 2026-04-19. The content on specific implementations (OpenClaw, Codex, Claude Code, Cursor, Cline, Aider in the comparison article) reflects those tools' architectures at that time. Implementations evolve; the comparison article should be treated as a snapshot rather than a current benchmark. LangChain and CrewAI are discussed as alternatives in the harness versus framework article. LangChain is a large framework for building LLM applications with a wide tool ecosystem; CrewAI focuses on multi-agent role-based coordination. Both are different in character from a raw harness: they provide abstracted orchestration at the cost of reduced transparency into what the agent is doing at each step. The guide's position is that raw harnesses are the right choice when the agent's behavior needs precise control, and frameworks are the right choice when speed of development matters more than control. ## How to Use the Repository and Contribute The guide is available at harness-guide.com in English and at harness-guide.com/zh/ in Chinese. The GitHub repository at github.com/nexu-io/harness-engineering-guide is the canonical source, with English articles in `guide/` and Chinese articles in `zh-guide/`. The changelog for each language is in the `changelog/` and `zh-changelog/` directories respectively. Contributing works through two paths. Opening an issue with the 'Submit a Resource' template takes the contributor through a structured form for title, URL, and relevance. Direct pull requests to the guide articles are also accepted; the CONTRIBUTING.md file documents the process. The repository's `skills/` directory contains a SKILL.md file that packages the guide as an installable skill for AI coding agents. An agent with the skill installed can retrieve guide content and answer questions about harness engineering patterns without switching to a browser. Clone the repository to read the guide articles locally: ```bash git clone https://github.com/nexu-io/harness-engineering-guide ``` This downloads the guide/ directory with all English Markdown articles and the zh-guide/ directory with the Chinese versions. The site/ directory holds the publishing tooling. After cloning, open any article in guide/ directly; for example, guide/your-first-harness.md contains the 50-line Python harness example. The README includes a BibTeX citation entry for academic attribution, naming the Nexu Team as author and the year 2026. The guide is licensed under MIT. Community discussion is available through GitHub Discussions, Twitter at @nexudotio, and a Feishu group for the Harness Engineering topic. ## Conclusion The Harness Engineering Guide is a practical starting point for developers building AI agent runtimes who want structured coverage of the core topics: agentic loop design, tool registration, context management, sandboxing, and multi-agent coordination. The guide is written by Nexu, who builds agent infrastructure, so the coverage reflects operational experience rather than purely academic treatment. The last push was on 2026-04-19. Teams who need coverage of topics added after that date should check the guide's changelog files (`changelog/` and `zh-changelog/`) to see what has been added since the initial release before relying on it as a current reference. ## FAQ ### What is harness engineering in simple terms? Harness engineering is the practice of building the runtime wrapper that turns a language model into an agent. The harness handles everything the model cannot do on its own: running tools, managing memory across turns, assembling context, and enforcing what the agent is allowed to do. ### What does a harness engineer do? A harness engineer designs and builds the infrastructure that sits between a language model and the outside world in an agent system. According to the guide, this includes the agentic loop, tool registry, context assembly, memory system, sandboxing, and safety guardrails. ### How to learn harness engineering? The Harness Engineering Guide at harness-guide.com provides structured coverage starting with what a harness is, building one in 50 lines of Python, and progressing through tool systems, memory, guardrails, sandboxing, and multi-agent orchestration. Each article includes runnable code. ### Is harness similar to GitHub? No. In this context, 'harness' refers to the runtime wrapper for an AI agent, not to GitHub or Harness the CI/CD platform. The Harness Engineering Guide covers the software architecture of AI agents, not version control or deployment pipelines. ## Sources - [Issues](https://github.com/nexu-io/harness-engineering-guide/issues) - [License: MIT](https://github.com/nexu-io/harness-engineering-guide/blob/main/LICENSE) - [nexu-io/harness-engineering-guide on GitHub](https://github.com/nexu-io/harness-engineering-guide) - [README](https://github.com/nexu-io/harness-engineering-guide/blob/main/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nexu-io-harness-engineering-guide