Ruflo Configuration: Files, Profiles, and Use Cases

Ruflo reads configuration from three sources that compose at runtime: a JSON config file for structured settings (swarm topology, MCP transport, memory backend), a dotenv file for secrets and runtime flags, and a Claude Code settings file that registers hooks. You can use all three together or just the ones your use case requires — most projects start with only .env and claude-flow.config.json.

Configuration Files

File	Purpose
`claude-flow.config.json`	Core config: swarm topology, MCP server, memory backend, provider routing
`.env`	Secret keys, provider API keys, and feature flags (never commit this file)
`.claude/settings.json`	Hook registration, Claude Code experimental settings, agent-teams flags

Core Configuration Schema

claude-flow.config.json lives at your project root. The full schema with commonly used fields:

{
  "swarm": {
    "topology": "hierarchical",
    "maxAgents": 8,
    "consensus": "raft"
  },
  "mcp": {
    "transport": "stdio",
    "port": 3000,
    "host": "localhost",
    "toolGroups": ["coordination", "memory", "monitoring"]
  },
  "memory": {
    "backend": "hybrid",
    "dimensions": 384,
    "cacheEnabled": true
  },
  "providers": {
    "default": "claude",
    "fallback": "openai"
  }
}

swarm

Key	Type	Description
`topology`	`"hierarchical" \| "mesh" \| "ring" \| "star"`	Agent coordination pattern. `hierarchical` (default) puts a queen coordinator in charge of workers — recommended for structured coding tasks because it enforces goal alignment at every step.
`maxAgents`	`number`	Maximum simultaneous agents. Keep at 6–8 to minimize coordination overhead and drift surface.
`consensus`	`"raft" \| "byzantine" \| "gossip" \| "quorum" \| "crdt"`	Distributed decision algorithm. `raft` (leader-elected, f < n/2) is the default for strongly consistent state; `byzantine` (2/3 supermajority, f < n/3) for adversarial environments.

mcp

Key	Type	Description
`transport`	`"stdio" \| "http" \| "websocket"`	”http” \| “websocket”`	Transport mode. `stdio` (default) is used by Claude Code and Codex — no network port is opened. Use `http` or `websocket` for editors that connect over a network socket.
`port`	`number`	HTTP or WebSocket transport port (default: `3000`). Ignored when transport is `stdio`.
`host`	`string`	Bind host for HTTP/WebSocket transport (default: `"localhost"`).
`toolGroups`	`string[]`	Restrict which tool groups are loaded. Fewer groups = faster startup and lower token usage. Options: `coordination`, `memory`, `monitoring`, `github`, `system`.

memory

Key	Type	Description
`backend`	`"hybrid" \| "sqlite" \| "hnsw"`	`hybrid` uses SQLite + HNSW index together. HNSW provides sub-millisecond vector search; SQLite handles relational persistence.
`dimensions`	`number`	Embedding vector dimensions. Default `384` (matches ONNX MiniLM). OpenAI’s `text-embedding-3-large` uses `3072`.
`cacheEnabled`	`boolean`	Enable LRU embedding cache. Cache hits return in <1ms.

providers

Key	Type	Description
`default`	`"claude" \| "openai" \| "google" \| "cohere" \| "ollama"`	Primary LLM provider.
`fallback`	`string`	Provider to use when the default is unavailable or rate-limited.

Configuration by Use Case

Minimal
Standard
Enterprise

Core CLI only — no ML dependencies, no HNSW, no ONNX. Fastest install (~45 MB, ~15s). Suitable for scripting, plugin authors using CLI_CORE=1, or environments where you don’t need vector memory.

{
  "swarm": {
    "topology": "hierarchical",
    "maxAgents": 4,
    "consensus": "raft"
  },
  "mcp": {
    "port": 3000,
    "toolGroups": ["coordination", "memory"]
  },
  "memory": {
    "backend": "sqlite",
    "cacheEnabled": false
  },
  "providers": {
    "default": "claude"
  }
}

Install with:

npm install -g ruflo@latest --omit=optional

Or use the install script flag:

curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/ruflo@main/scripts/install.sh | bash -s -- --minimal

Full feature set with ML/embeddings (~340 MB). HNSW vector memory, ONNX local embeddings, all five tool groups, self-learning hooks. Recommended for daily development use.

{
  "swarm": {
    "topology": "hierarchical",
    "maxAgents": 8,
    "consensus": "raft"
  },
  "mcp": {
    "port": 3000,
    "toolGroups": ["coordination", "memory", "monitoring", "github", "system"]
  },
  "memory": {
    "backend": "hybrid",
    "dimensions": 384,
    "cacheEnabled": true
  },
  "providers": {
    "default": "claude",
    "fallback": "openai"
  }
}

Install:

npx ruflo@latest init

Federation, security audit workers, observability, and Byzantine consensus. For teams running agents across multiple machines or trust boundaries.

{
  "swarm": {
    "topology": "hierarchical",
    "maxAgents": 12,
    "consensus": "byzantine"
  },
  "mcp": {
    "port": 3000,
    "toolGroups": ["coordination", "memory", "monitoring", "github", "system"]
  },
  "memory": {
    "backend": "hybrid",
    "dimensions": 384,
    "cacheEnabled": true
  },
  "providers": {
    "default": "claude",
    "fallback": "openai"
  }
}

Additional setup for enterprise deployments:

# Initialize federation (zero-trust cross-machine agent comms)
npx ruflo@latest federation init

# Enable security audit background worker
npx ruflo@latest worker dispatch --trigger audit --context ./src

# Install observability plugin
npx ruflo@latest plugins install -n @claude-flow/plugin-gastown-bridge

# Add ruflo-observability for structured logs + traces
/plugin install ruflo-observability@ruflo

Install Profiles

Profile	Flag	Size	Time	Use Case
Minimal	`--omit=optional` or `--minimal`	~45 MB	~15s	Core CLI only, no ML/embeddings
Default	(none)	~340 MB	~35s cold-cache	Full install with HNSW, ONNX, neural features

# Minimal install — skips optional dependencies (ML/embeddings)
npm install -g ruflo@latest --omit=optional

# Full install
npm install -g ruflo@latest

The minimal install includes all CLI commands and the MCP server. What’s missing is the local ONNX embedding runtime, HNSW indexing, and neural features. Vector memory falls back to SQLite brute-force search and the OpenAI embedding API (if OPENAI_API_KEY is set) rather than local ONNX SIMD.

CLI Config Commands

Ruflo ships a config subcommand for reading and writing claude-flow.config.json from the terminal:

# List all current configuration values
npx ruflo@latest config list

# Set a configuration key (dot-notation for nested keys)
npx ruflo@latest config set --key swarm.maxAgents --value 6

# Read a single configuration key
npx ruflo@latest config get --key swarm.topology

# Reset all configuration to defaults
npx ruflo@latest config reset --key swarm

Use config set in CI scripts to override topology or provider settings per environment without modifying the committed claude-flow.config.json. The CLI flag takes precedence over the config file: --tools=coordination,memory overrides mcp.toolGroups.

Precedence Order

When the same setting appears in multiple places, Ruflo resolves conflicts in this order (highest wins):

CLI flags (e.g., --transport http, --tools=coordination)
Environment variables (e.g., CLAUDE_FLOW_MCP_PORT)
claude-flow.config.json
Built-in defaults

Next Steps

Environment Variables

Complete reference for API keys, memory paths, MCP settings, and the CLI_CORE fast path.

MCP Server

Start the MCP server, configure transports, register with editors, and explore tool groups.

Get Started

Core Concepts

Guides

Configuration

Ruflo Configuration: Files, Profiles, and Use Cases

Configuration Files

Core Configuration Schema

Configuration by Use Case

Install Profiles

CLI Config Commands

Precedence Order

Next Steps

Environment Variables

MCP Server

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Configuration

Documentation Index

​Configuration Files

​Core Configuration Schema

​Configuration by Use Case

​Install Profiles

​CLI Config Commands

​Precedence Order

​Next Steps

Environment Variables

MCP Server

Build docs developers (and LLMs) love

Configuration Files

Core Configuration Schema

Configuration by Use Case

Install Profiles

CLI Config Commands

Precedence Order

Next Steps