homerail

What it is

HomeRail is a TypeScript runtime that turns one-off agent chats into auditable, reusable workflows. It runs on a user’s homelab, NAS, or home server, using a DAG-based execution model with explicit handoffs and run replay capabilities. The project includes a CLI (hr), a voice surface, and a generated UI contract, aiming to provide a resident home-datacenter agent with voice input and structured, readable views.

How it works

The runtime centers on a DAG engine where multiple agents and environments exchange work across explicit edges. Each run creates a workspace under HOMERAIL_HOME, with Node services provisioning Docker-backed Worker containers, one per DAG node, sharing a workspace per run. Templates define workflows; provider/model mappings in templates enable per-agent model selection. The system supports a Manager service and a Node service, with Workers executing per-run tasks and producing audit trails and scorecards.

Key components:

• homerail_cli: The hr CLI for configuring, running, and inspecting DAGs.
• homerail_manager: Manager service and DAG coordinator; owns the voice surface and UI contract.
• homerail_node: Node service provisioning worker containers.
• homerail_worker: Worker runtime interfacing with Claude/KimI-style SDKs and compatible backends.
• agent-ui: Decoupled browser UI for the Manager.

Getting started

Prerequisites and platform notes are provided in the Quickstart:

• Node.js 20+ and npm 10+
• Docker
• A Claude Agent SDK-compatible model endpoint

Install and build commands (as written in README):

npm run install:all
npm run build

npm run ci

Additional local CI commands:

npm run ci:local
npm run ci:local -- core-linux

CLI setup:

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

Start and check:

hr start

hr doctor

Run a topology with a two-node template:

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

For 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 --host 0.0.0.0 to expose beyond localhost.

Recent releases

• none

Traction

• GitHub stars: 506
• Forks: 118
• Open issues: 5

Caveats

• License: MIT
• Creation date: 2026-07-07
• Last push: 2026-07-13
• Language: TypeScript

Behind the repo

• Organization: xiaotianfotos
• Repository name: homerail