# How to Get Started with Ruflo Development: A Complete Setup Guide > Get started with Ruflo development by installing the CLI, scaffolding a project, and launching the dev environment. Build multi-agent applications easily with this guide. - Repository: [rUv/ruflo](https://github.com/ruvnet/ruflo) - Tags: getting-started - Published: 2026-03-09 --- **Install the CLI with `npm install -g ruflo`, scaffold a project using `npx ruflo@latest init --wizard`, and launch the development environment with `npm run dev` to start building multi-agent applications.** Ruflo serves as the re-branded entry point for the Claude Flow multi-agent platform, distributed as an NPM package that proxies the full `@claude-flow/cli` toolchain. Whether you are extending the Model Context Protocol (MCP) bridge or customizing the SvelteKit frontend, this guide covers the essential steps to bootstrap your ruflo development environment using the `ruvnet/ruflo` repository. ## What Is Ruflo? Ruflo is an NPM package that acts as a thin wrapper around the Claude Flow CLI. When you run the `ruflo` command, [`bin/cli.js`](https://github.com/ruvnet/ruflo/blob/main/bin/cli.js) simply re-exports the real CLI from `v3/@claude-flow/cli/bin/cli.js`. This architecture allows the ruflo ecosystem to leverage the robust multi-agent orchestration of Claude Flow while maintaining a distinct branding and entry point for the `ruvnet` organization. ## Prerequisites for Ruflo Development Before installing the CLI, ensure your environment meets the following requirements: - **Node.js** version 18 or higher (required for the MCP bridge and SvelteKit build tools) - **npm** or **yarn** for package management - **Git** for cloning the repository and managing project versions ## Installing the Ruflo CLI You can install the CLI globally for repeated use, or invoke it on-demand via `npx`. ### Global Installation ```bash npm install -g ruflo ``` This adds the `ruflo` command to your system path, allowing you to run `ruflo init` from any directory. ### One-time Usage with npx ```bash npx ruflo@latest ``` Use this approach when you want to ensure you are always running the latest version without maintaining a global installation. ## Creating Your First Ruflo Project ### Using the Interactive Wizard The fastest way to start ruflo development is with the built-in scaffolding wizard: ```bash npx ruflo@latest init --wizard ``` This command performs several setup tasks automatically: 1. Creates a new project directory with a standard structure 2. Generates a starter `.env.local` file from the template 3. Installs required Node modules for the bridge and frontend 4. Configures the SvelteKit development environment ### Project Structure Overview After initialization, your project contains the following key directories: - `src/mcp-bridge/` – Node.js bridge implementing the Model Context Protocol server ([`index.js`](https://github.com/ruvnet/ruflo/blob/main/index.js)) - `src/ruvocal/` – SvelteKit 2 frontend application providing the chat UI - `src/ruvocal/src/lib/` – Shared libraries including [`APIClient.ts`](https://github.com/ruvnet/ruflo/blob/main/APIClient.ts) and type definitions ## Configuring Environment Variables ### Required API Keys Before running the development server, copy the example environment file and fill in your credentials: ```bash cp .env.example .env.local ``` The `.env.example` file in the repository documents every required and optional variable, including: - **OpenAI API key** for LLM inference - **Google API credentials** for additional model providers - **MongoDB connection string** for persistent memory storage ### MCP Tool Groups Ruflo organizes capabilities into MCP tool groups that you can enable or disable via environment variables: - `MCP_GROUP_AGENTS` – Controls access to multi-agent orchestration tools - `MCP_GROUP_MEMORY` – Enables persistent context and memory features Set these to `true` or `false` in your `.env.local` to customize the bridge's exposed functionality. ## Running the Development Server Start the full development environment with: ```bash npm install # Install bridge dependencies if not already done npm run dev # Launches the bridge + SvelteKit dev server ``` This command starts two processes: 1. **The MCP Bridge** ([`src/mcp-bridge/index.js`](https://github.com/ruvnet/ruflo/blob/main/src/mcp-bridge/index.js)) – Runs the Model Context Protocol server that exposes tools to LLMs 2. **The SvelteKit Frontend** – Serves the chat UI on `http://localhost:5173` by default For hot-reloading of the bridge process specifically, use: ```bash npm run dev:bridge ``` ## Understanding the Ruflo Architecture ### Entry Point and CLI Proxy The `ruflo` command you invoke is a thin stub located at [`bin/cli.js`](https://github.com/ruvnet/ruflo/blob/main/bin/cli.js). This file simply re-exports the real CLI implementation from `v3/@claude-flow/cli/bin/cli.js`, allowing the package to proxy all commands to the underlying Claude Flow toolchain while maintaining the ruflo branding. ### MCP Bridge Server Located at [`src/mcp-bridge/index.js`](https://github.com/ruvnet/ruflo/blob/main/src/mcp-bridge/index.js), the bridge implements the Model Context Protocol. This Node.js process starts when you run `npm run dev` and exposes agent tools, memory systems, and orchestration capabilities to connected LLMs via the MCP specification. ### Frontend and API Client The user interface is a SvelteKit 2 application located in `src/ruvocal/src/`. Key architectural components include: - **[`APIClient.ts`](https://github.com/ruvnet/ruflo/blob/main/APIClient.ts)** – A thin, typed wrapper around `fetch` that constructs endpoint objects for the `/api/v2` REST layer. It includes a `handleResponse` utility that converts raw JSON into typed objects and throws on HTTP errors. - **[`types/Settings.ts`](https://github.com/ruvnet/ruflo/blob/main/types/Settings.ts)** – Defines the persisted user configuration structure, including model overrides, streaming mode preferences, and UI state. ## Building and Testing ### Production Builds When you are ready to deploy, generate an optimized production bundle: ```bash npm run build # Creates a static asset bundle in .svelte-kit npm run preview # Serves the built bundle locally on http://localhost:4173 ``` The `preview` command allows you to inspect the production build locally before deployment. ### Running Tests The repository includes a Vitest test suite. Execute all tests with: ```bash npm run test ``` For targeted development, run a single test file in watch mode: ```bash npx vitest --watch src/ruvocal/src/lib/utils/tree/buildSubtree.spec.ts ``` This approach is documented in the [`CLAUDE.md`](https://github.com/ruvnet/ruflo/blob/main/CLAUDE.md) developer guide and is useful when extending tree utilities or other specific modules. ## Summary - **Ruflo** is an NPM wrapper around the Claude Flow CLI, providing a branded entry point for multi-agent development. - **Installation** requires Node.js 18+ and uses either `npm install -g ruflo` or `npx ruflo@latest`. - **Project scaffolding** is handled by `ruflo init --wizard`, which creates the directory structure and `.env.local` configuration. - **Development workflow** uses `npm run dev` to start both the MCP bridge ([`src/mcp-bridge/index.js`](https://github.com/ruvnet/ruflo/blob/main/src/mcp-bridge/index.js)) and the SvelteKit frontend. - **Key architectural files** include [`bin/cli.js`](https://github.com/ruvnet/ruflo/blob/main/bin/cli.js) (entry proxy), [`APIClient.ts`](https://github.com/ruvnet/ruflo/blob/main/APIClient.ts) (typed REST wrapper), and [`types/Settings.ts`](https://github.com/ruvnet/ruflo/blob/main/types/Settings.ts) (configuration schema). - **Testing and building** leverage Vitest (`npm run test`) and standard SvelteKit build commands (`npm run build` and `npm run preview`). ## Frequently Asked Questions ### What is the difference between Ruflo and Claude Flow? Ruflo is the re-branded NPM package entry point for the Claude Flow multi-agent platform. While Claude Flow provides the underlying CLI toolchain located at `v3/@claude-flow/cli/bin/cli.js`, Ruflo wraps this functionality in the `ruvnet` namespace. When you run `ruflo` commands, [`bin/cli.js`](https://github.com/ruvnet/ruflo/blob/main/bin/cli.js) simply proxies to the Claude Flow implementation, maintaining identical functionality under the new branding. ### Do I need to install Claude Flow separately? No. When you install Ruflo via `npm install -g ruflo` or use `npx ruflo@latest`, the package automatically includes the `@claude-flow/cli` dependency. The [`bin/cli.js`](https://github.com/ruvnet/ruflo/blob/main/bin/cli.js) stub handles the delegation, so you only interact with the `ruflo` command while the underlying Claude Flow tools execute in the background. ### How do I enable specific MCP tool groups? MCP tool groups are controlled through environment variables defined in your `.env.local` file. According to the `.env.example` template, you can toggle functionality by setting variables such as `MCP_GROUP_AGENTS` and `MCP_GROUP_MEMORY` to `true` or `false`. These settings determine which capabilities the MCP bridge ([`src/mcp-bridge/index.js`](https://github.com/ruvnet/ruflo/blob/main/src/mcp-bridge/index.js)) exposes to connected LLMs when you run `npm run dev`. ### Can I use Ruflo without the SvelteKit frontend? Yes, though the standard development workflow (`npm run dev`) launches both the MCP bridge and the SvelteKit frontend. If you only need the backend MCP server, you can start the bridge process independently. The [`src/mcp-bridge/index.js`](https://github.com/ruvnet/ruflo/blob/main/src/mcp-bridge/index.js) file implements the Model Context Protocol server, and you can configure it solely through environment variables without serving the UI components located in `src/ruvocal/`.