Status: v1 Schema layer — candidate
The Harness Protocol is an open specification for portable AI coding harnesses — a vendor-neutral harness.yaml format that captures the complete operational context for an AI coding agent: plugins, skills, MCP servers, environment requirements, behavioral instructions, permissions, and governance policy. It is to AI coding harnesses what the Model Context Protocol (MCP) is to tool communication.
AI coding tools like Claude Code, Cursor, and GitHub Copilot each have their own proprietary formats for capturing agent context. A developer who crafts a well-tuned configuration for one tool cannot share it with a teammate on a different tool, publish it for their team to reuse, or carry it when they switch tools. The Harness Protocol defines a common format so that harness configurations become portable, shareable artifacts — the same way MCP made tool communication portable.
The specification is organized into three layers, each building on the previous.
| Layer | Description | Status |
|---|---|---|
| Schema | The harness.yaml format, JSON Schema validation, security model, plugin manifest | v1 — current |
| Exchange | Harness-to-harness sharing: publish, fetch, and compose harnesses across tools and teams | v2 — accepted (HEP-7) |
| Registry | Hosted discovery at harnessprotocol.io: search, publish, version resolution, integrity verification | v2/v3 — draft (HEP-8) |
Layers are intentionally decoupled. A tool can implement Schema-layer validation today without any dependency on exchange or registry infrastructure.
A harness profile is a YAML file validated against the Harness Protocol JSON Schema. The minimal valid profile:
$schema: https://harnessprotocol.io/schema/v1/harness.schema.jsonversion: "1"metadata:
name: my-harnessdescription: A minimal valid Harness Protocol v1 profile.A fuller example showing common fields:
$schema: https://harnessprotocol.io/schema/v1/harness.schema.jsonversion: "1"metadata:
name: data-engineerdescription: Harness for data engineering work in Go and SQL.author:
name: acme-orgplugins:
- name: sql-explorersource: acme-org/sql-explorerversion: "^1.2.0"integrity:
sha256: "abc123def456..."mcp-servers:
filesystem:
transport: stdiocommand: npxargs: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]env:
- name: DATABASE_URLdescription: Primary database connection stringrequired: truesensitive: trueinstructions:
operational: file://./instructions/operational.mdimport-mode: mergepermissions:
tools:
allow: [Read, Glob, Grep, Write, Edit]deny: ["mcp__*__drop_*"]The full field reference is in protocol/profile-schema.md. The JSON Schema is the authoritative validation source.
harness-kit is the reference implementation of the Harness Protocol. It provides a parser, validator, plugin loader, MCP server lifecycle manager, and CLI for working with harness.yaml profiles. Start there to use the protocol today.
Conformance does not require harness-kit — any implementation that correctly validates and applies harness.yaml per this specification is conformant.
Full documentation is available at harnessprotocol.io/spec.
| Document | Content |
|---|---|
| protocol/overview.md | What the protocol is and how the layers fit together |
| protocol/terminology.md | Glossary of all terms used in the spec |
| protocol/architecture.md | System diagram, layer interactions, trust model |
| protocol/profile-schema.md | Full harness.yaml field reference |
| protocol/plugin-manifest.md | plugin.json format for plugin authors |
| protocol/mcp-declarations.md | MCP server transport types, variable substitution, security |
| protocol/instructions.md | Instruction slots, content sources, import modes |
| protocol/environment.md | Environment variable declarations and sensitive data handling |
| protocol/fragments.md | kind: fragment — partial harness documents for composition |
| protocol/inheritance.md | extends resolution order and per-section merge rules |
| protocol/application.md | Application pipeline, effective configuration, error handling |
| protocol/source-resolution.md | Source resolution algorithm for owner/repo and local path references |
| protocol/exchange.md | (v2) Exchange layer — the signed offer envelope and consent-first sharing flow |
| protocol/registry.md | (v2 draft) Registry layer — hosted discovery, integrity hashing, and the transparency log |
| security/threat-model.md | Threat model and security design |
| security/trust-boundaries.md | Trust boundaries between spec, implementations, profiles, and remote content |
| security/secrets.md | Sensitive variable handling and secrets patterns |
| security/permissions.md | Permission model and enforcement |
| security/integrity.md | Content integrity verification |
| security/instruction-injection.md | Instruction injection threat and mitigations |
| security/skill-injection.md | Skill behavioral injection threat and mitigations |
| security/exchange.md | (v2) Exchange threat model — authenticity, consent, confidentiality in transit |
| security/registry.md | (v2 draft) Registry threat model — the registry is an index, not a trust anchor |
| security/crypto-map.md | How SHA-256 integrity, ed25519 (Exchange), and minisign signing compose |
Harness authors (writing harness.yaml files):
- protocol/profile-schema.md — the complete field reference
- examples/ — annotated example profiles to copy from
- schema/draft/harness.schema.json — validate your file
Tool implementers (building a harness implementation):
- protocol/overview.md — what the protocol is and how layers fit together
- protocol/architecture.md — system model and trust boundaries
- protocol/application.md — the 7-step application pipeline
- protocol/source-resolution.md — how
owner/reporeferences resolve - protocol/profile-schema.md — the normative field specification
- security/ — security model, sensitive data rules, and threat model
Spec changes go through the HEP (Harness Enhancement Proposal) process. Editorial fixes can be submitted directly as pull requests. See CONTRIBUTING.md for the full process.
See SECURITY.md for the security policy and responsible disclosure process.
Apache License 2.0. See LICENSE.