harness.md Frontmatter Reference

harness.md is the root artifact of every AI Harness project. It is a Markdown file with a YAML frontmatter block: the frontmatter declares the runtime configuration; the body becomes the system prompt.

This page is the exhaustive reference for every field the loader recognizes, the type and default for each, and a worked example for the non-obvious ones.

Versioning note. Every field documented on this page is part of the stable harness configuration surface under SemVer. Fields marked experimental may change; new optional fields may be added in minor releases without breaking existing files.

File shape

---
# YAML frontmatter — runtime configuration
model:
  provider: copilot
  name: gpt-4o
context:
  max_history: 50
delegation:
  max_depth: 2
---

# Markdown body — becomes the system prompt

You are a careful assistant. ...

Rules enforced by the loader (config.LoadMarkdown in config/markdown.go):

1. The file must start with a --- delimiter line.
2. The frontmatter must be closed by a second --- on its own line.
3. The body after the closing delimiter is the system prompt. If empty, no system prompt is set from this file.
4. Frontmatter is parsed as YAML. Unknown top-level keys are ignored silently — typos in field names produce no error. Use harness validate to confirm the runtime sees what you expect.

harness.md may also be supplied as plain harness.yaml / harness.yml for environments where Markdown is awkward; the schema is identical and no system prompt is read from the file.

Top-level fields

The minimal valid frontmatter is an empty block — defaults will fill in a working gpt-4o profile against the GitHub Copilot endpoint, provided GITHUB_TOKEN is set in the environment.

model

The primary completion model. Exactly one model block is active per turn; if models is also set, it becomes a routing table (see models).

model:
  provider: copilot
  name: gpt-4o
  max_tokens: 4096
  temperature: 0.3
  base_url: https://api.githubcopilot.com
  api_key_env: GH_TOKEN
  retry:
    max_retries: 3
    initial_backoff_ms: 250
    max_backoff_ms: 8000
    multiplier: 2.0

retry

Retry policy applied to model completion calls (not tool calls). All fields optional; absent fields fall back to harness-level defaults.

Retry kicks in for transient completion errors and finish_reason=length truncation (see PR #121). finish_reason=content_filter is a hard error and is not retried.

models

An optional list of additional model profiles available at runtime.

models:
  - name: gpt-4o
    provider: copilot
    api_key_env: GH_TOKEN
    retry:
      max_retries: 3
  - name: gpt-4o-mini
    provider: copilot
    api_key_env: GH_TOKEN

Each entry has the same schema as model. The first entry is the default at boot; sub-agents and tools may switch profiles by name. When models is empty, the single model block is the only profile.

context

Context-window management.

context:
  max_history: 50
  max_tokens: 64000
  system_prompt: ""

Setting system_prompt in frontmatter is supported for .yaml configs and for tests; in .md files prefer writing the prompt as the body.

tools

Inline tool definitions. Each entry registers one tool with a single harness.md-resident Starlark script. Most projects keep tools as separate artifacts in .harness/tools/<name>.md instead — see Tool Artifact Schema — but the inline form remains supported for small examples and tests.

tools:
  - name: echo
    description: Echo a message back.
    timeout_ms: 1000
    parameters:
      message:
        type: string
        description: What to echo
        required: true
    script: |
      def run(message):
          return message

param

tools_policy

Declarative governance over which registered tools the agent may invoke. Patterns are shell-style globs evaluated against tool names (e.g. fs.*, delegate*, web_fetch).

tools_policy:
  mode: allowlist
  allow:
    - "fs.read"
    - "fs.list"
    - "web_fetch"
    - "delegate*"
  deny:
    - "fs.remove"
    - "exec"

Policy is enforced at the registry level: a denied call never reaches the tool's Starlark script, and the OTel span is marked tool.policy=denied. See the Governance & Policy concept page.

hooks

Inline hook registrations. As with tools, most projects ship hooks as separate artifacts in .harness/hooks/<name>.md (see Hook Artifact Schema); the inline form is for small examples and tests.

hooks:
  - event: tool.pre
    handler: audit_pre
    when: 'payload["name"] == "fs.read"'
    priority: 100
    script: |
      def handle(event, payload):
          metrics.incr("audit.read")
          return {"action": "allow"}

Recognized event names (full list in Hook Artifact Schema):

• tool.pre, tool.post
• completion.pre, completion.post
• delegate.pre, delegate.post
• agent.start, agent.turn, agent.stop

delegation

Sub-agent delegation budget.

delegation:
  max_depth: 2
  max_concurrent: 4
  iterations_per_depth: [12, 6]

When iterations_per_depth has fewer entries than max_depth, the last entry is reused for deeper levels.

meta

Configuration for the meta.* Starlark built-ins (self-augmenting agents). All fields are required when meta is present.

meta:
  enabled: true
  max_tools: 20
  max_hooks: 20
  max_agents: 5
  max_call_depth: 2

Dynamically registered tools are still subject to tools_policy — meta.register_tool cannot bypass governance.

serve

Declarative configuration for harness serve. Replaces the repeated --source / --telegram-* CLI flags. Secrets are never embedded — each source references an env var via token_env.

serve:
  sources:
    - type: stdin
    - type: telegram
      token_env: TELEGRAM_BOT_TOKEN
      poll_timeout_seconds: 25
      chat_allowlist: [7729308746]
      offset_path: ./.harness/state/telegram-offset.json
    - type: meshwire
      token_env: MESHWIRE_TOKEN
      mesh_id: family-mesh
      agent_id: harness-bot
      sender_allowlist: [peer-reviewer]
      poll_timeout_seconds: 30
      base_url: https://meshwire.io

serve.sources must contain at least one entry. Duplicate types are not supported in v1. Unknown type values produce a validation error so a stale binary running newer config fails loudly instead of silently dropping sources.

Per-source fields

type: stdin

No required fields. Reads prompts from standard input; emits replies to standard output. Equivalent to harness run but participates in the multi-source dispatch loop.

type: telegram

type: meshwire

network

Network sandbox enforced by the http.* Starlark built-ins.

network:
  allowed_domains:
    - api.github.com
    - "*.example.com"

When network is omitted (or allowed_domains is empty), scripts may reach any host. This preserves backward compatibility with pre-5.5 configs. See the Network Sandboxing guide for full matching rules.

Defaults summary

The loader applies these defaults before validation:

Validation

harness validate runs the same checks the runtime applies at boot:

• model.name non-empty
• model.temperature in [0, 2]
• model.max_tokens > 0
• tool.timeout_ms >= 0
• No duplicate tool names
• Every hook event is a recognized event
• tools_policy.mode (if set) is allowlist or denylist
• All tools_policy.allow / deny entries are non-empty strings
• serve.sources non-empty when serve is present, with per-source required fields enforced
• model.retry and per-models[i].retry field bounds (max_retries >= 0, backoffs >= 0, multiplier >= 0)

Validation errors are joined into one message: each individual issue is listed so a CI run shows everything wrong in one pass.

Worked example

The flagship governed-agent example ships a complete harness.md exercising every governance primitive. Use it as the copy-paste baseline:

• Two models profiles (primary + cheap fallback)
• tools_policy allowlist with explicit denies
• delegation budget with per-depth iteration caps
• meta enabled with caps
• Companion artifacts under .harness/tools/ and .harness/hooks/

See also

• Tool Artifact Schema — the per-tool .md shape
• Hook Artifact Schema — the per-hook .md shape
• Starlark Built-ins — what scripts can call
• CLI Reference — flags and env vars that interact with this file
• Governance & Policy — how tools_policy and hooks compose
• Network Sandboxing — full network.allowed_domains matching rules