Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

24.6 KB
Raw Blame

The Harness Store

Everything that makes Harness more than a terminal for coding agents lives here: the contract a package keeps, the packages Autonomous maintains, the listing for packages that live elsewhere, and the tools to build and check one.

store/
  README.md        this guide: what a package is, how to build and publish one, the shelf's rules
  spec/            the contract, frozen; changes are appended to spec/CHANGES.md
  examples/hello-world/  your first harness: instructions, an HTML page, and a shared viewer
  starter/         a complete tier-0 harness to copy
  tools/           daemon-level checks: create an agent over the loopback socket, report what happened
  agents/<name>/   the built-in harnesses: an engine plus skills, toolchain, verdict, usually a pane
  viewers/<name>/  the built-in panes other packages name with viewer.use; never a tile of their own
  registry/        entries for packages that live in repositories of their own
  CANDIDATES.md    the research behind what is on the shelf, and what might come next
  PLAN.md          the first build plan, kept for its reasoning

Both a reusable Store package and its running sessions are called harnesses. A tab groups running harnesses. See the Naming System. In code and on the wire a package is still a DSH, a domain-specific harness: harness dsh …, dsh_list, cli/src/dsh/. Those names are the CLI's public contract and stay.

What a package is

A harness turns Harness into a product for one domain: PCB design, 3D CAD, a keynote, a robot in simulation. It is a folder with a manifest — a repository of its own, or one folder of a bigger one — that Harness installs on a machine. Users see it as one more tile in New Harness — pick Autonomous Circuit, choose a folder, prompt — and get the domain's skills in the agent, its toolchain on the machine, its viewer in a pane next to the terminal, and its verdict in the pane header. A viewer is the second kind of package (spec 1.1): a pane with no engine that harnesses share, so Blender and text-to-cad need not each ship a 3D viewer.

Harness never imports a package's code. It reads one manifest, copies files into the workspace, runs the commands the manifest declares, and watches one JSON file. That is the whole coupling, and it is what lets hundreds of packages exist without any of them touching the app or the CLI.

Anatomy

In the repo What it is
harness.json the manifest: id, name, category, base engine, workspace, skills, toolchain, viewer, verdict path
AGENTS.md what the engine is told in every workspace; a claude base gets a CLAUDE.md that imports it
skills/ the domain's craft as SKILL.md bundles, symlinked into the workspace so edits are live
template/ a fresh workspace, copied once into an empty folder, plus an optional init script
toolchain/setup, doctor install the domain's tools at install time; say what is missing, one line per check
viewer a loopback web server Harness runs beside the terminal; the pane is a webview on it
.harness/verdict.json the one file the domain writes and Harness reads: ready or not, findings, phases

Build one

Workspace layout is required: every DSH with a viewer opens with the viewer on the left at 70% and the real agent chat on the right at 30%. Keep both slots during loading and failed setup; show chat recovery in the chat slot. Use the shared canvas and preserve user resizing. Follow the DSH workspace contract, including its failure, reconnect, and release checks. This applies equally to native utility dashboards and web viewers.

First time? Follow Hello World: copy a tiny package, install it locally, and change a greeting in a live HTML preview. It includes the viewer in harness.json with "viewer": { "use": "autonomous/web-viewer" }. No app changes are needed.

The steps below explain the optional pieces as your harness grows. Skills, a toolchain, and a verdict are useful when your domain needs them; a first harness does not need every piece.

  1. Copy the starter. starter/ is a complete tier-0 harness: a manifest, an AGENTS.md, one skill, a template, a toolchain that installs nothing.

    cp -r store/starter store/agents/my-harness      # a built-in package, in this repository
    cp -r store/starter ~/code/my-harness            # or one that lives in a repository of its own
    

    In harness.json set id (owner/name, the install directory and the wire id), name (the tile), category (the tile's second line), engine (claude or codex), and workspace.marker (a file whose presence means the workspace is already laid out).

  2. Tell the agent its job. AGENTS.md says what the workspace is, where things go, what to do first, and how to work so the pane moves: first save within a minute, then build up, check after every pass. The craft itself goes in skills/<name>/SKILL.md: the dialect, the patterns, the commands. Skills are symlinked, so a change in your checkout is live in every workspace.

  3. Lay out the workspace. template/ is copied into an empty folder once; then workspace.init runs with the workspace as its working directory and HARNESS_DSH_DIR pointing at the install. Seed the first verdict here so the header has a state before the first prompt.

  4. Ship the toolchain with the harness. toolchain/setup.sh runs once at install, in the install directory: pin versions and vendor them there (a node_modules, a .venv), never into the user's machine. toolchain/doctor.sh exits 0 when the machine can run the harness and prints one line per check; Harness shows those lines. Point the agent at the tools through agent.env ("MARP_TOOLCHAIN": "${dsh}/toolchain"); ${dsh}, ${workspace} and ${home} expand.

  5. Write the verdict as a feed. .harness/verdict.json is written at every check and every phase change, not at the end. ready is the one machine truth; summary is the header's line; phases is how the header says "you are here".

    { "spec": 1, "ready": false, "summary": "10 slides so far · 1 warning",
      "findings": [{ "severity": "warning", "kind": "dense", "message": "slide 4 has 61 words" }],
      "artifact": "deck.md",
      "phases": [{ "id": "outline", "name": "Outline", "state": "done" },
                 { "id": "draft", "name": "Draft", "state": "active" },
                 { "id": "polish", "name": "Polish", "state": "pending" }],
      "updatedAt": "2026-09-15T23:33:00Z" }
    
  6. Add the viewer. viewer.command is a long-running process. Harness starts it with HARNESS_VIEWER_PORT, HARNESS_WORKSPACE, HARNESS_DSH_DIR and HARNESS_DSH in its environment, waits for the port to open on 127.0.0.1, then loads viewer.url in the pane (${port} and ${artifact} expand; the artifact is what the verdict names, or the newest file matching artifactExtensions). Serve files from the workspace and nothing outside it, watch the workspace, push a reload on every change, and re-run your check on every change so the header moves while the agent writes without the agent running anything. Marp's viewer does all of this in about 110 lines of Node with no dependencies beyond its renderer.

  7. Check it, install it, run it.

    harness dsh check "$PWD"               # conformance: the manifest, the scripts, the schemas
    harness dsh install "$PWD" --link      # this folder as the installed harness (a symlink)
    harness dsh doctor owner/name          # what the machine is missing, if anything
    harness dsh list                       # installed here, and what the registry offers
    

    Then New Harness, your tile, a folder, a prompt. For a check without the app, tools/dsh-e2e.mjs creates an agent over the daemon's loopback socket and reports the materialized workspace, the viewer URL, the pane's environment and the first verdict. The viewer process reads its own files when it starts; after you edit it, kill it and the daemon respawns it on the new code.

Publish a harness

Two ways, depending on where the package lives.

In this repository, as a built-in: the folder is store/agents/<name> (or store/viewers/<name>), its id autonomous/<name>, and beside harness.json a store.json with what the store page shows that a manifest does not know. The catalog publisher lists every such folder; there is no entry to write.

{ "homepage": "https://typst.app", "upstream": "https://github.com/typst/typst", "license": "MIT",
  "tagline": "Markup-based typesetting system",
  "screenshots": [],
  "examples": [{ "prompt": "A one-page invoice for Studio Nord, due in 30 days.",
                 "image": "https://raw.githubusercontent.com/autonomous-ai/openharness/main/store/showcase/typst/invoice.jpg",
                 "caption": "Invoice · 1 page PDF" }] }

tagline (≤ 80 characters) is the line under the harness's name in New Harness's agent search — "MuJoCo by Google DeepMind", then "Advanced physics simulation". Take it from the project's own website or repository, in its words, shortened only by dropping clauses. A package without one shows its category.

examples (≤ 8) is what the product page leads with: a prompt, a picture of what the harness really made from it, and a line naming the result. The page types the prompt out, reveals the picture, and "Try this prompt" opens New Harness with the prompt as the first message. Pictures live in store/showcase/<name>/, 1600×1000 JPEG under 350 KB, and are real output — never a mock-up.

An example may also carry an HTTPS video URL (≤ 2048 characters), with image as its poster. “Watch recorded run” opens the existing native web player on supported platforms, with a browser fallback. Browsing a detail page loads only its pictures; the video loads after a click, fits the whole native pane, and stops when the recording closes. Older clients keep showing the prompt and picture. The seven hands-on recordings reuse their original PNG/MP4 assets in docs/images/ rather than the JPEG convention above.

Recordings appear in the desktop Store's Featured tab. Discover keeps its illustrated editorial features. To join that collection, publish an example with both an HTTPS image poster and an HTTPS video. The first complete recording per harness is used; the card shows the harness's tagline and the recording's caption, with Watch run and Explore harness actions. Use the caption to identify the actual result and any demo limitations. The Featured tab mixes disciplines and shows the full collection; new catalog recordings join automatically on clients with this discovery UI. No per-harness desktop artwork or ID list is needed. Example prompts and captions are searchable too.

The matching recorded prompts and captions live in hands-on.json under demo. Run node store/tools/hands-on.mjs --sync-store to place each recording first in its harness's examples, preserving the others. --check verifies the pairs and local assets. Suggested starting prompts remain separate from the actual projects shown.

In a repository of its own: add store/registry/<owner>/<name>.json in a pull request.

{ "id": "owner/name", "name": "Name", "category": "Thing", "description": "One line.",
  "repo": "https://github.com/owner/name", "ref": "main", "engine": "claude",
  "tier": 2, "verified": false }

If the harness uses a shared viewer, include "viewerUse": "autonomous/web-viewer" (or the matching viewer ID) in the registry entry so the Store can show its dependencies before install. Built-in entries derive this field from the manifest automatically.

A package that is one folder of a bigger repository names it with "path"; install then fetches that folder alone. Run the conformance check and include a real example in the PR; the full test suite is currently triggered manually. Once merged, the catalog publisher lists it automatically. The app offers the tile before the package is installed. verified: true marks built-in packages; community packages show their source on install.

Live catalog

The live catalog is published independently of app and CLI releases. The publisher validates the complete catalog, checks viewer dependencies, pins built-in packages to the source commit, and writes one catalog.json to the store-catalog branch. It uses GitHub only; it does not build or release the app, run package setup scripts, or access cloud infrastructure. Authors do not edit a generated index.

Package changes merged into main trigger Publish Store catalog, which runs the publisher on main as merged; it uses pinned official actions, gives write permission to the publishing job alone, and never runs on pull requests or forks. Actions → Publish Store catalog → Run workflow republishes by hand. A maintainer can also publish from a clean, current main checkout with node store/tools/catalog.mjs --publish, supplying GITHUB_TOKEN with repository contents-write access.

The CLI reads that public JSON over HTTPS, using conditional requests and a five-minute cache. Concurrent requests share one fetch. An open Store asks connected machines again every minute; reopening it also asks. New harnesses and shared viewers appear without a client restart or another app/CLI release. GitHub caching and the refresh interval mean publication is not instantaneous.

The last validated catalog is saved on disk. If GitHub is unavailable, slow, or serves an invalid response, clients keep that catalog; a first offline launch uses the bundled catalog. Installed harnesses remain listed even if their Store entry is removed. Refreshing metadata does not install, update, or execute packages. Get resolves both the harness and its viewer from the live catalog, and an already-installed viewer is reused.

Validate publication locally without writing to GitHub:

node store/tools/catalog.mjs

HARNESS_STORE_CATALOG_URL selects a catalog mirror or a loopback HTTP fixture for development. HARNESS_STORE_REF still overrides built-in install refs for testing a branch. Existing clients need the CLI version containing the live reader once; subsequent package publications do not need releases. Changes to the runtime or package protocol can still require a client update.

Tiers

Tier Ships Harness shows
0 manifest and instructions; optional skills and template the tile, a terminal with the instructions loaded
1 + a check that writes .harness/verdict.json + ready or not, findings and phases in the pane header
2 + a viewer server + the viewer pane beside the terminal, following the artifact

Worked examples

Harness Base agent What it shows
Hello World Codex a greeting in plain HTML, with a shared viewer declared in the manifest; no build step
Marp (Slides) Claude Code the smallest complete tier 2: a 110-line viewer with live reload and a present mode, two themes, an offline art generator, a check that writes the verdict, node tests. Start here.
Blender (3D) Claude Code a pinned bpy in a venv set up by setup.sh, a helper module the skill teaches, and a viewer package it shares through viewer.use
Autonomous Circuit (PCB) Claude Code a wrapper of another team's project: setup fetches it at a pinned commit and runs its own setup, doctor, init and board viewer
Autonomous Workshop (CAD) Codex the same shape on a Codex base, with the store's CAD Viewer as its pane, phases Build / Fit / Print / Motion / Review

Visual harnesses should show work progressively. A terminal-only harness is welcome too. Domain behavior stays in the package: adding a harness on a supported engine should not need changes to the app or daemon. If you need a new shared capability, discuss it through the spec/README.md contract. Changes are appended to spec/CHANGES.md.

The built-in shelf

The packages Autonomous maintains are folders here, and the rules below hold for every one of them. cli/src/dsh/store.spec.ts fails the build when a folder breaks one.

  • The two kinds keep different contracts, so the folder says which: kind in harness.json agrees with agents/ or viewers/.
  • The folder is the upstream project's own name, and the id is autonomous/<folder>: mujoco, blender, text-to-cad, autonomous-circuit. A wrapper never renames what it wraps.
  • One place per fact. Name, category, author, description and engine are the manifest's; homepage, upstream, licence and screenshots are store.json's. The CLI build turns each folder into its registry entry (repo this repository, path the folder, tier from what the manifest ships). The live publisher pins its ref to the source commit; the offline build fallback uses main.
  • harness dsh check passes on the folder as it is committed.
  • Credit travels with the code. A LICENSE for the wrapper, the upstream's licence beside it when anything of theirs is in the folder, and a README whose "Credit and stewardship" section says whose project it is.
  • Fetch what is not ours to copy. A compiler, a model zoo, a project's skills without a licence to vendor, another team's repository: toolchain/setup.sh fetches it at a pinned version (named in the folder's VERSIONS) into an ignored directory, never into git.

A user presses Get in the store; the daemon makes a sparse, blob-less clone of this repository, keeps the one folder, and runs its setup. From a terminal:

harness dsh install autonomous/typst                          # from the shelf
harness dsh update autonomous/typst                           # update the package; keep projects
harness dsh install "$PWD/store/agents/typst" --link          # this working tree, for development
HARNESS_STORE_REF=my-branch harness start                     # the shelf from a pushed branch

A package that outgrows its folder, or whose upstream maintainers want it, moves to a repository of its own and gets an entry in registry/ instead. Nothing changes for the people who installed it.

Unlisting a package

A package that is not ready for people, or no longer meets the bar, is unlisted, not deleted. One flag in its store.json does it:

{ "tagline": "…", "listed": false }
node store/tools/listing.mjs                       # every package, listed or UNLISTED
node store/tools/listing.mjs unlist web-studio     # take it off the shelf
node store/tools/listing.mjs list web-studio       # put it back (the flag is removed)

An unlisted package keeps its folder, its history and its tests, and the rules above still hold for it, so it does not rot. It is left out of the registry the CLI bakes in and of the catalog the Store publishes, so nobody is offered it and harness dsh install autonomous/<name> no longer finds it. Someone who already installed it keeps their copy. It still installs from a working tree with harness dsh install "$PWD/store/agents/<name>" --link. The change goes live like any other: merge to main and the catalog is published again.

The store in the app

The app's start page has a door to the store: every harness as a card, and a page per harness — its mark, who made it (author), its category and description, where it lives (repo and path, homepage, upstream), what it is licensed under (license), prompts beside what they made (examples), pictures (screenshots), ratings and reviews, and installation actions for this computer: Get, Update, Open and Remove. Installing is still what it always was — a clone (for a built-in package, of its one folder) under ~/.harness/dsh on one machine, its toolchain set up beside it — so the page is honest about that: harnesses are installed on a machine. Ratings and reviews are the signed-in person's, one per package, kept in the control plane, never in this repository.

The sidebar starts with Search, followed by Discover and six broad sections: Design, Engineering, Media, Science, Games and Code. Cards show Get, Update or Open for each harness; its page manages installation on this computer. Package manifests keep their precise domain labels, grouped only for browsing.

Core app harnesses are part of each CLI release: Harness Monitor, Devices and Model Manager are installed or refreshed automatically before their viewers are restored. Existing official Store copies of these packages move onto this release-managed path on the next CLI update; their previous files, workspaces and conversations are retained. Companions refresh their generated package when the saved collection's identity is restored, without sending a prompt or replacing its conversation. Linked developer checkouts and custom forks remain owner-managed. Core resources are versioned beside the CLI, so a CLI rollback restores its corresponding core package revision as well.

Devices and Companions appear in the desktop Store and its search only while the current account's Devices tab and Focus-bar creature experiments, respectively, are enabled. Switching either off hides its listing immediately. Their Open action reuses the app workspace; these bundled resources have no Store Get, Update or Remove action. They remain absent from the public daemon catalog, so an account opt-in never publishes them to other users.

Other Store applications, such as Blender, keep explicit updates. The Store shows Update when a matching catalog source publishes a different commit with changed package content. Built-in catalog entries carry their package folder's Git tree revision, so a change elsewhere in the monorepo does not flag every installed harness. Hover over the short installed version on a package page to see the installed and available commits.

harness dsh update <id> follows the matching catalog's published ref, or the recorded source/ref for an unlisted package or private fork. A community catalog needs a full commit SHA in ref to advertise updates; moving branches can still be updated from the CLI. Linked checkouts are updated directly by their owner.

The updater fetches and validates a replacement, retains the previous package, and runs setup and doctor at the permanent installation path. A failed check restores the old files and installed record. Workspaces, copied instructions, output files and session identities are preserved; existing skill links resolve to the updated package. Running harnesses are not restarted. Setup scripts may change external tools, and those external side effects cannot be rolled back. Shared viewer updates are independent: open their page from Viewers, then choose Update.

Viewer packages are shared dependencies, not Store listings. Installing a harness installs its viewer on that machine when needed; another harness using the same viewer reuses the installed copy. Viewers stay out of Discover, search and categories. Authors can still inspect and manage them with harness dsh list, update, doctor and remove. A small Viewers icon at the bottom of the Store sidebar opens the viewer inventory, where each viewer shows its installed machines and the harnesses that depend on it. Dependency names come from the machines' catalogs, including community packages; an older daemon may not report that information yet.

Stewardship of packages built on other people's work

Some first-party packages wrap a project Autonomous did not write: Marp (Yuki Hattori and the Marp team), text-to-cad and the CAD Viewer (Jake Fitzgerald). Each carries the upstream licence and a THIRD_PARTY_NOTICES.md, changes nothing upstream, names the author on its tile (author in the manifest), and says in its README that Autonomous wrote the wrapper on the project's behalf to bootstrap the catalogue. The ideal end state is that maintainers own their own Harness package: any upstream maintainer can ask, on this repository's issues, to have the wrapper's folder moved into a repository of theirs and the registry entry pointed at it. Until then bugs in the project go upstream and bugs in the wrapper come here.

Other Autonomous projects are upstreams too. Autonomous Circuit and Autonomous Workshop live in their teams' own repositories; their store packages are wrappers that fetch them read-only at a pinned commit and change nothing there, exactly as the MuJoCo package fetches Menagerie.