HomeRail: a local DAG runtime for auditable agent workflows

The black box HomeRail is trying to replace

A chat session with an agent leaves you with a transcript. You can scroll it, but you cannot replay it, diff it, or hand a specific step to a different model. HomeRail's stated design bet is that a person's attention is the scarcest resource in any automation, and the artifact it produces instead of a transcript is a run: a DAG with explicit edges, a run_id, and per-run workspace isolation. The intended audience is narrow and specific. It is someone with a homelab, NAS or home server who already runs Docker and wants agent work to be inspectable after the fact. The README frames the wider ambition as a resident home-datacenter agent you talk to, but it also states plainly that what is in the tree today is the foundation: a DAG engine, a CLI, a voice surface, and the first steps toward a generated UI. Read the second list, not the first, when deciding whether it fits.

Manager, Node, Worker: the three processes behind a run

The runtime is split across separate packages in the repository: homerail_manager, homerail_node, homerail_worker, homerail_cli, homerail_protocol and homerail_plugin_sdk, plus agent-ui. Manager and Node run as local services. Node uses Docker to provision Worker containers, one per DAG node, and those workers share a workspace per run. That per-node container model is the mechanism behind the auditability claim: each step of the graph executes in its own container, so the handoff between nodes is a real boundary rather than a function call inside one process. The protocol package and the plugin SDK sit alongside this, which suggests the boundaries are meant to be contract-driven rather than ad hoc. The practical consequence is that a single run costs you at least one container, and the Node process needs a working route to Docker and a callback path back to Manager. On Linux the README warns that worker-to-Manager networking may need extra setup and points at the Configuration notes on Worker callback URLs. That is the part of the architecture most likely to bite you first.

Installing HomeRail from a source checkout

There is no published install path in the README. It instructs you to install and build from a source checkout, and the root package.json is marked private, so the entry point is the repository itself. Requirements are Node.js 20+ and npm 10+, Docker for the Worker containers, and a Claude Agent SDK-compatible model endpoint for live agent runs. On macOS the README says the default host.docker.internal mapping works out of the box; on Windows you need Docker Desktop and a POSIX-compatible shell such as Git Bash, because some scripts assume a Unix-like shell and will not run correctly under cmd.exe or PowerShell.

npm run install:all
npm run build

The install:all script runs npm ci in each package directory in turn, so expect it to take a while and to fail loudly if any single package cannot resolve its dependencies. Once built, link the CLI so the rest of the guide works as written, then confirm it responds.

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

Start Manager and Node together. Manager becomes available without waiting for Docker, and the README notes that hr start --rebuild-worker-image queues the image build asynchronously rather than blocking startup.

hr start
hr doctor

The doctor command reports Manager reachability, Node availability, the active model setting, and whether the Manager Agent harness can resolve a runtime. That output is the fastest way to find out whether your environment is actually usable. If you also want the browser Agent UI, hr start --ui brings it up. Defaults are Manager on http://localhost:19191, Agent UI on https://localhost:19192, and an HTTP fallback on http://localhost:19193. Manager binds to 127.0.0.1 by default; the README says to use hr start --host 0.0.0.0 only when you intentionally want it reachable beyond localhost, which is the right default for something sitting on a home network.

A first run that needs no model provider

The gentlest first run is the offline deterministic profile. It uses the two-node template and does not need a model provider, which makes it the right way to check that the plumbing works before you debug credentials.

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. Pass that id to hr dag supervise if you want to watch the handoff flow between nodes. For a reusable workflow the README describes a different path: sync the DAG into the Manager database, sync a runtime profile against it, and then run by workflow name rather than by file path.

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"

One detail worth internalising before you edit any YAML: the README says to keep workflow_id stable when editing, because changing it creates a new workflow identity. After a run, hr scorecard and hr eval-run take the same run_id and are the two commands that produce the evaluation artifacts the project is named around.

Where the beta shows its edges

The generated UI is the weakest part of the current tree, and the README says so directly: it is in exploration, the shape of the views is still being designed through real use cases, and the contract and widget set will keep changing. Do not build on that surface yet. The version string tells a similar story. The releases are v0.1.0-alpha.2.2, v0.1.0-alpha.3 and v0.1.0-beta.1, all dated within days of each other in late July and early August 2026, which is the cadence of a project still settling its interfaces rather than one holding a stable line. The last push to the repository was on 2026-08-01, so there is no evidence of activity after that date. The Windows story is a genuine constraint: the local CI runner covers the Linux core, UI coverage and Docker smoke jobs, and the README states that the Windows job remains on GitHub's windows-latest runner, so you cannot reproduce that environment locally with the documented tooling. And if your workflow is a single prompt with a single answer, the DAG machinery, the per-node containers and the workspace isolation are overhead you will pay for and never use.

When a plain agent CLI is the better fit

The obvious alternative is to stay with the agent CLI you already have, such as Claude Code or Codex, and drive it directly from a shell script. The README itself suggests handing it the HomeRail README as a runbook, which is a fair description of how those tools are normally used. The difference in approach is structural. A shell script plus an agent CLI gives you a linear sequence of prompts with no per-step container boundary, no run_id you can hand to a supervisor, and no scorecard or eval-run artifact. HomeRail trades that simplicity for a graph you can inspect and replay, and it charges you for the trade in Docker containers, a Manager process, a Node process, and a database that holds synced workflows. If you need multi-role handoffs with an auditable record of what each node received and produced, the script approach will not get you there. If you need one prompt answered, it is strictly less work.

Licence, releases and what an upgrade costs

HomeRail is MIT licensed, and the root package.json carries the same identifier. For a private, unpublished root package that is a permissive arrangement: you can read the source, modify it and run it locally without a copyleft obligation propagating into your own work. This is not legal advice; if you intend to redistribute a modified tree, read the LICENSE file in the repository rather than this paragraph. The upgrade cost is the more practical question. Because there is no published package, upgrading means pulling the repository and re-running npm run install:all and npm run build, then rebuilding the Worker image, which the README says can be queued asynchronously with hr start --rebuild-worker-image. The README does not document rollback, so there is no stated procedure for returning to a previous version if a build breaks your setup. Keep your YAML templates and profiles in version control separately from the checkout, since the workflow_id stability rule means a renamed identity is not a reversible edit.

Editorial conclusion

Adopt HomeRail if you already run Docker and want agent work expressed as an inspectable DAG rather than a chat log, and you are willing to build from a source checkout. Do not adopt it if you need a supported release, a stable generated-UI contract, or Windows support without a POSIX shell. Verify first that Node.js 20+ and Docker are present, that hr doctor reports a resolvable Manager Agent harness, and that your model endpoint is Claude Agent SDK-compatible, since the offline-deterministic profile is the only path that runs without one.

Frequently asked questions

Official sources

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