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.
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.
Copy the starter.
starter/is a complete tier-0 harness: a manifest, anAGENTS.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 ownIn
harness.jsonsetid(owner/name, the install directory and the wire id),name(the tile),category(the tile's second line),engine(claudeorcodex), andworkspace.marker(a file whose presence means the workspace is already laid out).Tell the agent its job.
AGENTS.mdsays 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 inskills/<name>/SKILL.md: the dialect, the patterns, the commands. Skills are symlinked, so a change in your checkout is live in every workspace.Lay out the workspace.
template/is copied into an empty folder once; thenworkspace.initruns with the workspace as its working directory andHARNESS_DSH_DIRpointing at the install. Seed the first verdict here so the header has a state before the first prompt.Ship the toolchain with the harness.
toolchain/setup.shruns once at install, in the install directory: pin versions and vendor them there (anode_modules, a.venv), never into the user's machine.toolchain/doctor.shexits 0 when the machine can run the harness and prints one line per check; Harness shows those lines. Point the agent at the tools throughagent.env("MARP_TOOLCHAIN": "${dsh}/toolchain");${dsh},${workspace}and${home}expand.Write the verdict as a feed.
.harness/verdict.jsonis written at every check and every phase change, not at the end.readyis the one machine truth;summaryis the header's line;phasesis 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" }Add the viewer.
viewer.commandis a long-running process. Harness starts it withHARNESS_VIEWER_PORT,HARNESS_WORKSPACE,HARNESS_DSH_DIRandHARNESS_DSHin its environment, waits for the port to open on127.0.0.1, then loadsviewer.urlin the pane (${port}and${artifact}expand; the artifact is what the verdict names, or the newest file matchingartifactExtensions). 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.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 offersThen New Harness, your tile, a folder, a prompt. For a check without the app,
tools/dsh-e2e.mjscreates 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:
kindinharness.jsonagrees withagents/orviewers/. - 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 usesmain. harness dsh checkpasses on the folder as it is committed.- Credit travels with the code. A
LICENSEfor 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.shfetches it at a pinned version (named in the folder'sVERSIONS) 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.