# How to Configure Ruflo Settings: Complete JSON Configuration Guide

> Master Ruflo settings with this JSON configuration guide. Learn to control branding, GCP deployment, authentication, and model catalogs for your project.

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

---

**Ruflo uses a single JSON configuration file at [`config/config.json`](https://github.com/ruvnet/ruflo/blob/main/config/config.json) to control branding, GCP deployment, authentication, and model catalogs, which is processed by [`generate-config.js`](https://github.com/ruvnet/ruflo/blob/main/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`](https://github.com/ruvnet/ruflo/blob/main/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`](https://github.com/ruvnet/ruflo/blob/main/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`](https://github.com/ruvnet/ruflo/blob/main/ruflo/src/scripts/generate-config.js) reads your [`config/config.json`](https://github.com/ruvnet/ruflo/blob/main/config/config.json) and produces deployment artifacts including [`chat-ui/dotenv-local.txt`](https://github.com/ruvnet/ruflo/blob/main/chat-ui/dotenv-local.txt), [`cloudbuild.yaml`](https://github.com/ruvnet/ruflo/blob/main/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:

```bash

# 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:

```json
{
  "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:

```json
{
  "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:

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

```

This produces:
- [`chat-ui/dotenv-local.txt`](https://github.com/ruvnet/ruflo/blob/main/chat-ui/dotenv-local.txt) – Environment variables for local development
- [`chat-ui/cloudbuild.yaml`](https://github.com/ruvnet/ruflo/blob/main/chat-ui/cloudbuild.yaml) – Cloud Build configuration for the UI service
- [`mcp-bridge/cloudbuild.yaml`](https://github.com/ruvnet/ruflo/blob/main/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
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`](https://github.com/ruvnet/ruflo/blob/main/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`](https://github.com/ruvnet/ruflo/blob/main/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:

```typescript
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`](https://github.com/ruvnet/ruflo/blob/main/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`](https://github.com/ruvnet/ruflo/blob/main/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`](https://github.com/ruvnet/ruflo/blob/main/config/config.json) copied from [`ruflo/src/config/config.example.json`](https://github.com/ruvnet/ruflo/blob/main/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`](https://github.com/ruvnet/ruflo/blob/main/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`](https://github.com/ruvnet/ruflo/blob/main/config/config.json) at the repository root. You create this file by copying the template at [`ruflo/src/config/config.example.json`](https://github.com/ruvnet/ruflo/blob/main/ruflo/src/config/config.example.json), which documents every available configuration key. The [`generate-config.js`](https://github.com/ruvnet/ruflo/blob/main/generate-config.js) script specifically looks for [`config/config.json`](https://github.com/ruvnet/ruflo/blob/main/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`](https://github.com/ruvnet/ruflo/blob/main/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`](https://github.com/ruvnet/ruflo/blob/main/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`](https://github.com/ruvnet/ruflo/blob/main/dotenv-local.txt) and [`cloudbuild.yaml`](https://github.com/ruvnet/ruflo/blob/main/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`](https://github.com/ruvnet/ruflo/blob/main/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`](https://github.com/ruvnet/ruflo/blob/main/generate-config.js) script converts this array into the `MODELS` environment variable that the chat UI reads to populate model selection dropdowns.