Skip to content
Back to search

homerail

Voice-first local agent orchestration runtime for auditable DAG workflows.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/xiaotianfotos--homerail/badge.svg)](/listings/xiaotianfotos--homerail)

HTML

<a href="/listings/xiaotianfotos--homerail"><img src="/api/listings/xiaotianfotos--homerail/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requirements:

- Node.js 20+ and npm 10+ - Docker, used by Node to provision Worker containers - A Claude Agent SDK-compatible model endpoint for live agent runs

Platform notes:

- **macOS** — install [Docker Desktop](https://www.docker.com/products/docker-desktop/). The default `host.docker.internal` mapping works out of the box. - **Windows** — Docker Desktop (WSL 2 or Hyper-V backend both work), and run the CLI from Git Bash (or another POSIX-compatible shell). Some scripts assume a Unix-like shell and will not run correctly under `cmd.exe` or PowerShell. - **Linux** — Docker Engine. Worker-to-Manager networking may need extra setup; see the [Configuration](#configuration) notes on Worker callback URLs.

Install and build from this source checkout:

npm run install:all
npm run build

Run the deterministic checks directly with `npm run ci`. To execute the Linux GitHub Actions jobs locally, install Docker, [`act`](https://github.com/nektos/act), and [`actionlint`](https://github.com/rhysd/actionlint), then run:

npm run ci:local
npm run ci:local -- core-linux  # run one job

The local runner covers the Linux core, UI coverage, and Docker smoke jobs. The Windows job remains on GitHub's `windows-latest` runner.

The CLI is exposed as `hr`. Link it locally so the rest of this guide works as written:

cd homerail_cli && npm link && cd ..
hr --help

Start Manager and Node together. Manager becomes available without waiting for Docker. Open **Settings → Runtime Environment** to check Docker, inspect Worker versions, and build or rebuild `homerail-worker:latest` asynchronously:

hr start

`hr start --rebuild-worker-image` queues the same asynchronous build after Manager starts; it no longer blocks Manager startup while Docker builds.

Check readiness. `hr doctor` reports Manager reachability, Node availability, the active model setting, and whether the Manager Agent harness can resolve a runtime:

hr doctor

Run a local topology check. This uses the two-node template's offline deterministic profile, so it does not need a model provider yet:

hr run assets/orchestrations/public-two-node.yaml.template \
  --profile offline-deterministic \
  --prompt "Draft a short checklist for a backend release"

The command returns a `run_id`; inspect it with `hr dag supervise <run_id>` if you want to watch the handoff flow.

To also bring up the browser Agent UI:

hr start --ui

Defaults are Manager `http://localhost:19191`, Agent UI `https://localhost:19192`, and HTTP fallback `http://localhost:19193`. The Manager binds to `127.0.0.1` by default; use `hr start --host 0.0.0.0` only when you intentionally want it reachable beyond localhost.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 439 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # HomeRail
  2. English | [中文](README.zh-CN.md)
  3. HomeRail is a TypeScript runtime that turns one-off agent chats into auditable,
  4. reusable workflows. The name comes from what it is: **Home** — it runs on your
  5. own homelab, NAS, or home server, serving the people who live there; **Rail** —
  6. the track shape of a DAG, where agent work flows node to node along explicit
  7. edges instead of pooling in a single chat. The design bet is that a person's
  8. attention is the scarcest resource in any automation, so the system should ask
  9. for very little of it.
  10. The long-term shape is a resident home-datacenter agent you talk to — voice in,
  11. a generated interface out, a DAG of agents doing the work behind it. What is in
  12. this tree today is the foundation it runs on: a DAG engine, a CLI, a voice
  13. surface, and the first steps toward a generated UI.
  14. ## Why
  15. Human bandwidth is narrow; the work we want done is not. HomeRail is shaped like
  16. an inverted funnel that widens toward the machine:
  17. - **Voice** — the preferred input, because it asks the least of you. You speak;
  18. the agent listens, confirms, and narrows ambiguity before doing anything. Text
  19. is always available too — for quiet settings, for precision, or for anyone not
  20. ready to talk to their computer yet.
  21. - **Generative UI** — the agent does not dump logs or JSON at you. The interface
  22. is generated for the moment and shaped to be easy to read.
  23. - **DAG** — the execution engine behind both. Multiple agents, multiple roles,
  24. multiple environments, with every handoff traced and every run replayable.
  25. A chat session is a black box. A DAG is a graph you can inspect, replay, and
  26. improve. HomeRail is what sits between the two — narrow where the person is,
  27. wide where the machine is.
  28. ## What works today
  29. - **DAG runtime** *(most mature)* — multi-agent orchestration with explicit
  30. handoffs, workspace isolation per run, replay, scorecards, and run evaluation.
  31. - **CLI `hr`** — `start`, `config`, `doctor`, `run`, `smoke`, `dag supervise`,
  32. `scorecard`, `eval-run`, `replay`. The primary way to operate HomeRail.
  33. - **Voice surface** — a Voice Surface Contract with ASR / TTS / VAD, Chinese by
  34. default, served through a desktop voice shell. The agent collects intent
  35. across turns before acting.
  36. - **Generative UI** *(in exploration)* — instead of dumping logs or JSON, the
  37. agent produces structured, generated views meant to be read at a glance. The
  38. shape of these views is still being designed through real use cases; the
  39. contract and the widget set will keep changing.
  40. - **Docker Worker** — Manager and Node run as local services; Node uses Docker
  41. to provision Worker containers, one per DAG node, sharing a workspace per run.
  42. ## Hand this README to an agent
  43. HomeRail is designed to be operated by agents as much as by people. This README
  44. is written so that it doubles as an agent-readable runbook: the commands below
  45. are plain `hr` invocations with self-describing names, and each step says what
  46. to expect. You can hand the whole file to your agent (Claude Code, Codex, or
  47. any tool that can run shell commands and read output) and ask it to install,
  48. configure, and verify HomeRail on your machine following the Quickstart.
  49. ## Quickstart
  50. Requirements:
  51. - Node.js 20+ and npm 10+
  52. - Docker, used by Node to provision Worker containers
  53. - A Claude Agent SDK-compatible model endpoint for live agent runs
  54. Platform notes:
  55. - **macOS** — install [Docker Desktop](https://www.docker.com/products/docker-desktop/).
  56. The default `host.docker.internal` mapping works out of the box.
  57. - **Windows** — Docker Desktop (WSL 2 or Hyper-V backend both work), and run
  58. the CLI from Git Bash (or another POSIX-compatible shell). Some scripts
  59. assume a Unix-like shell and will not run correctly under `cmd.exe` or
  60. PowerShell.
  61. - **Linux** — Docker Engine. Worker-to-Manager networking may need extra setup;
  62. see the [Configuration](#configuration) notes on Worker callback URLs.
  63. Install and build from this source checkout:
  64. ```bash
  65. npm run install:all
  66. npm run build
  67. ```
  68. Run the deterministic checks directly with `npm run ci`. To execute the Linux
  69. GitHub Actions jobs locally, install Docker, [`act`](https://github.com/nektos/act),
  70. and [`actionlint`](https://github.com/rhysd/actionlint), then run:
  71. ```bash
  72. npm run ci:local
  73. npm run ci:local -- core-linux # run one job
  74. ```
  75. The local runner covers the Linux core, UI coverage, and Docker smoke jobs. The
  76. Windows job remains on GitHub's `windows-latest` runner.
  77. The CLI is exposed as `hr`. Link it locally so the rest of this guide works as
  78. written:
  79. ```bash
  80. cd homerail_cli && npm link && cd ..
  81. hr --help
  82. ```
  83. Start Manager and Node together. Manager becomes available without waiting for
  84. Docker. Open **Settings → Runtime Environment** to check Docker, inspect Worker
  85. versions, and build or rebuild `homerail-worker:latest` asynchronously:
  86. ```bash
  87. hr start
  88. ```
  89. `hr start --rebuild-worker-image` queues the same asynchronous build after
  90. Manager starts; it no longer blocks Manager startup while Docker builds.
  91. Check readiness. `hr doctor` reports Manager reachability, Node availability,
  92. the active model setting, and whether the Manager Agent harness can resolve a
  93. runtime:
  94. ```bash
  95. hr doctor
  96. ```
  97. Run a local topology check. This uses the two-node template's offline
  98. deterministic profile, so it does not need a model provider yet:
  99. ```bash
  100. hr run assets/orchestrations/public-two-node.yaml.template \
  101. --profile offline-deterministic \
  102. --prompt "Draft a short checklist for a backend release"
  103. ```
  104. The command returns a `run_id`; inspect it with `hr dag supervise <run_id>` if
  105. you want to watch the handoff flow.
  106. To also bring up the browser Agent UI:
  107. ```bash
  108. hr start --ui
  109. ```
  110. Defaults are Manager `http://localhost:19191`, Agent UI
  111. `https://localhost:19192`, and HTTP fallback `http://localhost:19193`. The
  112. Manager binds to `127.0.0.1` by default; use `hr start --host 0.0.0.0` only when
  113. you intentionally want it reachable beyond localhost.
  114. ## Run a DAG
  115. Load a template explicitly and run it:
  116. ```bash
  117. hr templates list
  118. hr run assets/orchestrations/public-two-node.yaml.template \
  119. --prompt "Draft a short project checklist"
  120. ```
  121. For reusable workflows, sync the DAG into the Manager database. Keep
  122. `workflow_id` stable when editing YAML; changing it creates a new workflow
  123. identity.
  124. ```bash
  125. hr dag sync assets/orchestrations/public-dev-5node.yaml.template
  126. hr profile sync assets/profiles/example-runtime.profile.yaml.template \
  127. --workflow public-dev-5node-template
  128. hr run \
  129. --workflow public-dev-5node-template \
  130. --profile example-runtime \
  131. --prompt "Draft a short project checklist"
  132. ```
  133. Copy the returned `run_id`, then inspect it:
  134. ```bash
  135. hr dag supervise <run_id>
  136. hr scorecard <run_id>
  137. hr eval-run <run_id>
  138. ```
  139. For workflows that pause at a durable command boundary and resume selected
  140. logical actors under the same run, see [Multi-Round DAGs](docs/multi-round-dags.md).
  141. The guide covers strict WorkflowSpec v1 authoring, round fencing, CLI and HTTP
  142. commands, recovery, expiry, and concurrency-slot behavior.
  143. An optional [tokenizer-based local-model route](docs/e2e-fix-token-admission.md) checks complete requests and preserves the configured output reserve before forwarding.
  144. [E2E Fix](docs/e2e-fix.md) accepts a fixed caller design. A local Fixer develops
  145. and passes trusted tests before publishing or updating the same PR for independent
  146. model review. Insufficient approvals or failed CI feed a fresh Fixer session.
  147. New tasks have no Codex dependency and no Planner/Judger nodes: the configured
  148. review majority and same-head CI determine acceptance. Design, candidate history
  149. and per-round evidence persist; see [recovery boundaries](docs/e2e-fix-recovery.md).
  150. Older frozen host Codex tasks remain readable; new preparation rejects that configuration.
  151. Trusted candidate snapshots normalize storage permissions and pass validation
  152. before publication; invalid published snapshots are rejected without rewriting.
  153. DSH provides bounded, content-free output byte diagnostics to distinguish
  154. observed reasoning, text and tool arguments; these are not token budgets.
  155. The program-only watcher also alerts when a failed host stage remains RUNNING,
  156. while expected failures handled by the repair loop stay quiet.
  157. See the same guide for evidence requirements and remaining recovery limits.
  158. For a topology check without a live model provider, the two-node template ships
  159. an offline deterministic profile:
  160. ```bash
  161. hr run assets/orchestrations/public-two-node.yaml.template \
  162. --profile offline-deterministic \
  163. --prompt "Draft a short checklist for a backend release"
  164. ```
  165. HomeRail also ships a Manager-backed [DAG pattern library](docs/dag-patterns.md)
  166. for reusable control-flow designs such as quorum, bounded ratchets, standing
  167. goal verification, and planner/worker fan-out:
  168. ```bash
  169. hr patterns list
  170. hr patterns show quorum
  171. hr patterns instantiate quorum --set workflow_id=release-quorum --set threshold=2
  172. ```
  173. Manager Agent discovers every `SKILL.md` directory under
  174. `${HOMERAIL_HOME:-$HOME/.homerail}/skills` on each turn and installs missing
  175. built-in `homerail-*` skills there as links. A pattern request can therefore be
  176. handled without shell commands: Manager Agent reads `homerail-dag-patterns`,
  177. selects and instantiates a catalog pattern, syncs it, and starts the returned
  178. workflow through Manager tools.
  179. ## Drive the CLI from a coding agent
  180. There is a second way to use HomeRail, beyond speaking to the Manager Agent or
  181. typing commands yourself. A coding agent you already trust — Codex, Claude
  182. Code, or any tool that can run shell commands — can drive the `hr` CLI
  183. directly: `templates list`, `run`, `dag supervise`, `scorecard`, `replay`.
  184. This skips the Manager Agent layer (the AI that plans a DAG from a request),
  185. but not the Manager service (the DAG coordinator). Your coding agent takes over
  186. the planning role: it reads a template, decides what to change, runs the DAG,
  187. inspects the result, and iterates. This is the natural loop for developing and
  188. debugging DAGs and templates — you get the full audit trail and evaluation of
  189. the DAG runtime, with a model you already use for code in direct control of the
  190. loop.
  191. ```text
  192. you ↔ coding agent ↔ hr CLI ↔ Manager service ↔ DAG nodes
  193. (planning) (coordination) (execution)
  194. ```
  195. The Manager Agent is still the right choice when you want HomeRail to plan and
  196. run a workflow end-to-end from a single request, especially by voice. Driving
  197. the CLI yourself is the right choice when you are building or tuning the DAG.
  198. ## Architecture
  199. | Package | Role |
  200. | --- | --- |
  201. | `homerail_protocol` | Shared message and validation contracts — single source of truth for runtime communication. |
  202. | `homerail_manager` | Manager service and DAG coordinator. Owns the voice surface and the generated-UI contract. |
  203. | `homerail_node` | Node service. Provisions Docker-backed Worker containers. |
  204. | `homerail_worker` | Worker runtime. Harness adapters for Claude Agent SDK and compatible agent backends. |
  205. | `homerail_cli` | The `hr` CLI. Configures, runs, and inspects DAG workflows. |
  206. | `agent-ui` | Decoupled browser UI for operating the Manager. Renders voice surface and widgets. |
  207. Manager and Node run as local services. Manager is not expected to run inside
  208. the Worker image. Node creates Worker containers; Workers for one run share
  209. `${HOMERAIL_HOME}/workspace/<run_id>`.
  210. ### Smart brain, efficient workers
  211. The expensive model should not do everything. Each DAG node runs in its own
  212. context window: it receives the handoff it needs, does its part, and passes
  213. evidence forward. Context never balloons into one giant thread, and nothing gets
  214. compressed under pressure just to fit. Because nodes are independent, each can
  215. use a different model — the smartest model plans and reviews; cheaper, more
  216. token-efficient models do the bulk of the work. Templates express this through a
  217. per-agent `provider` / `model` mapping, with a `"*"` wildcard as the fallback
  218. default.
  219. ## Configuration
  220. `HOMERAIL_HOME` is the local data root — where Manager state, run workspaces,
  221. logs, and the worker image cache land. It defaults to `~/.homerail` and can grow
  222. quickly: every DAG run writes its artifacts under
  223. `${HOMERAIL_HOME}/workspace/<run_id>/`, and these accumulate across runs. Point
  224. it at a disk with room (a NAS mount, a large external volume) before you start
  225. running real work:
  226. ```bash
  227. export HOMERAIL_HOME="/mnt/nas/homerail"
  228. ```
  229. Provider credentials are stored in the Manager encrypted settings store, never
  230. in repo files. Configure a model from the provider catalog:
  231. ```bash
  232. hr model configure <provider-or-endpoint-alias> \
  233. --endpoint-id <endpoint-id> \
  234. --model-name <model-id> \
  235. --api-key-stdin
  236. hr model list
  237. ```
  238. After a model is configured, run the full public smoke DAG. It exercises the
  239. five-node path (plan → implement → test → review → summarize) and verifies both
  240. scorecard and eval-run:
  241. ```bash
  242. hr smoke dag \
  243. --template assets/orchestrations/public-dev-5node.yaml.template
  244. ```
  245. A passing smoke writes its artifacts to the shared run workspace:
  246. ```text
  247. ${HOMERAIL_HOME}/workspace/<run_id>/snake-game/index.html
  248. ${HOMERAIL_HOME}/workspace/<run_id>/snake-game/TESTS.md
  249. ```
  250. The CLI resolves the Manager URL in this order: `--base-url`,
  251. `HOMERAIL_MANAGER_URL`, `${HOMERAIL_HOME}/config.json`, then
  252. `http://localhost:19191`.
  253. Android Live Voice access from the bundled WebView is disabled by default.
  254. To opt in on a trusted LAN, set this variable in the Manager process environment
  255. and start (or restart) Manager:
  256. ```bash
  257. export HOMERAIL_ANDROID_LIVE_VOICE_ENABLED=1
  258. hr start --host 0.0.0.0 --ui
  259. ```
  260. If Manager is already running, restart it after changing the environment.
  261. Only the value `1` enables this exception. It allows the exact Origin
  262. `https://appassets.androidplatform.net` for `POST /api/voice-agent/sessions/:id/live-ticket`
  263. (including its preflight) and the ticket-authenticated `/api/voice-agent/sessions/:id/live`
  264. WebSocket. Other Manager mutation endpoints keep their existing Origin rules;
  265. this switch does not add the Android Origin to `HOMERAIL_MANAGER_ADMIN_ORIGINS`.
  266. Unset the variable or set it to `0` and restart to remove the exception.
  267. The appassets domain is shared by Android apps using WebViewAssetLoader and is
  268. not proof of a HomeRail installation. Enabling this switch permits any reachable
  269. client using that Origin to obtain a Live Voice ticket and invoke the voice agent;
  270. the short-lived ticket is not device authentication. Enable it only on a network
  271. you trust, not an unprotected public Manager. An explicitly configured global
  272. `HOMERAIL_MANAGER_ADMIN_ORIGINS` entry remains authoritative even with this switch
  273. off; remove any appassets entry there if you want default rejection.
  274. For reverse-proxied public access, advertise external endpoints and bind the UI
  275. to the machine IP:
  276. ```bash
  277. hr start --ui --public \
  278. --public-url https://homerail.example.com \
  279. --ui-public-url https://homerail-ui.example.com
  280. ```
  281. `--ui-public-url` (or `HOMERAIL_UI_PUBLIC_URL`) must be an exact `http(s)`
  282. Origin — no wildcard, path, query, fragment, or credentials. HomeRail rejects
  283. anything else at startup instead of silently trusting a truncated Origin. The
  284. same canonical Origin is shared with the Manager admin allowlist
  285. (`HOMERAIL_MANAGER_ADMIN_ORIGINS`) and with the static Agent UI proxy, which
  286. authorizes protected UI mutations from either the explicitly configured public
  287. Origin or a request-derived localhost/literal-IP Origin. Named LAN hosts such
  288. as `homerail.lan`, mDNS names, and custom domains must be pinned with
  289. `--ui-public-url`; otherwise protected mutations and the browser-renderer ticket
  290. fail closed with HTTP 403. This prevents an arbitrary DNS-rebinding Host from
  291. being promoted to the trusted Manager proxy hop. `Forwarded` and
  292. `X-Forwarded-*` headers are never trusted for this decision.
  293. FN Connect (fnOS) rewrites the Host it forwards to HomeRail, so the browser
  294. Origin no longer matches the internal Host. Configure the exact public Origin
  295. the proxy presents:
  296. ```bash
  297. # Browser loads https://homerail.fn.example; FN Connect forwards the request
  298. # to HomeRail with an internal Host such as 127.0.0.1:19192.
  299. hr start --ui \
  300. --ui-public-url https://homerail.fn.example
  301. ```
  302. Generic Tailscale Serve / nginx / Caddy setups work the same way: terminate
  303. TLS in the proxy, forward to the local Agent UI port, and configure the public
  304. Origin:
  305. ```bash
  306. hr start --ui --public \
  307. --ui-public-url https://homerail.tail1234.ts.net
  308. ```
  309. Worker containers connect back to the Manager through the URL Manager passes to
  310. Node. On Docker Desktop the default `host.docker.internal` mapping is usually
  311. enough; on Linux use Docker `host-gateway` support or set
  312. `HOMERAIL_MANAGER_WORKER_WS_BASE_URL`. Do not hardcode Docker bridge addresses.
  313. Remote Worker and Node connections require authenticated `wss://` endpoints;
  314. see [Control-Plane WebSocket Security](docs/control-plane-security.md) for token,
  315. reverse-proxy, certificate, and compatibility settings.
  316. Worker image builds default to the base image's Debian sources and the
  317. default npm registry. Operators in restricted networks can opt in to public
  318. mirrors with `HOMERAIL_WORKER_BUILD_APT_MIRROR`,
  319. `HOMERAIL_WORKER_BUILD_APT_SECURITY_MIRROR`, and
  320. `HOMERAIL_WORKER_BUILD_NPM_REGISTRY`; standard `HTTP_PROXY`/`HTTPS_PROXY`/
  321. `NO_PROXY` variables are forwarded to Docker by name only, and their values
  322. are never captured by HomeRail. See
  323. [Worker build network sources](docs/worker-build-network.md) for the
  324. validation contract, security boundaries, and fnOS integration notes.
  325. Runtime helpers:
  326. ```bash
  327. hr runtime status
  328. hr runtime logs
  329. hr runtime stop
  330. hr ui status
  331. hr ui logs
  332. hr ui stop
  333. ```
  334. ## Project direction
  335. HomeRail is heading toward a resident agent on the home datacenter — voice in,
  336. generated UI out, multiple nodes and terminals (phone, tablet, TV, car). The
  337. foundation here is the first step; see [ROADMAP.md](ROADMAP.md) for the plan.
  338. For the voice Manager Agent, **Codex (`codex_appserver`) is the recommended
  339. harness today**: it is the only path that auto-synthesizes the `commentary`
  340. speech channel from the model's native reasoning stream, so the user hears
  341. progress while work happens. `claude-sdk` and `kimi-code` are silent during
  342. execution — this is a provider capability gap, not something HomeRail can
  343. close. An experimental `deepseek_harness` backend now runs the owner-maintained
  344. [DSH fork](docs/architecture/deepseek-harness-integration.md) out of process and
  345. maps its reasoning stream into HomeRail thinking events; it is not yet the
  346. recommended Manager Agent runtime.
  347. ## License
  348. MIT. See [LICENSE](LICENSE).
  349. For unattended Auto Fix and PR checks, see [durable event supervision](docs/scenarios/event-supervision.md) for persistent Linux monitoring and result recovery.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.