HomeRail: a voice-first runtime for agent workflows you can replay

The name is the architecture: Home and Rail

The README explains the name as the design. Home is where it runs, on your own homelab, NAS or home server, serving the people who live there. Rail is the track shape of a DAG, where agent work flows node to node along explicit edges instead of pooling in a single chat.

The bet underneath is a single claim: a person's attention is the scarcest resource in any automation, so the system should ask for very little of it. Everything in the architecture follows from that, including the inverted funnel shape where the system is narrow where the person is and wide where the machine is.

The long-term shape is described as a resident home-datacenter agent you talk to: voice in, a generated interface out, and a DAG of agents doing the work behind it. What exists in the tree today is the foundation that runs on: a DAG engine, a CLI, a voice surface, and the first steps toward a generated UI.

That gap between the stated destination and the current state is worth keeping in mind when reading the feature list, since each item is labelled with how finished it is.

Voice is the input that asks the least of you

Voice is listed first among the reasons, and the argument is about cost rather than novelty: 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.

The mechanics are described as a Voice Surface Contract covering ASR, TTS and VAD, Chinese by default, served through a desktop voice shell. The behavioural detail is that the agent collects intent across turns before acting, which is what keeps a spoken request from becoming a wrong action on a half-heard sentence.

The second pillar is generative UI, where the agent does not dump logs or JSON at you but produces an interface generated for the moment and shaped to be easy to read. That one is explicitly marked as in exploration, with the caveat that the shape of the views is still being designed through real use cases and that the contract and the widget set will keep changing.

So the two interfaces the project says are still changing are also the two its pitch rests on, which is an honest thing for the README to admit.

A chat session is a black box, a DAG is a graph you can inspect

The sentence that argues the whole design is short: a chat session is a black box, a DAG is a graph you can inspect, replay and improve.

The DAG runtime is labelled the most mature part, and its feature list is specific about what that buys. Multi-agent orchestration with explicit handoffs, workspace isolation per run, replay, scorecards, and run evaluation. Multiple agents, multiple roles, multiple environments, with every handoff traced and every run replayable.

The CLI is named `hr` and is described as the primary way to operate HomeRail, with the commands listed as `start`, `config`, `doctor`, `run`, `smoke`, `dag supervise`, `scorecard`, `eval-run` and `replay`.

The infrastructure piece is a Docker Worker model: Manager and Node run as local services, and Node uses Docker to provision Worker containers, one per DAG node, sharing a workspace per run. That is why a run can be isolated and replayed, since each node gets a container and each run gets a workspace rather than sharing mutable state.

The inspection commands are the ones that make the graph legible: supervise a run, scorecard a run, evaluate a run.

Seven packages, no workspaces field, and a test script that names its files

The repository is a monorepo of seven npm packages plus a front end: `homerail_protocol/`, `homerail_plugin_sdk/`, `homerail_manager/`, `homerail_node/`, `homerail_worker/`, `homerail_cli/` and `agent-ui/`, alongside `assets/` for orchestration and profile templates, `docs/`, `plugins/`, `scripts/`, `skills/`, `ops/` and a `ROADMAP.md`.

The root manifest is private, MIT, and versioned `0.1.0-beta.1`, which matches the newest tag. There is no `workspaces` field, so the orchestration is done by hand in the scripts. `install:all` is a chain of seven `npm --prefix <package> ci` invocations, one per package, and `build` delegates to `build:packages`, which is the same seven-package chain running each build.

That approach means each package keeps its own lockfile and its own install, which is slower and more explicit than a workspace hoist.

The test script is the other thing worth naming. `test:live-validator` is a single `node --test` call that lists its test files explicitly, roughly two dozen of them, with names such as `native-codex-subscription-smoke`, `dag-pattern-live-contracts`, `desktop-release-contracts`, `live-runner-isolation`, `manager-only-restart-evidence`, `production-deploy-contracts` and `event-supervisor`, plus a subdirectory case at `scripts/judged-autofix/loop.test.mjs`.

The naming convention is the point: the filenames state what contract they check, so a failing test names its own guarantee.

hr doctor is the command that tells you whether anything works

The quickstart is a sequence of commands where each one reports something. Install and build come first with `npm run install:all` and `npm run build`, then the CLI is linked locally:

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

`hr start` brings Manager and Node up together, and the detail that saves a confusing first run is that Manager becomes available without waiting for Docker. Worker images are built or rebuilt asynchronously from Settings, Runtime Environment, and `hr start --rebuild-worker-image` queues that same build after Manager starts rather than blocking startup while Docker works.

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

The first topology check is designed to need nothing external:

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

It uses the two-node template's offline deterministic profile, so it does not need a model provider yet, and it returns a `run_id` you can watch with `hr dag supervise <run_id>`. Adding `--ui` to `hr start` also brings up the browser Agent UI.

Three fixed ports, and the Manager binds to loopback

The defaults are stated in one sentence and they are worth memorising before you hit a conflict: Manager on `http://localhost:19191`, Agent UI on `https://localhost:19192`, and an HTTP fallback on `http://localhost:19193`.

The Manager binds to `127.0.0.1` by default, and the guidance is to use `hr start --host 0.0.0.0` only when you intentionally want it reachable beyond localhost. That is a deliberate default for something designed to sit on a home network.

Platform notes are more specific than a single cross-platform claim. On macOS you install Docker Desktop and the default `host.docker.internal` mapping works out of the box. On Windows you need Docker Desktop, with either the WSL 2 or the Hyper-V backend working, and you must run the CLI from Git Bash or another POSIX-compatible shell because some scripts assume a Unix-like shell and will not run correctly under `cmd.exe` or PowerShell. On Linux you use Docker Engine, and Worker-to-Manager networking may need extra setup, with the Configuration notes on Worker callback URLs as the reference.

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

The README is written to be handed to an agent

One section is about the documentation itself: HomeRail is designed to be operated by agents as much as by people, and the README is written so it doubles as an agent-readable runbook. The commands are plain `hr` invocations with self-describing names, and each step says what to expect.

The instruction is to hand the whole file to Claude Code, Codex, or any tool that can run shell commands and read output, and ask it to install, configure and verify HomeRail following the Quickstart.

The continuous integration story supports that. `npm run ci` runs the deterministic checks directly, and `npm run ci:local` reproduces the Linux GitHub Actions jobs locally once you have Docker, `act` and `actionlint`. The local runner covers the Linux core, UI coverage and Docker smoke jobs, while the Windows job remains on GitHub's own `windows-latest` runner.

Two operational warnings come from the workflow section. For reusable workflows the DAG is synced into the Manager database, and `workflow_id` has to stay stable when editing YAML, because changing it creates a new workflow identity. And there is a separate guide for multi-round DAGs, workflows that pause at a durable command boundary and resume selected logical actors under the same run, covering strict WorkflowSpec v1 authoring, round fencing, and the CLI and HTTP commands involved.

The release history shows the project moving fast through pre-1.0 versions: v0.1.0-alpha.2.2 and v0.1.0-alpha.3 both on 2026-07-29, then v0.1.0-beta.1 on 2026-08-01, with the last push to `main` on 2026-09-25.

Editorial conclusion

HomeRail fits a household or small team that wants agent work to be inspectable after the fact, since the DAG, the per-run workspace and the scorecard and replay commands turn a finished run into something you can read rather than something you take on trust. It does not fit someone who wants a finished voice assistant today, since the generated interface is marked as still being designed and the version is a beta with no release after 2026-08-01. Check three things first: that your machine matches the platform notes, especially the POSIX shell requirement on Windows and the Worker callback networking on Linux; that you have a Claude Agent SDK-compatible endpoint before you attempt a live run, or use the offline deterministic profile that needs no provider at all; and that your ports 19191, 19192 and 19193 are free before you start, since all three are fixed defaults. Then run `hr doctor` before anything else, since it is the one command that tells you which layer is missing.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes