Worker install guide

Prerequisites

• Node 22+ on the host (run node --version to check)
• Claude Code CLI installed and on PATH — install instructions
• For claude-max auth: claude login completed once interactively as the user that will run the worker
• For api-key auth: ANTHROPIC_API_KEY available in the worker's environment

One-liner install

bashnpm i -g @pipedai/worker \
  && pipedai-worker register --token=wrk_… --api-url=https://api-beta.pipedai.app \
  && pipedai-worker run

That's the entire happy path. Open the dashboard's Settings → API Keys → Worker Registration tab to mint a wrk_ token before running this.

Install as a system service

For sustained production use, the worker should run under a service manager so it auto-restarts on crash and survives reboots. Sample templates ship in the npm package's templates/ directory.

Linux (systemd)

bashsudo cp $(npm root -g)/@pipedai/worker/templates/systemd-pipedai-worker.service \
  /etc/systemd/system/pipedai-worker.service
sudo $EDITOR /etc/systemd/system/pipedai-worker.service   # set User= and AUTH_MODE
sudo systemctl daemon-reload
sudo systemctl enable --now pipedai-worker
journalctl -u pipedai-worker -f

The template uses KillSignal=SIGINT andTimeoutStopSec=120 so the worker has time to finish its in-flight run before systemd escalates.

macOS (launchd)

bashcp $(npm root -g)/@pipedai/worker/templates/launchd-com.marolence.pipedai-worker.plist \
  ~/Library/LaunchAgents/com.marolence.pipedai-worker.plist
$EDITOR ~/Library/LaunchAgents/com.marolence.pipedai-worker.plist
launchctl load -w ~/Library/LaunchAgents/com.marolence.pipedai-worker.plist
tail -f /tmp/pipedai-worker.out.log

Windows (nssm)

cmdchoco install nssm
copy %APPDATA%\npm\node_modules\@pipedai\worker\templates\windows-nssm-install.bat .
notepad windows-nssm-install.bat   :: edit AUTH_MODE / paths
:: Run as Administrator:
windows-nssm-install.bat
nssm start PipedAIWorker

Docker / docker-compose

The image bundles Node 22 + the worker. Because claude login needs an interactive terminal, Docker is most useful for api-key mode. Bind-mount the host's ~/.pipedai so worker.json persists across container recreations.

bashdocker run -d --name pipedai-worker \
  -e AUTH_MODE=api-key \
  -e ANTHROPIC_API_KEY=sk-... \
  -v ~/.pipedai:/root/.pipedai \
  pipedai-worker

Or use the compose template at templates/docker-compose.yml and run docker compose up -d.

Configuration

Environment variables the worker reads:

• AUTH_MODE — claude-max (default) or api-key
• ANTHROPIC_API_KEY — required when AUTH_MODE=api-key
• POLL_INTERVAL_MS — default 60000. Floor 1000ms.
• CONCURRENCY — max parallel runs per worker. Default 1.