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.
Badge for your README
Markdown
[](/listings/xiaotianfotos--homerail)HTML
<a href="/listings/xiaotianfotos--homerail"><img src="/api/listings/xiaotianfotos--homerail/badge.svg" alt="findsafeskills safety rating" /></a>Install
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)
- # HomeRail
- English | [中文](README.zh-CN.md)
- HomeRail is a TypeScript runtime that turns one-off agent chats into auditable,
- reusable workflows. The name comes from what it is: **Home** — it runs on your
- own homelab, NAS, or home server, serving the people who live there; **Rail** —
- the track shape of a DAG, where agent work flows node to node along explicit
- edges instead of pooling in a single chat. The design bet is that a person's
- attention is the scarcest resource in any automation, so the system should ask
- for very little of it.
- The long-term shape is a resident home-datacenter agent you talk to — voice in,
- a generated interface out, a DAG of agents doing the work behind it. What is in
- this tree today is the foundation it runs on: a DAG engine, a CLI, a voice
- surface, and the first steps toward a generated UI.
- ## Why
- Human bandwidth is narrow; the work we want done is not. HomeRail is shaped like
- an inverted funnel that widens toward the machine:
- - **Voice** — the preferred input, because it asks the least of you. You speak;
- the agent listens, confirms, and narrows ambiguity before doing anything. Text
- is always available too — for quiet settings, for precision, or for anyone not
- ready to talk to their computer yet.
- - **Generative UI** — the agent does not dump logs or JSON at you. The interface
- is generated for the moment and shaped to be easy to read.
- - **DAG** — the execution engine behind both. Multiple agents, multiple roles,
- multiple environments, with every handoff traced and every run replayable.
- A chat session is a black box. A DAG is a graph you can inspect, replay, and
- improve. HomeRail is what sits between the two — narrow where the person is,
- wide where the machine is.
- ## What works today
- - **DAG runtime** *(most mature)* — multi-agent orchestration with explicit
- handoffs, workspace isolation per run, replay, scorecards, and run evaluation.
- - **CLI `hr`** — `start`, `config`, `doctor`, `run`, `smoke`, `dag supervise`,
- `scorecard`, `eval-run`, `replay`. The primary way to operate HomeRail.
- - **Voice surface** — a Voice Surface Contract with ASR / TTS / VAD, Chinese by
- default, served through a desktop voice shell. The agent collects intent
- across turns before acting.
- - **Generative UI** *(in exploration)* — instead of dumping logs or JSON, the
- agent produces structured, generated views meant to be read at a glance. The
- shape of these views is still being designed through real use cases; the
- contract and the widget set will keep changing.
- - **Docker Worker** — Manager and Node run as local services; Node uses Docker
- to provision Worker containers, one per DAG node, sharing a workspace per run.
- ## Hand this README to an agent
- HomeRail is designed to be operated by agents as much as by people. This README
- is written so that it doubles as an agent-readable runbook: the commands below
- are plain `hr` invocations with self-describing names, and each step says what
- to expect. You can hand the whole file to your agent (Claude Code, Codex, or
- any tool that can run shell commands and read output) and ask it to install,
- configure, and verify HomeRail on your machine following the Quickstart.
- ## Quickstart
- 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:
- ```bash
- 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:
- ```bash
- 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:
- ```bash
- 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:
- ```bash
- 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:
- ```bash
- 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:
- ```bash
- 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:
- ```bash
- 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.
- ## Run a DAG
- Load a template explicitly and run it:
- ```bash
- hr templates list
- hr run assets/orchestrations/public-two-node.yaml.template \
- --prompt "Draft a short project checklist"
- ```
- For reusable workflows, sync the DAG into the Manager database. Keep
- `workflow_id` stable when editing YAML; changing it creates a new workflow
- identity.
- ```bash
- hr dag sync assets/orchestrations/public-dev-5node.yaml.template
- hr profile sync assets/profiles/example-runtime.profile.yaml.template \
- --workflow public-dev-5node-template
- hr run \
- --workflow public-dev-5node-template \
- --profile example-runtime \
- --prompt "Draft a short project checklist"
- ```
- Copy the returned `run_id`, then inspect it:
- ```bash
- hr dag supervise <run_id>
- hr scorecard <run_id>
- hr eval-run <run_id>
- ```
- For workflows that pause at a durable command boundary and resume selected
- logical actors under the same run, see [Multi-Round DAGs](docs/multi-round-dags.md).
- The guide covers strict WorkflowSpec v1 authoring, round fencing, CLI and HTTP
- commands, recovery, expiry, and concurrency-slot behavior.
- An optional [tokenizer-based local-model route](docs/e2e-fix-token-admission.md) checks complete requests and preserves the configured output reserve before forwarding.
- [E2E Fix](docs/e2e-fix.md) accepts a fixed caller design. A local Fixer develops
- and passes trusted tests before publishing or updating the same PR for independent
- model review. Insufficient approvals or failed CI feed a fresh Fixer session.
- New tasks have no Codex dependency and no Planner/Judger nodes: the configured
- review majority and same-head CI determine acceptance. Design, candidate history
- and per-round evidence persist; see [recovery boundaries](docs/e2e-fix-recovery.md).
- Older frozen host Codex tasks remain readable; new preparation rejects that configuration.
- Trusted candidate snapshots normalize storage permissions and pass validation
- before publication; invalid published snapshots are rejected without rewriting.
- DSH provides bounded, content-free output byte diagnostics to distinguish
- observed reasoning, text and tool arguments; these are not token budgets.
- The program-only watcher also alerts when a failed host stage remains RUNNING,
- while expected failures handled by the repair loop stay quiet.
- See the same guide for evidence requirements and remaining recovery limits.
- For a topology check without a live model provider, the two-node template ships
- an offline deterministic profile:
- ```bash
- hr run assets/orchestrations/public-two-node.yaml.template \
- --profile offline-deterministic \
- --prompt "Draft a short checklist for a backend release"
- ```
- HomeRail also ships a Manager-backed [DAG pattern library](docs/dag-patterns.md)
- for reusable control-flow designs such as quorum, bounded ratchets, standing
- goal verification, and planner/worker fan-out:
- ```bash
- hr patterns list
- hr patterns show quorum
- hr patterns instantiate quorum --set workflow_id=release-quorum --set threshold=2
- ```
- Manager Agent discovers every `SKILL.md` directory under
- `${HOMERAIL_HOME:-$HOME/.homerail}/skills` on each turn and installs missing
- built-in `homerail-*` skills there as links. A pattern request can therefore be
- handled without shell commands: Manager Agent reads `homerail-dag-patterns`,
- selects and instantiates a catalog pattern, syncs it, and starts the returned
- workflow through Manager tools.
- ## Drive the CLI from a coding agent
- There is a second way to use HomeRail, beyond speaking to the Manager Agent or
- typing commands yourself. A coding agent you already trust — Codex, Claude
- Code, or any tool that can run shell commands — can drive the `hr` CLI
- directly: `templates list`, `run`, `dag supervise`, `scorecard`, `replay`.
- This skips the Manager Agent layer (the AI that plans a DAG from a request),
- but not the Manager service (the DAG coordinator). Your coding agent takes over
- the planning role: it reads a template, decides what to change, runs the DAG,
- inspects the result, and iterates. This is the natural loop for developing and
- debugging DAGs and templates — you get the full audit trail and evaluation of
- the DAG runtime, with a model you already use for code in direct control of the
- loop.
- ```text
- you ↔ coding agent ↔ hr CLI ↔ Manager service ↔ DAG nodes
- (planning) (coordination) (execution)
- ```
- The Manager Agent is still the right choice when you want HomeRail to plan and
- run a workflow end-to-end from a single request, especially by voice. Driving
- the CLI yourself is the right choice when you are building or tuning the DAG.
- ## Architecture
- | Package | Role |
- | --- | --- |
- | `homerail_protocol` | Shared message and validation contracts — single source of truth for runtime communication. |
- | `homerail_manager` | Manager service and DAG coordinator. Owns the voice surface and the generated-UI contract. |
- | `homerail_node` | Node service. Provisions Docker-backed Worker containers. |
- | `homerail_worker` | Worker runtime. Harness adapters for Claude Agent SDK and compatible agent backends. |
- | `homerail_cli` | The `hr` CLI. Configures, runs, and inspects DAG workflows. |
- | `agent-ui` | Decoupled browser UI for operating the Manager. Renders voice surface and widgets. |
- Manager and Node run as local services. Manager is not expected to run inside
- the Worker image. Node creates Worker containers; Workers for one run share
- `${HOMERAIL_HOME}/workspace/<run_id>`.
- ### Smart brain, efficient workers
- The expensive model should not do everything. Each DAG node runs in its own
- context window: it receives the handoff it needs, does its part, and passes
- evidence forward. Context never balloons into one giant thread, and nothing gets
- compressed under pressure just to fit. Because nodes are independent, each can
- use a different model — the smartest model plans and reviews; cheaper, more
- token-efficient models do the bulk of the work. Templates express this through a
- per-agent `provider` / `model` mapping, with a `"*"` wildcard as the fallback
- default.
- ## Configuration
- `HOMERAIL_HOME` is the local data root — where Manager state, run workspaces,
- logs, and the worker image cache land. It defaults to `~/.homerail` and can grow
- quickly: every DAG run writes its artifacts under
- `${HOMERAIL_HOME}/workspace/<run_id>/`, and these accumulate across runs. Point
- it at a disk with room (a NAS mount, a large external volume) before you start
- running real work:
- ```bash
- export HOMERAIL_HOME="/mnt/nas/homerail"
- ```
- Provider credentials are stored in the Manager encrypted settings store, never
- in repo files. Configure a model from the provider catalog:
- ```bash
- hr model configure <provider-or-endpoint-alias> \
- --endpoint-id <endpoint-id> \
- --model-name <model-id> \
- --api-key-stdin
- hr model list
- ```
- After a model is configured, run the full public smoke DAG. It exercises the
- five-node path (plan → implement → test → review → summarize) and verifies both
- scorecard and eval-run:
- ```bash
- hr smoke dag \
- --template assets/orchestrations/public-dev-5node.yaml.template
- ```
- A passing smoke writes its artifacts to the shared run workspace:
- ```text
- ${HOMERAIL_HOME}/workspace/<run_id>/snake-game/index.html
- ${HOMERAIL_HOME}/workspace/<run_id>/snake-game/TESTS.md
- ```
- The CLI resolves the Manager URL in this order: `--base-url`,
- `HOMERAIL_MANAGER_URL`, `${HOMERAIL_HOME}/config.json`, then
- `http://localhost:19191`.
- Android Live Voice access from the bundled WebView is disabled by default.
- To opt in on a trusted LAN, set this variable in the Manager process environment
- and start (or restart) Manager:
- ```bash
- export HOMERAIL_ANDROID_LIVE_VOICE_ENABLED=1
- hr start --host 0.0.0.0 --ui
- ```
- If Manager is already running, restart it after changing the environment.
- Only the value `1` enables this exception. It allows the exact Origin
- `https://appassets.androidplatform.net` for `POST /api/voice-agent/sessions/:id/live-ticket`
- (including its preflight) and the ticket-authenticated `/api/voice-agent/sessions/:id/live`
- WebSocket. Other Manager mutation endpoints keep their existing Origin rules;
- this switch does not add the Android Origin to `HOMERAIL_MANAGER_ADMIN_ORIGINS`.
- Unset the variable or set it to `0` and restart to remove the exception.
- The appassets domain is shared by Android apps using WebViewAssetLoader and is
- not proof of a HomeRail installation. Enabling this switch permits any reachable
- client using that Origin to obtain a Live Voice ticket and invoke the voice agent;
- the short-lived ticket is not device authentication. Enable it only on a network
- you trust, not an unprotected public Manager. An explicitly configured global
- `HOMERAIL_MANAGER_ADMIN_ORIGINS` entry remains authoritative even with this switch
- off; remove any appassets entry there if you want default rejection.
- For reverse-proxied public access, advertise external endpoints and bind the UI
- to the machine IP:
- ```bash
- hr start --ui --public \
- --public-url https://homerail.example.com \
- --ui-public-url https://homerail-ui.example.com
- ```
- `--ui-public-url` (or `HOMERAIL_UI_PUBLIC_URL`) must be an exact `http(s)`
- Origin — no wildcard, path, query, fragment, or credentials. HomeRail rejects
- anything else at startup instead of silently trusting a truncated Origin. The
- same canonical Origin is shared with the Manager admin allowlist
- (`HOMERAIL_MANAGER_ADMIN_ORIGINS`) and with the static Agent UI proxy, which
- authorizes protected UI mutations from either the explicitly configured public
- Origin or a request-derived localhost/literal-IP Origin. Named LAN hosts such
- as `homerail.lan`, mDNS names, and custom domains must be pinned with
- `--ui-public-url`; otherwise protected mutations and the browser-renderer ticket
- fail closed with HTTP 403. This prevents an arbitrary DNS-rebinding Host from
- being promoted to the trusted Manager proxy hop. `Forwarded` and
- `X-Forwarded-*` headers are never trusted for this decision.
- FN Connect (fnOS) rewrites the Host it forwards to HomeRail, so the browser
- Origin no longer matches the internal Host. Configure the exact public Origin
- the proxy presents:
- ```bash
- # Browser loads https://homerail.fn.example; FN Connect forwards the request
- # to HomeRail with an internal Host such as 127.0.0.1:19192.
- hr start --ui \
- --ui-public-url https://homerail.fn.example
- ```
- Generic Tailscale Serve / nginx / Caddy setups work the same way: terminate
- TLS in the proxy, forward to the local Agent UI port, and configure the public
- Origin:
- ```bash
- hr start --ui --public \
- --ui-public-url https://homerail.tail1234.ts.net
- ```
- Worker containers connect back to the Manager through the URL Manager passes to
- Node. On Docker Desktop the default `host.docker.internal` mapping is usually
- enough; on Linux use Docker `host-gateway` support or set
- `HOMERAIL_MANAGER_WORKER_WS_BASE_URL`. Do not hardcode Docker bridge addresses.
- Remote Worker and Node connections require authenticated `wss://` endpoints;
- see [Control-Plane WebSocket Security](docs/control-plane-security.md) for token,
- reverse-proxy, certificate, and compatibility settings.
- Worker image builds default to the base image's Debian sources and the
- default npm registry. Operators in restricted networks can opt in to public
- mirrors with `HOMERAIL_WORKER_BUILD_APT_MIRROR`,
- `HOMERAIL_WORKER_BUILD_APT_SECURITY_MIRROR`, and
- `HOMERAIL_WORKER_BUILD_NPM_REGISTRY`; standard `HTTP_PROXY`/`HTTPS_PROXY`/
- `NO_PROXY` variables are forwarded to Docker by name only, and their values
- are never captured by HomeRail. See
- [Worker build network sources](docs/worker-build-network.md) for the
- validation contract, security boundaries, and fnOS integration notes.
- Runtime helpers:
- ```bash
- hr runtime status
- hr runtime logs
- hr runtime stop
- hr ui status
- hr ui logs
- hr ui stop
- ```
- ## Project direction
- HomeRail is heading toward a resident agent on the home datacenter — voice in,
- generated UI out, multiple nodes and terminals (phone, tablet, TV, car). The
- foundation here is the first step; see [ROADMAP.md](ROADMAP.md) for the plan.
- For the voice Manager Agent, **Codex (`codex_appserver`) is the recommended
- harness today**: it is the only path that auto-synthesizes the `commentary`
- speech channel from the model's native reasoning stream, so the user hears
- progress while work happens. `claude-sdk` and `kimi-code` are silent during
- execution — this is a provider capability gap, not something HomeRail can
- close. An experimental `deepseek_harness` backend now runs the owner-maintained
- [DSH fork](docs/architecture/deepseek-harness-integration.md) out of process and
- maps its reasoning stream into HomeRail thinking events; it is not yet the
- recommended Manager Agent runtime.
- ## License
- MIT. See [LICENSE](LICENSE).
- 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 inFree to use. If it’s helped, pass it on.