{"id":51173678,"url":"https://github.com/yolo-maxi/runyard","last_synced_at":"2026-06-27T02:05:12.535Z","repository":{"id":365864457,"uuid":"1273782570","full_name":"yolo-maxi/runyard","owner":"yolo-maxi","description":"Runyard: self-hosted control plane for agent runs","archived":false,"fork":false,"pushed_at":"2026-06-26T23:41:43.000Z","size":4093,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-27T00:14:17.225Z","etag":null,"topics":["agents","mcp","runners","self-hosted","sqlite"],"latest_commit_sha":null,"homepage":"https://runyard.repo.box","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yolo-maxi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-18T21:42:29.000Z","updated_at":"2026-06-26T23:41:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yolo-maxi/runyard","commit_stats":null,"previous_names":["yolo-maxi/runyard"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/yolo-maxi/runyard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yolo-maxi%2Frunyard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yolo-maxi%2Frunyard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yolo-maxi%2Frunyard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yolo-maxi%2Frunyard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yolo-maxi","download_url":"https://codeload.github.com/yolo-maxi/runyard/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yolo-maxi%2Frunyard/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34839011,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","mcp","runners","self-hosted","sqlite"],"created_at":"2026-06-27T02:05:10.804Z","updated_at":"2026-06-27T02:05:12.522Z","avatar_url":"https://github.com/yolo-maxi.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Runyard\n\n**Self-hosted control plane for agent runs.**\n\nRunyard (package: `runyard`) is a capability operating system you run on a box you own. Agents discover team-defined capabilities over MCP/CLI/HTTP/Web, runners execute them on a VPS or laptop, and the Hub keeps the durable record of logs, events, artifacts, approvals, skills, agents, and knowledge.\n\nOne private deployment per company/org — no SaaS dependency, no shared database. The CLI and bins are `runyard`, `runyard-mcp`, and `runyard-runner`. Runyard was formerly called Smithers Hub; the legacy `SMITHERS_HUB_*` env vars are still read as fallbacks, so existing deployments and tokens carry over.\n\n## Concepts\n\n- **Capability** — a public, named action agents and operators discover and run (surfaced as *workflows* in the app/API).\n- **Workflow** — the Smithers steps behind a capability.\n- **Run** — one durable execution: `queued → running → succeeded/failed/cancelled`, pausing in `waiting_approval` for human sign-off. Keeps logs, events, outputs, artifacts, and a unified timeline.\n- **Runner** — a disposable process on a VPS or laptop that polls the Hub, claims matching runs, executes them, and uploads artifacts.\n- **Approval** — a human checkpoint resolved from Web, API, CLI, MCP, or Telegram and recorded once.\n- **Artifact / Agent / Skill / Knowledge** — persistent run outputs, reusable roles, reusable tooling packages, and shared company context.\n- **Access token** — the single bearer auth primitive for Web/API/CLI/MCP/runners; scopes (`api`, `mcp`, `runner`, `admin`) narrow what a token can do.\n\nThe full concepts overview, setup, API, and the in-app **Assistant** (the context-aware support copilot in `/app`) are documented in **[/docs/quickstart](public/docs.html)**.\n\n## run-smithers (supervising wrapper)\n\n`run-smithers` is the core Orchestration capability that wraps any other capability/workflow request inside a Smithers-managed supervising run. The watcher:\n\n- Records child lineage: child run id, capability, current/failed step, checkpoint when present, recovery attempts, and normalized error fingerprint counts.\n- Retries recoverable failures and re-queues child runs whose state was interrupted.\n- Pauses autonomous retry and requests an approval (with concrete options: retry as-is, approve a revised input, or abandon) once the same normalized error fingerprint repeats three times.\n- Never marks the supervising run a success unless the child workflow reaches a terminal `succeeded` state.\n\nExisting user-facing workflows are migrating to run behind `run-smithers` so every long-running goal carries the same lineage and recovery semantics. The pure watcher decision logic lives in `src/runSmithersWatcher.js` and is covered by `tests/run-smithers-watcher.test.js`.\n\n## Workflow hardening\n\nRunyard workflows are meant to harden over time. Early runs can be agentic: agents explore the repo, write shell snippets, try commands, and discover what works. Runyard should capture that knowledge, split it into smaller deliverable steps, and progressively replace repeatable agent work with scripts, tested code, and automated machine steps.\n\nThe gradient is:\n\n```text\nagentic -\u003e constrained agentic -\u003e script-backed -\u003e deterministic code -\u003e automated machine step\n```\n\nNightly optimizer runs should replay workflows, diff outputs, measure variance/failure/cost, delete unnecessary steps, and propose hardened replacements. Creative and taste-heavy steps may remain agentic; engineering plumbing should become deterministic wherever possible.\n\nSee `specs/workflow-hardening-and-optimizer.md`.\n\n## Get started\n\n```bash\npnpm install\n```\n\nThen read **[/docs/quickstart](public/docs.html)** (or visit `/docs/quickstart` on any running Hub) for install, run, topology, CLI, MCP, runner pool, security, env vars, and verification. The landing page (`/`) walks you through your first capability run before you pick a topology or install channel.\n\nAfter a run starts, use the Hub detail page or the CLI:\n\n```bash\nrunyard tail \u003crun-id\u003e --once\nrunyard tail \u003crun-id\u003e\n```\n\nThe tail command streams the unified run timeline as NDJSON: lifecycle status transitions, run events, runner artifacts, retrospectives, and obstruction-analysis artifacts in timestamp order.\n\n## Improve target repos\n\nThe `improve` workflow edits the runner's default repo by default: `IMPROVE_REPO_DIR || GATED_REPO_DIR || process.cwd()`. To improve another repo, pass `repoDir` as an absolute runner-local git repo path and allow it with `IMPROVE_ALLOWED_REPO_ROOTS`, or pass a friendly `repo`/`project` key from `IMPROVE_REPO_MAP` / `IMPROVE_PROJECT_MAP`.\n\nThe selected repo is where the PM review, builder, tests, commit, push, and deploy run. The Hub remains the source of truth for run status, logs, outputs, and artifacts.\n\n## Repo layout\n\n- `bin/` — CLI / MCP / runner entry points\n- `src/` — server, CLI, MCP, runner, db, security\n- `public/` — landing, docs, console\n- `specs/` — product intent, decisions, acceptance checks\n- `workflow-templates/` — bundled Smithers workflows\n- `tests/` — Node test runner\n\n## Specs\n\nThe durable product/spec record lives in `specs/`:\n\n- `specs/product-intent-and-user-expectations.md`\n- `specs/implementation-decisions.md`\n- `specs/acceptance-and-manual-tests.md`\n- `specs/workflow-hardening-and-optimizer.md`\n\n## License\n\nMIT. File issues and PRs against the public Runyard repo. Treat hostnames like `hub.example.com` as examples — do not hard-code private hostnames in new code or docs.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyolo-maxi%2Frunyard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyolo-maxi%2Frunyard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyolo-maxi%2Frunyard/lists"}