pipedai-orchestrator

PipedAI worker orchestrator — a local control plane that runs on the same host as your workers and lets an operator (or a BYOM client) build, register, monitor, start/stop, disable, and delete workers from one place. Distributed via npm as @pipedai/orchestrator.

The orchestrator is a long-lived daemon that owns a host manifest of the workers on this machine, supervises each one by spawning the pipedai-worker CLI as a child process, and serves a localhost web dashboard for live status and control. It does not replace the worker — it drives the published @pipedai/worker binary, keeping the worker a thin runtime.

See ARCHITECTURE.md for the runtime model, DEPLOYMENT.md for install/ service/rollback, and CLAUDE.md for working guidelines.

Quick install

npm i -g @pipedai/orchestrator
pipedai-orchestrator connect                  # one-step onboarding: enroll, install, open dashboard

That's it for the customer path. connect runs the host-enrollment / device- pairing flow against pipedai-api, registers the worker server-side, writes all the per-host config, installs the daemon as a native service, and opens the local dashboard in the browser. The only interactive step is approving the pairing code in the dashboard (or, for claude_max workspaces, running claude login once).

Two enrollment flows:

• Device pairing (default, no secret paste). Run pipedai-orchestrator connect. It prints a short pairing code; an operator approves it in the dashboard.
• One-line install (headless / CI). Operator pre-issues a code in the dashboard and hands it to the host: pipedai-orchestrator connect --token enr_….

Both flows hit the same redeem exchange. Skip the daemon install with --no-install, skip the browser auto-open with --no-open.

Commands

pipedai-orchestrator connect [--token <code>] [--api-url <url>] [--label <name>]
                                           # PRIMARY: one-step host enrollment
                                           # [--no-install] [--no-open]
pipedai-orchestrator dashboard [--open]    # print the authenticated dashboard URL (--open launches the browser)
pipedai-orchestrator install | uninstall   # native service (launchd/systemd/NSSM)
pipedai-orchestrator status                # is the daemon service running?
pipedai-orchestrator start                 # run the daemon (what the native unit runs)

Advanced / manual escape hatches

These exist for power users and migrations; the primary path is connect.

pipedai-orchestrator login --api-url <url> [--scope=workspace|pool]
                                           # store a pwk_ (workspace) or pop_ (pool-read)
                                           # operator token manually instead of via connect
pipedai-orchestrator adopt                 # import existing ~/.pipedai/worker*.json into the manifest
                                           # (useful when migrating off the old per-worker launchctl units)

Dashboard

The daemon serves a small React dashboard on its loopback port. Run pipedai-orchestrator dashboard to get an authenticated http://127.0.0.1:PORT/?token=… link — the SPA reads the local control token from the URL, then drives the control API (list fused status, build a worker, start/stop/disable/delete) with live updates over a WebSocket. The token gates /api; the app shell itself is static. Dev: npm run dev:web (Vite) against a running daemon.

Operations: rolling forward workers (v3)

The daemon polls pipedai-api's /api/v1/releases/latest daily and surfaces a "behind latest" badge per row. Click Upgrade on the row → the daemon drains the worker (api-side disable + wait for the in-flight Run to complete, 30-min cap), runs npm install -g @pipedai/worker@<latest>, SIGTERMs the child, respawns at the new binary, and re-enables the worker server-side. Self-upgrade for the orchestrator itself follows the same shape (drain + install + exit; launchd respawns the daemon, ~30s downtime).

See DEPLOYMENT.md for the full flow + the macOS TCC gotcha that makes npm install -g . from ~/Documents break launchd-supervised workers.

Running as a service

pipedai-orchestrator install renders the right native unit for your OS, writes it, and loads it — one unit that keeps the daemon alive across reboots; the daemon in turn supervises the worker child processes (the hybrid model). Units invoke node by absolute path, so they work in non-interactive service environments without your nvm/Homebrew PATH. Reference unit files live in templates/. Logs go to /tmp/pipedai-orchestrator.{out,err}.log on macOS/Linux; %TEMP%\pipedai-orchestrator.{out,err}.log on Windows.

Windows

connect and install work on Windows in PowerShell or cmd (orchestrator 0.4.2+ — older builds couldn't resolve the .cmd npm shims from spawn). Service install on Windows uses NSSM — install NSSM first (choco install nssm or download from nssm.cc), then run an elevated PowerShell / cmd window so the generated nssm install batch file can register the service. Logs land under %TEMP%\. Per-worker state lives under %USERPROFILE%\.pipedai\orchestrator\.

Stack

• Node 22 + TypeScript 5.9
• commander for arg parsing
• tsup bundles to a single executable dist/cli.js (CJS + ESM)
• zod for input validation
• Vitest, ESLint, Prettier
• mise pins Node 22

Local Setup

1. Clone all four pipedai repos as siblings (pipedai-api, pipedai-website, pipedai-worker, pipedai-orchestrator) under one parent directory.

2. Install mise (or install Node 22 directly):

   brew install mise
   mise install        # picks up mise.toml -> node@22

3. Install dependencies and build:

   npm install
   npm run build       # emits dist/cli.js with #!/usr/bin/env node shebang

4. Run it:

   npm run dev -- version      # via tsx, no build
   # or, after building:
   node dist/cli.js version

Scripts

| Script | What it does | |---|---| | npm run build | Bundle src/cli.ts to dist/ (CJS + ESM) via tsup | | npm run dev | Run the CLI from source via tsx | | npm run type-check | tsc --noEmit | | npm run lint | ESLint over .ts | | npm run format | Prettier write | | npm test | Vitest run |

Relationship to the other repos

• pipedai-worker — the runtime the orchestrator supervises. The daemon shells out to its register and run commands.
• pipedai-api — source of truth for worker status, run assignment, and the lifecycle endpoints (disable / deregister) the orchestrator calls.
• pipedai-website — the hosted dashboard; the orchestrator's UI is a separate, local, single-host control plane.