# How to Set Up a Development Environment for Ruflo

> Set up your Ruflo development environment easily. Install Node.js and the Claude Code CLI, then run the automated installer with the full flag for global access and MCP integration.

- Repository: [rUv/ruflo](https://github.com/ruvnet/ruflo)
- Tags: getting-started
- Published: 2026-03-09

---

**To set up a Ruflo development environment, install Node.js 20+, the Claude Code CLI, and run the automated installer at [`scripts/install.sh`](https://github.com/ruvnet/ruflo/blob/main/scripts/install.sh) with the `--full` flag to configure global access, MCP integration, and project scaffolding.**

Ruflo (formerly Claude Flow) is an enterprise-grade, multi-agent AI orchestration platform built on top of Claude Code. It ships with a **self-learning kernel**, **vector memory (HNSW)**, and full **MCP (Model Context Protocol)** integration. To begin contributing or developing with this framework, you must configure Node.js 20 or higher, the Claude Code CLI, and the Ruflo package itself.

## Prerequisites

Before running the installer, verify your system meets these baseline requirements as enforced by [`scripts/install.sh`](https://github.com/ruvnet/ruflo/blob/main/scripts/install.sh):

- **Node.js 20 or higher**: The installer checks your version by parsing `node -v` and comparing it against the minimum threshold at lines 50-55. If you lack Node 20, the script suggests installing **fnm** (Fast Node Manager) to obtain it (lines 58-62).

- **npm**: The `npm -v` check occurs at lines 73-77 to ensure package management capabilities are available.

- **Claude Code CLI**: The installer attempts `claude --version` and, if missing, automatically installs the CLI globally via `npm install -g @anthropic-ai/claude-code` (lines 82-97).

## Installation Methods

The [`scripts/install.sh`](https://github.com/ruvnet/ruflo/blob/main/scripts/install.sh) script supports four distinct workflows via the `install_package()` function (lines 24-40). Choose the mode that matches your development needs:

**Global Install (`--global`)**
Adds the `ruflo` command permanently to your PATH using `npm install -g ruflo@<version>`. This is the recommended approach for daily development.

**Npx-Only (Default)**
Runs without flags to execute Ruflo via npx without a permanent installation, storing the package in the temporary npx cache (lines 42-45). Ideal for CI/CD pipelines or one-off testing.

**Minimal Profile (`--minimal` or `-m`)**
Skips optional heavy dependencies by appending `--omit=optional` to the npm install command (lines 27-33). Use this when you need a lightweight agent runtime without extended AI libraries.

**Full Setup (`--full` or `-f`)**
Executes a complete configuration by setting `GLOBAL=1`, `SETUP_MCP=1`, `RUN_DOCTOR=1`, and `RUN_INIT=1` (lines 71-76). This installs globally, configures the MCP server, runs diagnostics, and bootstraps a new project.

Run the full setup with:

```bash
curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/claude-flow@main/scripts/install.sh \
  | bash -s -- --full

```

## MCP Server Configuration

While optional, configuring the **MCP server** unlocks Ruflo's full capabilities by allowing Claude Code to invoke its 170+ specialized tools. When using `--full`, the installer automatically executes the `setup_mcp_server()` function (lines 30-38) to register Ruflo:

```bash
claude mcp add ruflo -- ruflo mcp start

```

If you installed via npx or need to configure manually later, use:

```bash
claude mcp add ruflo -- npx -y ruflo@latest mcp start

```

This handshake is critical because Ruflo's architecture—spanning the CLI entry point at [`bin/cli.js`](https://github.com/ruvnet/ruflo/blob/main/bin/cli.js), the swarm manager, and the HNSW vector memory stack—relies on MCP for inter-agent communication.

## Verify and Initialize Your Environment

After installation, validate the setup using built-in diagnostic commands:

**Run System Diagnostics**
The `ruflo doctor` command (or `npx ruflo@latest doctor` for non-global installs) executes internal health checks for dependencies, network connectivity, and MCP status. The installer triggers this automatically when `RUN_DOCTOR=1` is set (lines 48-51).

**Bootstrap a Project**
Initialize a new Ruflo workspace with `ruflo init --yes` (or `npx ruflo@latest init --yes`). This creates the `.claude/` configuration directory, default agent definitions, and project scaffolding automatically (lines 64-71).

Both commands should return green check-marks and version confirmations indicating successful installation.

## Architectural Context

Ruflo's runtime consists of interconnected layers that require specific environmental support. The **Node.js 20+** requirement ensures compatibility with compiled WASM kernels in `@ruvector/*` packages. The **Claude Code CLI** provides the foundational MCP host capability. Without these, the swarm manager (which coordinates 60+ specialized agents using hierarchical and mesh topologies) cannot initialize the memory stack (HNSW → SQLite → AgentDB → ReasoningBank) or execute tasks from [`bin/cli.js`](https://github.com/ruvnet/ruflo/blob/main/bin/cli.js).

## Summary

- Install **Node.js 20+** and verify with `node -v` (checked in [`scripts/install.sh`](https://github.com/ruvnet/ruflo/blob/main/scripts/install.sh) lines 50-55).

- Ensure **npm** is available and install the **Claude Code CLI** globally.

- Execute the **Ruflo installer** with `--full` for complete setup or choose specific flags for minimal installs.

- Configure the **MCP server** to enable Claude Code integration with Ruflo's tool suite.

- Run **`ruflo doctor`** to validate the environment and **`ruflo init --yes`** to create your first project.

## Frequently Asked Questions

### What is the minimum Node.js version required for Ruflo development?

Ruflo requires **Node.js 20 or higher**. The installer script at [`scripts/install.sh`](https://github.com/ruvnet/ruflo/blob/main/scripts/install.sh) explicitly parses `node -v` and validates the version at lines 50-55, exiting with instructions to use fnm if your version is outdated.

### How do I install Ruflo without adding it to my global PATH?

Use the **npx-only** installation method by running the installer without the `--global` flag. This caches the package temporarily and allows you to invoke commands via `npx ruflo@latest` without permanent installation, as handled in lines 42-45 of [`scripts/install.sh`](https://github.com/ruvnet/ruflo/blob/main/scripts/install.sh).

### What does the `ruflo doctor` command verify?

The `ruflo doctor` command runs comprehensive diagnostics checking dependency health, network connectivity, MCP server accessibility, and WASM kernel load status. It is implemented in the installer logic at lines 48-51 and executes automatically when using the `--full` installation flag.

### Is the Claude Code CLI mandatory for Ruflo?

**Yes.** The Claude Code CLI (`@anthropic-ai/claude-code`) is required because Ruflo functions as an MCP server that communicates through Claude Code's host interface. The installer checks for this dependency at lines 82-97 and automatically installs it if missing, as the MCP handshake fails without this component.