ruvnet/ruflo · error · ProxyNotInstalledError

meta-proxy is not installed. Run: ruflo proxy install

Error message

meta-proxy is not installed. Run: ruflo proxy install

What it means

Every proxy lifecycle operation (start, foreground, background, stop) first calls requireBinary(), which checks fs.existsSync(proxyBinaryPath()) and throws ProxyNotInstalledError when the meta-proxy binary is absent. The binary is not bundled with the CLI — it is downloaded, signature-verified, and placed only by `ruflo proxy install`.

Solutions

1. Run `ruflo proxy install` to download, signature-verify, and place the binary
2. Confirm detection with `ruflo proxy status` before retrying the lifecycle command
3. If install itself fails, fix that error first (network, platform support) — start will keep throwing until the binary exists

Example fix

# before
ruflo proxy start   # ProxyNotInstalledError
# after
ruflo proxy install && ruflo proxy start

import { existsSync } from 'node:fs';
import { execFileSync } from 'node:child_process';
// Cheap pre-check via the CLI before starting
const installed = execFileSync('ruflo', ['proxy', 'status'], { encoding: 'utf8' });
// Or, if importing the module: import { proxyBinaryPath } from '@claude-flow/cli/.../proxy/paths.js';
// const installed = existsSync(proxyBinaryPath());

const isProxyNotInstalled = (e: unknown): e is Error =>
  e instanceof Error && e.name === 'ProxyNotInstalledError';

try {
  await startForeground();
} catch (e) {
  if (isProxyNotInstalled(e)) {
    execSync('ruflo proxy install');   // self-heal once
    await startForeground();
  } else throw e;
}

When it happens

Trigger: Running `ruflo proxy start` (or `proxy stop`, or any code path reaching requireBinary()) before `ruflo proxy install` has ever run on this machine; or after the binary file at proxyBinaryPath() was deleted or the state directory was cleaned.

Common situations: Fresh npm install of the CLI on a new machine; CI runners with ephemeral home directories where install state never persists; users assuming the proxy ships inside the CLI package; cleanup tools purging dot-state directories.

Related errors

• meta-proxy is already running
• Agent not found
• Agent is not available (status: )
• Agent not initialized. Call initialize() first.
• AgentAdapter not initialized. Call initialize() first.

AI-assisted analysis of ruvnet/ruflo@fa13ee4ad6 (2026-08-18). Data as JSON: /api/errors/ea357c3629018150. Report an issue: GitHub.

Appendix: source

Thrown at v3/@claude-flow/cli/src/proxy/lifecycle.ts:59

} from './paths.js';

export class ProxyNotInstalledError extends Error {
  constructor() {
    super('meta-proxy is not installed. Run: ruflo proxy install');
    this.name = 'ProxyNotInstalledError';
  }
}

export class ProxyAlreadyRunningError extends Error {
  constructor(public readonly pid: number) {
    super(`meta-proxy is already running (pid ${pid}). Stop it first with: ruflo proxy stop`);
    this.name = 'ProxyAlreadyRunningError';
  }
}

function requireBinary(): string {
  const bin = proxyBinaryPath();
  if (!fs.existsSync(bin)) throw new ProxyNotInstalledError();
  return bin;
}

/** Signal-0 liveness probe — cross-platform in Node, throws if the process is dead. */
function isProcessRunning(pid: number): boolean {
  try {
    process.kill(pid, 0);
    return true;
  } catch {
    return false;
  }
}

export interface ProxyStatus {
  installed: boolean;
  running: boolean;
  pid: number | null;
  stalePidFile: boolean;

View on GitHub (pinned to fa13ee4ad6)