Homerail Install Ops

HomeRail Install Ops

Before acting, apply homerail-shared rules. This pre-publication flow uses a local source checkout or local Git clone, not npm publication.

Local Skill Install

Install HomeRail skills by linking the checkout's skills/homerail-* directories into the target agent skill directory. Prefer symlinks over copies so skill updates follow git pull.

If the source tree is already present, use skills/README.md as the source of truth for Codex and Claude Code install targets. On macOS/Linux:

repo=/path/to/HomeRail

for root in "${CODEX_HOME:-$HOME/.codex}/skills" "$HOME/.claude/skills"; do
  mkdir -p "$root"
  for skill in "$repo"/skills/homerail-*; do
    [ -d "$skill" ] || continue
    name="$(basename "$skill")"
    dst="$root/$name"
    if [ -L "$dst" ]; then
      rm "$dst"
    elif [ -e "$dst" ]; then
      echo "Refusing to replace existing non-symlink skill: $dst" >&2
      continue
    fi
    ln -s "$skill" "$dst"
  done
done

If the user gives a local Git address, clone it first, then install links from the checkout:

git clone <local-homerail-git-url> HomeRail
cd HomeRail

On Windows, use PowerShell directory symlinks when Developer Mode or Administrator permissions allow them. If symlinks are blocked, use a junction as the local fallback; repeat the junction for every skills/homerail-* directory that should be installed:

cmd /c mklink /J "%USERPROFILE%\.claude\skills\homerail-install-ops" "C:\path\to\HomeRail\skills\homerail-install-ops"

After installing or updating skills, ask the user to restart the AI agent session if their agent host only loads skills on startup.

After restart, route user requests to the root skills this way:

• Use homerail-install-ops for first install, update, service startup, provider configuration, and smoke verification. Codex invocation: $homerail-install-ops; Claude Code invocation: /homerail-install-ops.
• Use homerail-dag-ops for the full DAG lifecycle: pattern selection, workflow authoring, execution, background supervision, decisions and output inspection. Its references cover advanced modes; no separate supervision skill is needed.
• Use homerail-cli for command syntax, flags, and evidence commands.
• Use homerail-shared as background rules for all HomeRail operations.

Deploy From Local Source

Run from the source root:

npm run install:all
npm run build
npm run typecheck
npm test
npm run ci

Prepare a local data root:

export HOMERAIL_HOME="${HOMERAIL_HOME:-$HOME/.homerail}"

Configure local runtime settings and credentials through the CLI:

node homerail_cli/dist/cli.js config

Start Manager and Node together:

node homerail_cli/dist/cli.js start
node homerail_cli/dist/cli.js start --rebuild-worker-image
node homerail_cli/dist/cli.js start --ui
node homerail_cli/dist/cli.js doctor

hr start uses the shared HOMERAIL_HOME, starts Manager if needed, applies stored model config, builds homerail-worker:latest when missing, and starts a Node with Docker capability when no configured Node is connected. Use --rebuild-worker-image after Worker runtime changes so provisioned DAG workers run the current checkout. Use --ui or node homerail_cli/dist/cli.js ui start to start the decoupled Agent UI. HTTPS is the default endpoint, https://localhost:19192, and HTTP is kept as a fallback on http://localhost:19193. If provider credentials are not configured yet, hr start should still bring up Manager and Node; hr doctor reports the missing model or Manager Agent runtime configuration and the agent should run hr config / hr model configure.

Use node homerail_cli/dist/cli.js runtime status|logs|stop for service inspection and cleanup. Use node homerail_cli/dist/cli.js ui status|logs|stop for UI-only inspection and cleanup.

hr doctor is the first environment probe an agent needs for normal operation. Do not supplement it with ps, lsof, curl /health, or source reading unless the CLI output is insufficient for a concrete failure. It reports, per line: manager reachability + URL, runtime state (connected nodes/workers, active runs, node capabilities), node count, any active LLM model setting, and the Manager Agent runtime/harness readiness. A HomeRail is ready. trailer is the readiness gate; any FAIL/WARN line names the exact next command to run (e.g. hr model configure).

connected_workers: 0 is expected on an idle Manager. DAG Workers are provisioned on demand by a Node into Docker containers when a run dispatches; there is no standing worker to inspect or start by hand. connected_nodes >= 1 is what matters for DAGs to run.

The local harness deployment diagnosis DAG runs through the same Worker provisioning path as normal DAGs. Do not start a fixed host Worker, mount the Docker socket into a Worker, or use Docker-in-Docker for this test. The diagnosis run uses its isolated workspace, clones the latest source, builds it, configures the cloned CLI to talk to the outer Manager, and verifies runtime status / doctor. Deployment diagnosis uses advisory scorecard enforcement; inspect findings, but use terminal status and structured handoff evidence as the deployment result.