OnlyHarness Registry

Official9 toolsLive

by elvismusli · TypeScript

Search, inspect, pull and publish reusable AI-agent harnesses from onlyharness.com.

Topics

agent-harnessai-agentsfastifyreactsupabaseviteonlyharness

Captured live from the server via tools/list.

search_harnesses

Search the OnlyHarness registry by task, job, title, summary or tag.

Parameters

query	string	optional	Search terms such as market research, support triage or finance safety.
limit	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Search terms such as market research, support triage or finance safety.",
      "default": "",
      "type": "string"
    },
    "limit": {
      "default": 10,
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

harness_detail

Return manifest, trust signals, example and file list for one harness.

Parameters

owner	string	optional
name	string	required	Harness slug, for example deep-market-researcher.

Raw schema

{
  "type": "object",
  "properties": {
    "owner": {
      "default": "harnesses",
      "type": "string"
    },
    "name": {
      "description": "Harness slug, for example deep-market-researcher.",
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

search_resources

Search mixed source-aware resources: harnesses, skills, plugins, workflows, MCP servers, configs, guides, runtimes and directories.

Parameters

query	string	optional	Search terms such as superpowers, MCP browser, workflow or Claude skill.
q	string	optional	Alias for query, matching the HTTP /resources?q= contract.
type	string	optional	Optional resource type filter, for example skill, plugin, workflow, mcp_server or harness.
worksWith	string	optional	Optional compatibility filter: claude-code, codex, cursor, mcp, cli or github.
limit	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Search terms such as superpowers, MCP browser, workflow or Claude skill.",
      "default": "",
      "type": "string"
    },
    "q": {
      "description": "Alias for query, matching the HTTP /resources?q= contract.",
      "type": "string"
    },
    "type": {
      "description": "Optional resource type filter, for example skill, plugin, workflow, mcp_server or harness.",
      "type": "string"
    },
    "worksWith": {
      "description": "Optional compatibility filter: claude-code, codex, cursor, mcp, cli or github.",
      "type": "string"
    },
    "limit": {
      "default": 10,
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

resource_detail

Return provenance, trust, popularity and actions for one mixed resource.

Parameters

string

required

Resource id, for example github:obra/superpowers or onlyharness:harnesses/deep-market-researcher.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "description": "Resource id, for example github:obra/superpowers or onlyharness:harnesses/deep-market-researcher.",
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

resource_use_instructions

Return the best safe next action for a mixed resource without trying to pull non-harness archive files.

Parameters

string

required

Resource id, for example github:obra/superpowers.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "description": "Resource id, for example github:obra/superpowers.",
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

pull_instructions

Return CLI and HTTP commands for pulling a harness into a local workspace.

Parameters

owner	string	optional
name	string	required

Raw schema

{
  "type": "object",
  "properties": {
    "owner": {
      "default": "harnesses",
      "type": "string"
    },
    "name": {
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

pull_harness

Return archive files for a harness. Paid harnesses return payment requirements unless the Bearer token is entitled.

Parameters

owner	string	optional
name	string	required
version	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "owner": {
      "default": "harnesses",
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "version": {
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

search_docs

Search /llms.txt and agent guidance for API, CLI, MCP and safety instructions.

Parameters

query

string

optional

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "default": "",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

publish_markdown_to_harness

Convert markdown into an unverified harness scaffold. Requires an OnlyHarness Bearer token.

Parameters

name	string	optional
markdown	string	required

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "markdown": {
      "type": "string",
      "minLength": 20
    }
  },
  "required": [
    "markdown"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

README.md17 KBView on GitHub

OnlyHarness

onlyharness.com is a friendly hub for reusable AI-agent harnesses: browse workflows, try examples, read the thread, create local remix drafts, star, and publish with a CLI-ready trust layer.

The UI ships as OnlyHarness 98 — a deliberately playful Windows 98 / MS Paint / WordArt desktop (per design_handoff_harness_hub_98): every surface is a window, harnesses open as draggable windows with a taskbar, auth is a Log On dialog, and the share card is harness_flex.exe. Design decisions live in docs/plans/2026-07-04-win98-redesign-design.md. Internal package names still use @harnesshub/*, except the public CLI workspace/package is onlyharness.

What is a harness?

A harness is a versioned agent workflow package:

harness.yaml manifest with runtime, tools, permissions, quality gates, and risk profile.
Prompt, examples, eval cases, and expected outputs.
CLI commands for validate, eval, gate, diff, import, and PR annotation.
Social layer: stars, server-side remix forks, threads, verified gate runs, install confirms, heat, tags, outcomes, and maintainer review.

Live MVP

App: https://onlyharness.com
API health: https://onlyharness.com/api/healthz
Registry API: https://onlyharness.com/api/registry

Supabase auth is enabled for signup/login, stars, local remix drafts, thread posts, and authenticated publish.

Features

HuggingFace-style discovery for agent harnesses, wrapped in a Win98 desktop with a real window manager (drag, minimize, z-order, taskbar, Start menu).
Outcome filters, global search, leaderboard, Harness Heat, stars, server-side remix fork counters, threads, and verified gate-run counters.
Harness detail opens as its own window with Overview, Install, Trust, Try sample, Thread, Files, and Versions tabs plus a plain-tone trust panel; Versions is backed by archive snapshot history.
Authenticated publish flow (New Harness Wizard) that imports markdown into a harness scaffold.
Share card window (harness_flex.exe), Wild West awards, Paint heat chart, and a paperclip mascot that opens the wizard.
CLI package onlyharness with hh search, hh suggest, hh pull, hh run, hh publish, hh doctor, hh audit-setup, hh benchmark, hh extract, hh setup @org, hh validate, hh inspect, hh risk, hh diff, hh eval, hh gate, hh pin, hh outdated, hh update, hh import-md, and hh annotate-pr (HH_REGISTRY_URL targets any registry, default https://onlyharness.com/api).
Agent-friendly discovery: /llms.txt, /api/openapi.json, /server.json, and /mcp document the HTTP/MCP surfaces so an AI agent can find and pull a harness without a browser.
Local bounty flow: create/claim/deliver/accept work-state over the existing gate_escrow rail; paid is set only after a matching escrow purchase captures against the delivered gate receipt.
Semantic PR review and quality gate sidecar API.
Docker production stack with system Caddy deployment mode for shared VPS hosts.

Architecture

flowchart LR
  Web["React/Vite UI"] --> API["Fastify Harness API"]
  API --> Seeds["Seed harnesses"]
  API --> Imports["Imported harnesses"]
  Web --> Supabase["Supabase Auth + RLS tables"]
  API --> SupabaseAuth["Supabase token verification"]
  Caddy["System Caddy / onlyharness.com"] --> Web
  CLI["hh CLI"] --> Schema["Schema, eval, gate, diff"]

Run locally

bash

npm install
npm run seed
npm run check
npm run smoke
npm run dev

Open:

UI: http://127.0.0.1:5177
API: http://127.0.0.1:8787/healthz
Local Gitea forge: http://127.0.0.1:3000

Operator Payouts

Payout reporting and ledger creation are manual-ops only. The script reads settled purchases plus payout_accounts, applies the current rates, and can create an idempotent draft payout ledger. It never calls a payout provider and never marks items paid.

bash

npm run payout:report -- --month 2026-07
npm run payout:report -- --month 2026-07 --json
npm run payout:ledger -- --month 2026-07 --ledger-out data/payout-ledgers/2026-07.json

Use SUPABASE_URL + SUPABASE_SERVICE_ROLE_KEY, or local JSON fixtures via --purchases and --payout-accounts. --record-ledger upserts payout_runs/payout_items through Supabase service role. Rows without creator_user_id are marked MISSING_CREATOR_ID; rows without payout account are blocked as MISSING_PAYOUT_ACCOUNT.

CLI

After the npm package is published:

bash

npx onlyharness search market research
npx onlyharness suggest market research --json
npx onlyharness install harnesses/deep-market-researcher --target claude-code --json
npx onlyharness mcp-config deep-market-researcher --target claude-desktop --json
npm i -g onlyharness   # installs the `hh` command

This local branch prepares the onlyharness npm bundle but does not publish it. For local development, build the workspace bundle and run it directly:

bash

npm run build -w onlyharness
node packages/harness-cli/dist/hh.mjs doctor
node packages/harness-cli/dist/hh.mjs audit-setup
node packages/harness-cli/dist/hh.mjs suggest market research --apply --out suggested-deep-market-researcher --json
node packages/harness-cli/dist/hh.mjs suggest market research --apply --target codex --out suggested-deep-market-researcher --adapter-out .codex/harnesses/deep-market-researcher --json
node packages/harness-cli/dist/hh.mjs install harnesses/deep-market-researcher --target codex --out deep-market-researcher --adapter-out .codex/harnesses/deep-market-researcher --json
node packages/harness-cli/dist/hh.mjs pull harnesses/deep-market-researcher --version 0.1.0 --out deep-market-researcher-0.1.0 --json
node packages/harness-cli/dist/hh.mjs mcp-config deep-market-researcher --target claude-desktop --out mcp.json
node packages/harness-cli/dist/hh.mjs benchmark benchmarks/research-discovery.yaml --json
node packages/harness-cli/dist/hh.mjs extract ~/.claude/skills/my-skill --out my-skill-harness
HH_TOKEN=<token> node packages/harness-cli/dist/hh.mjs publish git@github.com:acme/harnesses.git --path harnesses/my-harness --name my-harness --json
HH_ORG_TOKEN=<org-token> node packages/harness-cli/dist/hh.mjs setup @acme
HH_ORG_TOKEN=<org-token> node packages/harness-cli/dist/hh.mjs publish workflow.md --org acme --name my-private-harness
HH_ORG_TOKEN=<org-token> node packages/harness-cli/dist/hh.mjs sync git@github.com:acme/skills.git --org acme
TELEGRAM_BOT_TOKEN=<bot-token> HH_ORG_TOKEN=<org-token> TELEGRAM_CHANNEL_ID=<channel-id> npm run telegram:gate-bot

For agents

Discovery: /llms.txt, /AGENTS.md, /api/openapi.json, MCP Registry metadata at /server.json, OAuth protected-resource metadata at /.well-known/oauth-protected-resource, and authorization-server metadata at /.well-known/oauth-authorization-server.
MCP: https://onlyharness.com/mcp with search_harnesses, harness_detail, pull_instructions, pull_harness, search_docs, and publish_markdown_to_harness. harness_detail/pull_instructions expose read-only access/payment state; only pull_harness/archive delivery returns files after entitlement.
Registry publish: server.json is remote-only (com.onlyharness/registry) and ready for MCP Registry domain auth; publish still requires a DNS/HTTP ownership proof for onlyharness.com.
Team setup and publish: hh setup @acme reads GET /api/orgs/{slug}/bundle; hh publish --org acme writes an org-private harness. Both use HH_ORG_TOKEN when ORGS_ENABLED=true. Org auth/bundles/audit read Supabase service-role tables first and keep HARNESS_ORGS_PATH/HARNESS_ORG_AUDIT_PATH as the local smoke fallback.
Team workspace UI/API: Network Neighborhood uses GET /api/orgs/{slug}/workspace with the same org token and returns org-private cards, sanitized audit rows, and a permission/risk summary.
Team git sync: hh sync <git-url-or-local-path> --org acme clones/scans markdown skills and runbooks, then imports them through the org publish endpoint. First version has no webhooks.
Maintainer publish: hh publish <harness-dir> requires local .harnesshub/results.json; hh publish <git-url> --path <harness-dir> clones to a temp dir, runs local eval/gate there, then publishes only if the server rechecks schema, security and gate successfully.
Org-private pulls use the same token path: HH_ORG_TOKEN=<org-token> hh pull @acme/private-harness.
Directory shelf entries are link-only discovery indexes under owner directories. They show open <url> in search results and GET /api/repos/directories/{name}/archive returns 409 DIRECTORY_LINK_ONLY instead of runnable files.
Server-side remix is a local draft flow with a real fork graph row: POST /api/repos/{owner}/{repo}/remixes creates a free unverified local/{name} copy from archive files only and records the source -> fork edge. Paid, org/private, directory, link-only and unspecified-license sources fail closed; copied fallback recipes do not increment forks or store prompts/local paths.
Public API payloads never expose server filesystem paths: registry/detail use public forge/upstream URLs when available, /healthz only returns status, and maintainer review in detail is explicitly a local-demo preview until a real forge PR source is connected.
Category benchmark infrastructure is local-first: hh benchmark <suite.yaml> compares candidate and analog harnesses from local paths using declared eval case scores. Suites live in benchmarks/, smoke runs every YAML suite there, and this remains a runner/comparison layer, not an independent LLM quality measurement.
Agent autopilot: hh suggest <task> --json searches, returns ranked candidates with trust fields, fetches detail for the selected harness, prints a full trust summary, and records a privacy-safe suggested event. Use --pick <rank> to inspect/apply another candidate. hh suggest <task> --apply --out <dir> installs the selected harness through the same archive path as hh pull, records accepted when --apply is chosen, and records applied only after files are written. Add --target cli|claude-code|codex|cursor to run the full adapter install path before applied.
Versioned archives: harness detail includes versions[]; hh pull owner/name --version <semver> and hh install owner/name --version <semver> request the same immutable /archive?version= path and keep .harnesshub/source.json pinned to the resolved version.
hh eval and hh gate record privacy-safe eval/gate events for pulled harnesses when they pass; detail payloads expose verification.lastVerifiedAt from those events. Registry runs are counted only from passed gate events, never from hh run sample preview.
hh gate --receipt writes a signed gate receipt with harness ref, version, resultsHash, verdict and timestamp. POST /api/receipts verifies the ed25519 signature only; it is side-effect-free and does not store prompts, local paths, payments or entitlements.
Gate escrow is reserved-first: pricing.model: gate_escrow checkout/webhook creates reserved plus an expiring escrow_reserved archive entitlement. POST /api/billing/escrow/receipt captures on a valid passing receipt or refunds on a valid failing receipt; POST /api/billing/escrow/timeout refunds after the 72h window.
Bounties are work-state over the same escrow rail: /api/bounties* supports create, claim, deliver and accept; accept verifies the delivered receipt, escrow target, amount and currency, blocks escrow reuse, and writes paid only after capture.
Hosted endpoints are not live yet: hh run executes locally as sample preview only, and HTTP/MCP surfaces deliver harness files rather than running author code server-side. pricing.model=per_call returns 409 HOSTED_EXECUTION_NOT_AVAILABLE until a runner/partner path is shipped and smoked.
Paid installs/pulls return 402 until entitled. When PAYMENTS_ENABLED=true, X402_ENABLED=true, and X402_PAY_TO is set, the archive response also includes an x402 v2 PAYMENT-REQUIRED header. Successful hh install --pay or hh pull --pay archive delivery requires X402_FACILITATOR_URL to verify/settle and then grants a wallet entitlement.
Checkout URLs land on /checkout: without provider_ref the web UI asks the buyer to log on and create a manual checkout session; with provider_ref it shows a pending manual handoff. Neither state grants access client-side.
Manual checkout is the only enabled checkout provider (PAYMENT_PROVIDER unset or manual). Any other provider value fails closed before creating a purchase; x402 remains a separate archive-payment rail.
Buyer receipts are read-only: GET /api/billing/receipt?provider_ref=<ref> returns the authenticated user's pending/paid purchase status and entitlement flag, but never settles providers or grants access.
Bot gates can call GET /api/entitlements/check?subject=user:<id>&harness=owner/name with an org token that has entitlements:read; this returns a decision only, never archive files.
Safer community gates use short-lived signed codes: the buyer calls POST /api/community/invite-code after entitlement, then the Telegram/Discord bot calls POST /api/community/verify-code with a scoped org token before granting access. COMMUNITY_INVITE_SECRET must be configured on the API.
Registry items include installConfirms; only authenticated kind=install&client=claude-code events count toward the works in Claude Code: N confirms badge.
Claude Code plugin: claude plugin marketplace add elvismusli/onlyharness then claude plugin install onlyharness@onlyharness.
Codex MCP setup: codex mcp add onlyharness --url https://onlyharness.com/mcp --bearer-token-env-var HH_TOKEN.
Local validation: npm run check:mcp-registry && npm run check:plugin; when Claude CLI is installed, also run claude plugin validate . && claude plugin validate plugins/onlyharness.

Create local env from the examples:

bash

cp .env.example .env.local
cp .env.example apps/registry-web/.env.local

Production deploy

The current VPS uses a shared system Caddy on ports 80/443. OnlyHarness runs behind it on 127.0.0.1:8097.

bash

SSH_TARGET=hetzner-root DEPLOY_MODE=system-caddy scripts/deploy-production.sh

scripts/deploy-production.sh runs public smoke by default after containers reload: /api/healthz, /server.json, /.well-known/oauth-protected-resource, /.well-known/oauth-authorization-server, /checkout, and /mcp. Override PUBLIC_BASE_URL for a non-default hostname or set RUN_DEPLOY_SMOKE=0 only for a deliberately partial deploy. For authenticated production smoke without creating throwaway users, set ONLYHARNESS_QA_EMAIL and ONLYHARNESS_QA_PASSWORD in the ignored production env and run scripts/smoke-production-auth.ts against https://onlyharness.com/api.

Deployment artifacts:

infra/production-compose.yml
infra/production-system-caddy.override.yml
infra/Caddyfile.local-smoke
scripts/deploy-production.sh
scripts/smoke-production-compose.sh
scripts/smoke-production-auth.ts

Production smoke:

bash

scripts/smoke-production-compose.sh

set -a
. infra/production.env
set +a
SMOKE_API_URL=https://onlyharness.com/api SMOKE_EXPECT_EMAIL_CONFIRMATION=1 npm run smoke:prod-auth

Verification

Current verification gates:

bash

npm run build
npm run check
npm run smoke
npm run smoke:mcp
npm run smoke:x402
scripts/smoke-production-compose.sh

The production auth smoke creates a QA Supabase user and verifies that email confirmation blocks immediate sign-in. To test authenticated publish with a pre-confirmed token, pass HH_TOKEN to the CLI publish flow or run the API publish smoke against a confirmed session.

Repository Layout

text

apps/
  harness-api/       Fastify API and registry endpoints
  registry-web/      React/Vite OnlyHarness UI
packages/
  cli/               hh CLI
  schema/            harness.yaml schema, validation, risk checks
  semantic-diff/     harness semantic diff and PR review markdown
seed-harnesses/      curated MVP harness examples
supabase/            auth/social/thread schema migrations
infra/               Docker, Caddy, Gitea, and production compose
scripts/             seed, smoke, deploy, Gitea proof scripts

Security Notes

Real .env.local, app env, and infra/production.env files are gitignored.
Publish requires a valid Supabase bearer token in production.
Internal webhook/eval endpoints require HARNESS_WEBHOOK_TOKEN when configured.
Organization setup is behind ORGS_ENABLED; org tokens are stored as sha256: hashes in Supabase or the local fallback store, and audit logs must not contain raw tokens.
Supabase tables use RLS policies for profiles, user actions, and thread posts.

Install

Tools (9)

search_harnessesharness_detailsearch_resourcesresource_detailresource_use_instructionspull_instructionspull_harnesssearch_docs

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://onlyharness.com/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "registry": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://onlyharness.com/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.