[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-92566":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":15,"stars7d":15,"stars30d":16,"stars90d":15,"forks30d":15,"starsTrendScore":15,"compositeScore":17,"rankGlobal":9,"rankLanguage":9,"license":18,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":19,"hasPages":19,"topics":21,"createdAt":9,"pushedAt":9,"updatedAt":22,"readmeContent":23,"aiSummary":24,"trendingCount":15,"starSnapshotCount":15,"syncStatus":25,"lastSyncTime":26,"discoverSource":27},92566,"homerail","xiaotianfotos\u002Fhomerail","xiaotianfotos","Voice-first local agent orchestration runtime for auditable DAG workflows.",null,"TypeScript",492,115,1,5,0,315,56.19,"MIT License",false,"main",[],"2026-07-22 04:02:06","# HomeRail\n\nEnglish | [中文](README.zh-CN.md)\n\nHomeRail is a TypeScript runtime that turns one-off agent chats into auditable,\nreusable workflows. The name comes from what it is: **Home** — it runs on your\nown homelab, NAS, or home server, serving the people who live there; **Rail** —\nthe track shape of a DAG, where agent work flows node to node along explicit\nedges instead of pooling in a single chat. The design bet is that a person's\nattention is the scarcest resource in any automation, so the system should ask\nfor very little of it.\n\nThe long-term shape is a resident home-datacenter agent you talk to — voice in,\na generated interface out, a DAG of agents doing the work behind it. What is in\nthis tree today is the foundation it runs on: a DAG engine, a CLI, a voice\nsurface, and the first steps toward a generated UI.\n\n## Why\n\nHuman bandwidth is narrow; the work we want done is not. HomeRail is shaped like\nan inverted funnel that widens toward the machine:\n\n- **Voice** — the preferred input, because it asks the least of you. You speak;\n  the agent listens, confirms, and narrows ambiguity before doing anything. Text\n  is always available too — for quiet settings, for precision, or for anyone not\n  ready to talk to their computer yet.\n- **Generative UI** — the agent does not dump logs or JSON at you. The interface\n  is generated for the moment and shaped to be easy to read.\n- **DAG** — the execution engine behind both. Multiple agents, multiple roles,\n  multiple environments, with every handoff traced and every run replayable.\n\nA chat session is a black box. A DAG is a graph you can inspect, replay, and\nimprove. HomeRail is what sits between the two — narrow where the person is,\nwide where the machine is.\n\n## What works today\n\n- **DAG runtime** *(most mature)* — multi-agent orchestration with explicit\n  handoffs, workspace isolation per run, replay, scorecards, and run evaluation.\n- **CLI `hr`** — `start`, `config`, `doctor`, `run`, `smoke`, `dag supervise`,\n  `scorecard`, `eval-run`, `replay`. The primary way to operate HomeRail.\n- **Voice surface** — a Voice Surface Contract with ASR \u002F TTS \u002F VAD, Chinese by\n  default, served through a desktop voice shell. The agent collects intent\n  across turns before acting.\n- **Generative UI** *(in exploration)* — instead of dumping logs or JSON, the\n  agent produces structured, generated views meant to be read at a glance. The\n  shape of these views is still being designed through real use cases; the\n  contract and the widget set will keep changing.\n- **Docker Worker** — Manager and Node run as local services; Node uses Docker\n  to provision Worker containers, one per DAG node, sharing a workspace per run.\n\n## Hand this README to an agent\n\nHomeRail is designed to be operated by agents as much as by people. This README\nis written so that it doubles as an agent-readable runbook: the commands below\nare plain `hr` invocations with self-describing names, and each step says what\nto expect. You can hand the whole file to your agent (Claude Code, Codex, or\nany tool that can run shell commands and read output) and ask it to install,\nconfigure, and verify HomeRail on your machine following the Quickstart.\n\n## Quickstart\n\nRequirements:\n\n- Node.js 20+ and npm 10+\n- Docker, used by Node to provision Worker containers\n- A Claude Agent SDK-compatible model endpoint for live agent runs\n\nPlatform notes:\n\n- **macOS** — install [Docker Desktop](https:\u002F\u002Fwww.docker.com\u002Fproducts\u002Fdocker-desktop\u002F).\n  The default `host.docker.internal` mapping works out of the box.\n- **Windows** — Docker Desktop (WSL 2 or Hyper-V backend both work), and run\n  the CLI from Git Bash (or another POSIX-compatible shell). Some scripts\n  assume a Unix-like shell and will not run correctly under `cmd.exe` or\n  PowerShell.\n- **Linux** — Docker Engine. Worker-to-Manager networking may need extra setup;\n  see the [Configuration](#configuration) notes on Worker callback URLs.\n\nInstall and build from this source checkout:\n\n```bash\nnpm run install:all\nnpm run build\n```\n\nThe CLI is exposed as `hr`. Link it locally so the rest of this guide works as\nwritten:\n\n```bash\ncd homerail_cli && npm link && cd ..\nhr --help\n```\n\nStart Manager and Node together. On first run this builds the\n`homerail-worker:latest` image; it is rebuilt automatically when the worker\nsource fingerprint changes:\n\n```bash\nhr start\n```\n\nCheck readiness. `hr doctor` reports Manager reachability, Node availability,\nthe active model setting, and whether the Manager Agent harness can resolve a\nruntime:\n\n```bash\nhr doctor\n```\n\nRun a local topology check. This uses the two-node template's offline\ndeterministic profile, so it does not need a model provider yet:\n\n```bash\nhr run assets\u002Forchestrations\u002Fpublic-two-node.yaml.template \\\n  --profile offline-deterministic \\\n  --prompt \"Draft a short checklist for a backend release\"\n```\n\nThe command returns a `run_id`; inspect it with `hr dag supervise \u003Crun_id>` if\nyou want to watch the handoff flow.\n\nTo also bring up the browser Agent UI:\n\n```bash\nhr start --ui\n```\n\nDefaults are Manager `http:\u002F\u002Flocalhost:19191`, Agent UI\n`https:\u002F\u002Flocalhost:19192`, and HTTP fallback `http:\u002F\u002Flocalhost:19193`. The\nManager binds to `127.0.0.1` by default; use `hr start --host 0.0.0.0` only when\nyou intentionally want it reachable beyond localhost.\n\n## Run a DAG\n\nLoad a template explicitly and run it:\n\n```bash\nhr templates list\nhr run assets\u002Forchestrations\u002Fpublic-two-node.yaml.template \\\n  --prompt \"Draft a short project checklist\"\n```\n\nFor reusable workflows, sync the DAG into the Manager database. Keep\n`workflow_id` stable when editing YAML; changing it creates a new workflow\nidentity.\n\n```bash\nhr dag sync assets\u002Forchestrations\u002Fpublic-dev-5node.yaml.template\nhr profile sync assets\u002Fprofiles\u002Fexample-runtime.profile.yaml.template \\\n  --workflow public-dev-5node-template\nhr run \\\n  --workflow public-dev-5node-template \\\n  --profile example-runtime \\\n  --prompt \"Draft a short project checklist\"\n```\n\nCopy the returned `run_id`, then inspect it:\n\n```bash\nhr dag supervise \u003Crun_id>\nhr scorecard \u003Crun_id>\nhr eval-run \u003Crun_id>\n```\n\nFor a topology check without a live model provider, the two-node template ships\nan offline deterministic profile:\n\n```bash\nhr run assets\u002Forchestrations\u002Fpublic-two-node.yaml.template \\\n  --profile offline-deterministic \\\n  --prompt \"Draft a short checklist for a backend release\"\n```\n\n## Drive the CLI from a coding agent\n\nThere is a second way to use HomeRail, beyond speaking to the Manager Agent or\ntyping commands yourself. A coding agent you already trust — Codex, Claude\nCode, or any tool that can run shell commands — can drive the `hr` CLI\ndirectly: `templates list`, `run`, `dag supervise`, `scorecard`, `replay`.\n\nThis skips the Manager Agent layer (the AI that plans a DAG from a request),\nbut not the Manager service (the DAG coordinator). Your coding agent takes over\nthe planning role: it reads a template, decides what to change, runs the DAG,\ninspects the result, and iterates. This is the natural loop for developing and\ndebugging DAGs and templates — you get the full audit trail and evaluation of\nthe DAG runtime, with a model you already use for code in direct control of the\nloop.\n\n```text\nyou ↔ coding agent ↔ hr CLI ↔ Manager service ↔ DAG nodes\n       (planning)              (coordination)     (execution)\n```\n\nThe Manager Agent is still the right choice when you want HomeRail to plan and\nrun a workflow end-to-end from a single request, especially by voice. Driving\nthe CLI yourself is the right choice when you are building or tuning the DAG.\n\n## Architecture\n\n| Package | Role |\n| --- | --- |\n| `homerail_protocol` | Shared message and validation contracts — single source of truth for runtime communication. |\n| `homerail_manager` | Manager service and DAG coordinator. Owns the voice surface and the generated-UI contract. |\n| `homerail_node` | Node service. Provisions Docker-backed Worker containers. |\n| `homerail_worker` | Worker runtime. Harness adapters for Claude Agent SDK and compatible agent backends. |\n| `homerail_cli` | The `hr` CLI. Configures, runs, and inspects DAG workflows. |\n| `agent-ui` | Decoupled browser UI for operating the Manager. Renders voice surface and widgets. |\n\nManager and Node run as local services. Manager is not expected to run inside\nthe Worker image. Node creates Worker containers; Workers for one run share\n`${HOMERAIL_HOME}\u002Fworkspace\u002F\u003Crun_id>`.\n\n### Smart brain, efficient workers\n\nThe expensive model should not do everything. Each DAG node runs in its own\ncontext window: it receives the handoff it needs, does its part, and passes\nevidence forward. Context never balloons into one giant thread, and nothing gets\ncompressed under pressure just to fit. Because nodes are independent, each can\nuse a different model — the smartest model plans and reviews; cheaper, more\ntoken-efficient models do the bulk of the work. Templates express this through a\nper-agent `provider` \u002F `model` mapping, with a `\"*\"` wildcard as the fallback\ndefault.\n\n## Configuration\n\n`HOMERAIL_HOME` is the local data root — where Manager state, run workspaces,\nlogs, and the worker image cache land. It defaults to `~\u002F.homerail` and can grow\nquickly: every DAG run writes its artifacts under\n`${HOMERAIL_HOME}\u002Fworkspace\u002F\u003Crun_id>\u002F`, and these accumulate across runs. Point\nit at a disk with room (a NAS mount, a large external volume) before you start\nrunning real work:\n\n```bash\nexport HOMERAIL_HOME=\"\u002Fmnt\u002Fnas\u002Fhomerail\"\n```\n\nProvider credentials are stored in the Manager encrypted settings store, never\nin repo files. Configure a model from the provider catalog:\n\n```bash\nhr model configure \u003Cprovider-or-endpoint-alias> \\\n  --endpoint-id \u003Cendpoint-id> \\\n  --model-name \u003Cmodel-id> \\\n  --api-key-stdin\nhr model list\n```\n\nAfter a model is configured, run the full public smoke DAG. It exercises the\nfive-node path (plan → implement → test → review → summarize) and verifies both\nscorecard and eval-run:\n\n```bash\nhr smoke dag \\\n  --template assets\u002Forchestrations\u002Fpublic-dev-5node.yaml.template\n```\n\nA passing smoke writes its artifacts to the shared run workspace:\n\n```text\n${HOMERAIL_HOME}\u002Fworkspace\u002F\u003Crun_id>\u002Fsnake-game\u002Findex.html\n${HOMERAIL_HOME}\u002Fworkspace\u002F\u003Crun_id>\u002Fsnake-game\u002FTESTS.md\n```\n\nThe CLI resolves the Manager URL in this order: `--base-url`,\n`HOMERAIL_MANAGER_URL`, `${HOMERAIL_HOME}\u002Fconfig.json`, then\n`http:\u002F\u002Flocalhost:19191`.\n\nFor reverse-proxied public access, advertise external endpoints and bind the UI\nto the machine IP:\n\n```bash\nhr start --ui --public \\\n  --public-url https:\u002F\u002Fhomerail.example.com \\\n  --ui-public-url https:\u002F\u002Fhomerail-ui.example.com\n```\n\nWorker containers connect back to the Manager through the URL Manager passes to\nNode. On Docker Desktop the default `host.docker.internal` mapping is usually\nenough; on Linux use Docker `host-gateway` support or set\n`HOMERAIL_MANAGER_WORKER_WS_BASE_URL`. Do not hardcode Docker bridge addresses.\n\nRuntime helpers:\n\n```bash\nhr runtime status\nhr runtime logs\nhr runtime stop\nhr ui status\nhr ui logs\nhr ui stop\n```\n\n## Project direction\n\nHomeRail is heading toward a resident agent on the home datacenter — voice in,\ngenerated UI out, multiple nodes and terminals (phone, tablet, TV, car). The\nfoundation here is the first step; see [ROADMAP.md](ROADMAP.md) for the plan.\n\nFor the voice Manager Agent, **Codex (`codex_appserver`) is the recommended\nharness today**: it is the only path that auto-synthesizes the `commentary`\nspeech channel from the model's native reasoning stream, so the user hears\nprogress while work happens. Other harnesses (`claude-sdk`, `kimi-code`) are\nsilent during execution — this is a provider capability gap, not something\nHomeRail can close.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","HomeRail 是一个面向家庭本地环境的语音优先智能体编排运行时，将单次对话转化为可审计、可复用的有向无环图（DAG）工作流。其核心包含轻量级 DAG 执行引擎、支持中文的语音交互界面（ASR\u002FTTS\u002FVAD）、命令行工具 `hr`、基于 Docker 的隔离式节点执行器，以及正在探索中的生成式 UI 输出机制。所有组件默认运行于用户自有设备（如家庭服务器、NAS），强调隐私性、可追溯性与最小化人工干预。适用于家庭自动化、个人知识管理、本地 AI 任务编排等需兼顾可控性、可审计性与自然交互的场景。",2,"2026-07-09 02:30:21","CREATED_QUERY"]