@flofai/runner

@flofai/runner

Connect a machine (your laptop, a VM, a CI box) to your egos workspace. The runner holds a WebSocket to the hub, registers the machine, and runs the orders the workspace assigns to it — using that machine's own Claude Code login. Zero dependencies (Node 22+).

Quick start

# 1) sign in to Claude on this machine once (reused by the runner)
claude setup-token

# 2) connect to your workspace (token from the console → "Add a machine")
npx @flofai/runner connect --token <TOKEN>

The machine now shows as online in the workspace. Leave the process running.

egos-runner add-project egosorg/helpway --dir ~/code/helpway   # map a repo to a local dir
egos-runner status                                             # show config

Keeping it alive

The runner must keep running for the machine to stay online (it auto-reconnects if the network drops). Pick one:

• Foreground — run connect in a terminal and leave it open. Simplest.

• Background — nohup npx @flofai/runner connect --token <T> & (survives terminal close).

• Service (recommended for a VM) — keep it up across reboots:

  macOS (launchd) — ~/Library/LaunchAgents/ai.flof.runner.plist:

  <?xml version="1.0" encoding="UTF-8"?>
  <plist version="1.0"><dict>
    <key>Label</key><string>ai.flof.runner</string>
    <key>ProgramArguments</key>
    <array><string>/usr/local/bin/npx</string><string>@flofai/runner</string><string>connect</string></array>
    <key>RunAtLoad</key><true/><key>KeepAlive</key><true/>
  </dict></plist>

  launchctl load ~/Library/LaunchAgents/ai.flof.runner.plist

  Linux (systemd) — /etc/systemd/system/egos-runner.service:

  [Unit]
  Description=egos runner
  After=network-online.target
  [Service]
  ExecStart=/usr/bin/npx @flofai/runner connect
  Restart=always
  User=%i
  [Install]
  WantedBy=multi-user.target

  sudo systemctl enable --now egos-runner

(The token is saved to ~/.egos/runner.json on first connect, so the service form needs no flags.)

Config

~/.egos/runner.json — { hub, token, name, machineId, executor, projects }. Default hub: https://carna.flof.ai. Executor: demo (safe) · shell · claude.