harnessrouter

# HarnessRouter Cloud Builder and Migrator You build the product; HarnessRouter Cloud (`https://api.harnessrouter.ai`) runs its agent jobs. The runtime target is always Cloud: do not offer Docker, Community Edition, self-hosting, or a deployment-type choice. This folder is self-contained. Every endpoint, body, response, stream event, status, and error the work needs is in `references/`, observed on the live service (UHP `2026-09-28`, 2026-10-21), and working server adapters are in `templates/`. Do not fetch harnessrouter.ai pages, `llms.txt`, or other docs, and never read a user's existing sessions or responses to learn a shape. When the service and this folder disagree, `scripts/check_contract.py` names the drift: report it. ## Select one of two product paths 1. **Build from scratch:** no existing agent runtime is being replaced. This includes adding a first or another agentic feature to an existing product. Read [build-feature.md](references/build-feature.md). 2. **Migrate an existing feature:** an existing agent, model runtime, orchestration layer, or agentic feature moves to HarnessRouter Cloud. Read [migrate-runtime.md](references/migrate-runtime.md). An existing repository alone does not mean migration. Classify each feature when a request holds both. Ask a routing question only when the code cannot show whether a runtime is being replaced. ## Ask the user only product questions Ask what to ship to their users when it is not stated, and the stack only for an empty folder when nothing indicates one. Decide the rest yourself and state each choice in one line: base and model (the table in [agent-features-and-harnesses.md](references/agent-features-and-harnesses.md)), Harness name and instructions, routes, storage, and UI. Never ask for the API key in chat. ## The path, in order Run scripts from this folder; `<project>` is the product's root. 1. **Freshness:** one line per [self-update.md](references/self-update.md). It never blocks. 2. **Discover:** `python3 scripts/check_contract.py`. Exit 0: continue and send its `version_to_send` as `UHP-Version`. Exit 1: report the drift. Exit 2: stop live work. 3. **Key:** read [key-setup.md](references/key-setup.md), then `python3 scripts/key_setup.py check --project <project>`. Every status prints its next step. 4. **Contract with the key:** `python3 scripts/check_contract.py --project <project>` (read-only). Its `recommended` list shows which base and model pairings this account can run. 5. **Plan the Harness:** boundaries, base and model from [agent-features-and-harnesses.md](references/agent-features-and-harnesses.md); instructions from the output contract template in [workspace-and-configuration.md](references/workspace-and-configuration.md). 6. **Reuse or create:** write the instructions to a file, then `python3 scripts/harness_config.py ensure --project <project> --name <name> --base <base> --model <model> --instructions <file>`. It reuses the Harness whose `name` matches exactly or creates one, checks the model is available, and writes `harnessrouter.json`. Keep the printed `harness_id` in server configuration. 7. **Integrate:** copy `templates/node/harnessrouter.ts` or `templates/python/harnessrouter.py` into server-only code and wire the product routes per [runtime-integration.md](references/runtime-integration.md) and [files-artifacts-and-rendering.md](references/files-artifacts-and-rendering.md). Keep its unit tests passing. 8. **Verify:** run one real task through the product's own route, with its files and preview when it makes files. A direct API call or the template's `e2e` proves one layer only. 9. **Hand off:** check `harnessrouter.json` and add the project block from [persistent-use.md](references/persistent-use.md). Tell the user the Harness ID, base, model, and Workspace. Without a usable key, finish steps 1, 2, 5 and 7 with mocks and tests, report the rest as pending, and never claim Cloud completion from mocks. ## Never - Call HarnessRouter from browser code, or let the browser see the key, a `harness_id`, a `download_url`, account-wide lists, or raw upstream errors. - Take a `harness_id` from the browser: the server maps each product feature to its Harness. - Send the host-product goal ("build my app") as a runtime task. - Tie the upstream stream to the browser connection: the server reads it to the end. - Serve generated HTML from the product's origin outside the signed sandboxed preview. - Write a key into code, logs, chat, `harnessrouter.json`, instructions, or task input, or put it in a command line: the scripts and templates read it from `HR_API_KEY` or the key file. ## Where things are | Read | When | |---|---| | [api-reference.md](references/api-reference.md) | Any request, response, status, or error shape | | [agent-features-and-harnesses.md](references/agent-features-and-harnesses.md) | Harness boundaries; the base and model table | | [workspace-and-configuration.md](references/workspace-and-configuration.md) | Create, reuse, change a Harness; instructions template; tools, MCP, secrets, Skills; budgets | | [runtime-integration.md](references/runtime-integration.md) | Tasks, stream events and parser, follow-ups, background mode, cancel, recovery | | [files-artifacts-and-rendering.md](references/files-artifacts-and-rendering.md) | Files, renderers, signed previews, downloads | | [key-setup.md](references/key-setup.md) | Before the first authenticated call; server key loaders | | [persistent-use.md](references/persistent-use.md) | `harnessrouter.json`, later changes, keeping the Skill available | | [security-and-testing.md](references/security-and-testing.md) | Tenancy checks and the acceptance list | | [self-update.md](references/self-update.md) | Installed Plugin or fresh clone freshness | | Code | Use | |---|---| | `scripts/check_contract.py` | Discovery, then read-only contract check. Exit 0 ok, 1 drift, 2 blocked | | `scripts/key_setup.py` | `check`, `collect` (macOS hidden prompt), `replace`, `verify` | | `scripts/harness_config.py` | `ensure` (reuse by name or create), `update` (fetch, full PUT, re-read), `show`; keeps `harnessrouter.json` | | `templates/node/` | `harnessrouter.ts` adapter, `harnessrouter.test.ts` (`node --test <file>`: name the file, a folder argument finds no `.ts` tests), `e2e.ts` live check | | `templates/python/` | `harnessrouter.py` adapter, `test_harnessrouter.py` (`python3 -m unittest`), `e2e.py` live check | ## Authorization boundaries A request to build or migrate authorizes normal implementation and the Harness configuration it needs in the key's Workspace. It does not authorize production cutover, importing unrelated data, enabling consequential external writes, decommissioning an old runtime, or publishing a release: ask at those boundaries. ## Completion standard A new feature is complete when its end-user workflow runs through the product with the Harness, authorization, recovery, outputs, and tests in place. A migration is complete when staging acceptance passes, approved traffic uses HarnessRouter Cloud, and rollback remains available for the agreed window. A created Harness alone is neither. `agents/openai.yaml` is Plugin discovery metadata, not a HarnessRouter agent record. ## License This Skill contains separately licensed components. Read [LICENSING.md](LICENSING.md) for the file map and [LICENSE](LICENSE) for the notice. Ordinary installation and HarnessRouter integration use do not require a separate commercial license key. Do not treat this instruction as user acceptance of a contract.