How to Configure Ruflo Settings: Complete JSON Configuration Guide

Ruflo uses a single JSON configuration file at config/config.json to control branding, GCP deployment, authentication, and model catalogs, which is processed by generate-config.js to create deployment artifacts.

Ruflo (ruvnet/ruflo) is an open-source AI orchestration platform that relies on a centralized JSON configuration to manage its runtime behavior. To configure Ruflo settings effectively, you need to understand the configuration file structure, the generation scripts that process it, and the runtime manager that applies these settings.

Configuration File Location and Structure

Template and Production Paths

Ruflo separates the configuration template from your active settings:

• ruflo/src/config/config.example.json – The canonical template that documents every supported configuration key. This file serves as the reference for all available options.
• config/config.json – Your active configuration file. Copy the example template to this location and customize the values for your deployment.

The generation script at ruflo/src/scripts/generate-config.js reads your config/config.json and produces deployment artifacts including chat-ui/dotenv-local.txt, cloudbuild.yaml, and MCP server configurations.

Core Configuration Sections

The JSON file organizes settings into logical sections that control specific runtime behaviors:

Section	Key Examples	Purpose
brand	name, description, domain, welcomeColors	Controls UI branding in the chat interface and generated environment files.
gcp	projectId, region, vpcConnector, serviceName.chatUi	Defines Google Cloud Platform deployment targets for Cloud Run services.
auth	enabled, provider, clientId, clientSecretName	Configures OpenID Connect authentication (Google OAuth by default).
models	Array of objects with name, displayName, provider	Populates the model catalog available to users in the UI.
secrets	openaiApiKey, googleApiKey, openrouterApiKey	Stores API credentials injected as Docker secrets into the MCP bridge.
systemPrompt	systemPrompt	Sets the default pre-prompt applied to all model interactions.

Step-by-Step Configuration Process

1. Copy the Example Template

Start by creating your active configuration from the provided template:

# From the repository root

cp ruflo/src/config/config.example.json config/config.json

# Edit the file with your specific values

nano config/config.json

2. Configure Brand and Deployment Settings

Edit the brand and gcp sections to define your application identity and cloud targets:

{
  "brand": {
    "name": "Acme AI Assistant",
    "description": "Enterprise knowledge management",
    "domain": "acme.example.com",
    "welcomeColors": ["#1a73e8", "#34a853"]
  },
  "gcp": {
    "projectId": "acme-gcp-project",
    "region": "us-central1",
    "vpcConnector": "acme-vpc-connector",
    "serviceName": {
      "chatUi": "acme-chat-ui",
      "mcpBridge": "acme-mcp-bridge"
    }
  }
}

3. Set Up Authentication and Models

Configure OAuth and available AI models:

{
  "auth": {
    "enabled": true,
    "provider": "google",
    "clientId": "your-oauth-client-id.apps.googleusercontent.com",
    "clientSecretName": "oauth-client-secret",
    "scopes": ["openid", "email", "profile"],
    "nameClaim": "name"
  },
  "models": [
    {
      "name": "gpt-4",
      "displayName": "GPT-4",
      "description": "Advanced reasoning model",
      "provider": "openai",
      "supportsTools": true
    }
  ]
}

4. Generate Deployment Artifacts

Run the generation script to create environment files and Cloud Build configurations:

node ruflo/src/scripts/generate-config.js config/config.json

This produces:

• chat-ui/dotenv-local.txt – Environment variables for local development
• chat-ui/cloudbuild.yaml – Cloud Build configuration for the UI service
• mcp-bridge/cloudbuild.yaml – Cloud Build configuration for the MCP bridge
• MCP_SERVERS list based on the mcpGroups configuration

Deploy using the generated files:

bash ruflo/src/scripts/deploy.sh

Runtime Configuration Management

Environment Variable Merging in config.ts

After deployment, ruflo/src/ruvocal/src/lib/server/config.ts manages runtime configuration by merging multiple sources:

1. Process Environment – Variables like PUBLIC_APP_NAME and OPENAI_BASE_URL take precedence
2. Database Configuration – When ENABLE_CONFIG_MANAGER=true, values from the config collection can override environment variables
3. JSON Defaults – Fallback values from the original config.json

The module exposes a Proxy object (config) used throughout the codebase for consistent access to settings.

Dynamic Updates Without Restart

The ConfigManager class enables hot-reloading of configuration values:

import { config } from "$lib/server/config";

// Update a value programmatically
await config.set("PUBLIC_APP_NAME", "Updated Assistant Name");

// Delete a configuration key
await config.delete("PUBLIC_APP_NAME");

The manager watches the semaphores collection for a CONFIG_UPDATE entry. When detected, it reloads database-backed settings without requiring a server restart, ensuring zero-downtime configuration changes.

Common Configuration Pitfalls and Solutions

Symptom	Likely Cause	Fix
Missing brand name in UI	config.brand.name not set or PUBLIC_APP_NAME not regenerated	Re-run generate-config.js and redeploy the container
Auth flow never triggers	config.auth.enabled is false or clientId empty	Set enabled: true and provide a valid Google OAuth client ID in the JSON
Model list is empty	config.models array missing or supportsTools mis-typed	Populate the models array with valid provider names and boolean flags
MCP tools not reachable	MCP_SERVERS missing or bridge URL not reachable	Verify MCP_SERVERS appears in dotenv-local.txt and the bridge container runs at the expected host/port

Summary

• Ruflo configuration centers on a single JSON file at config/config.json copied from ruflo/src/config/config.example.json.
• Key sections include brand, gcp, auth, models, and secrets, controlling everything from UI colors to API credentials.
• Generation workflow requires running node ruflo/src/scripts/generate-config.js to produce environment files and Cloud Build configurations.
• Runtime management happens in ruflo/src/ruvocal/src/lib/server/config.ts, which merges environment variables with database-backed settings when ENABLE_CONFIG_MANAGER is enabled.
• Dynamic updates allow changing configuration values without server restarts by using the ConfigManager class and watching the semaphores collection.

Frequently Asked Questions

Where is the main configuration file located in Ruflo?

The primary configuration file is config/config.json at the repository root. You create this file by copying the template at ruflo/src/config/config.example.json, which documents every available configuration key. The generate-config.js script specifically looks for config/config.json by default, though you can pass a custom path as an argument.

How do I update Ruflo settings without redeploying?

When ENABLE_CONFIG_MANAGER=true, you can update settings dynamically using the ConfigManager class exposed in ruflo/src/ruvocal/src/lib/server/config.ts. Import the config proxy and call await config.set("KEY_NAME", "value") to update values programmatically. The system watches the semaphores collection for CONFIG_UPDATE entries and reloads database-backed settings without requiring a container restart.

What happens if I forget to run generate-config.js after editing?

If you modify config/config.json but do not run node ruflo/src/scripts/generate-config.js, your changes will not propagate to the deployment artifacts. The Docker containers and Cloud Build configurations will continue using the old values from the previously generated dotenv-local.txt and cloudbuild.yaml files. Always regenerate the configuration files and redeploy the containers to ensure changes take effect.

Which configuration section controls the model catalog?

The models array in config/config.json defines the available AI models in the catalog. Each object in this array specifies properties like name, displayName, description, provider (e.g., "openai" or "google"), and supportsTools (boolean). The generate-config.js script converts this array into the MODELS environment variable that the chat UI reads to populate model selection dropdowns.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}