Where Is the Configuration File for OmniRoute? A Complete Path Reference

OmniRoute stores its runtime configuration files in the repository’s config/ directory, while environment templates and build settings reside in the project root.

OmniRoute, the open-source routing and proxy framework developed by diegosouzapw, centralizes its behavioral settings in JSON-based configuration files. Understanding where these files live and how the server consumes them is essential for customizing payload validation, internationalization, and quality gates without modifying source code.

Runtime Configuration in the config/ Directory

The primary configuration files for OmniRoute are located under the config/ folder at the repository root. These JSON files define runtime behavior and are imported directly by the server during initialization in src/server/init.ts.

Payload Validation Rules

The config/payloadRules.json file defines request filtering and reshaping rules, including size limits and prohibited fields. According to the OmniRoute source code, this file is consumed by the request-validation middleware at src/middleware/payloadValidator.ts to sanitize incoming traffic.

Internationalization Settings

Language support is governed by two files:

• config/i18n.json – Maps language codes to translation bundles used by both the UI and CLI.
• config/i18n-schema.json – Provides JSON-Schema validation to ensure new language entries conform to expected structures, validated by src/lib/validation/i18nValidator.ts.

Quality Gate Baselines

The config/quality/ directory contains multiple JSON baseline files used by CI tooling to enforce code-quality metrics such as complexity limits and duplication thresholds. These are consumed by scripts in scripts/check/quality/.

Project Root Configuration Files

Several configuration files reside at the repository root to handle environment variables, TypeScript compilation, and project metadata:

• .env.example – Template for required environment variables including API keys and feature flags; developers copy this to .env and populate secrets.
• tsconfig.json, tsconfig.typecheck-core.json, tsconfig.typecheck-noimplicit-core.json – TypeScript compiler configurations for the main application and strict type-checking runs.
• .size-limit.json – Bundle size budgets enforced by the size-limit tool during CI.
• .markdownlint.json – Linting rules for documentation files.

How OmniRoute Loads Configuration Files

At startup, the server imports configuration files using a standardized loader pattern found in the initialization sequence. The loadJson utility resolves paths relative to the working directory and parses the JSON content.

// src/lib/config/load.ts
import { readFileSync } from 'fs';
import { resolve } from 'path';

export function loadJson<T>(relativePath: string): T {
  const fullPath = resolve(process.cwd(), relativePath);
  const raw = readFileSync(fullPath, 'utf-8');
  return JSON.parse(raw) as T;
}

// Example usage from src/server/init.ts
const payloadRules = loadJson<Record<string, unknown>>('config/payloadRules.json');
console.log('Payload max size →', payloadRules.maxBytes);

Accessing and Modifying Configuration via the Settings API

OmniRoute exposes configuration data through the Settings skill endpoints, allowing administrators to query current values without direct filesystem access.

# Query current payload rules

curl -X GET https://localhost:20128/api/settings/payload-rules \
  -H "Authorization: Bearer $OMNIRoute_API_KEY"

The endpoint maps to src/lib/db/settings.ts, which reads from the underlying JSON files. For persistent changes, you can update the configuration programmatically by merging new values into the existing JSON structure:

import { writeFileSync, readFileSync } from 'fs';
import { resolve } from 'path';

function updatePayloadRules(updates: Partial<Record<string, unknown>>) {
  const cfgPath = resolve('config/payloadRules.json');
  const current = JSON.parse(readFileSync(cfgPath, 'utf-8'));
  const merged = { ...current, ...updates };
  writeFileSync(cfgPath, JSON.stringify(merged, null, 2));
}

// Increase request size limit to 5 MiB
updatePayloadRules({ maxBytes: 5 * 1024 * 1024 });

Frontend Access to Configuration

React components in the frontend can import configuration directly from the config/ directory. For example, the locale switcher reads the available languages from i18n.json:

// src/app/components/LocaleSwitcher.tsx
import localeData from '../../config/i18n.json';

export function LocaleSwitcher() {
  return (
    <select>
      {Object.entries(localeData).map(([code, name]) => (
        <option key={code} value={code}>
          {name}
        </option>
      ))}
    </select>
  );
}

This file is validated against i18n-schema.json at startup to prevent runtime errors from malformed translation data.

Summary

• Primary location: All runtime configuration files reside in the config/ directory at the repository root, including payloadRules.json, i18n.json, and the quality/ subdirectory.
• Environment configuration: The .env.example file in the project root serves as the template for environment variables required at runtime.
• Loading mechanism: The server uses the loadJson utility pattern to import configuration during initialization, as implemented in src/server/init.ts.
• API access: The Settings skill exposes REST endpoints at /api/settings/* for querying and modifying configuration values without direct filesystem manipulation.
• Validation: Schema files like i18n-schema.json ensure configuration integrity before the server accepts new values.

Frequently Asked Questions

What is the main configuration directory for OmniRoute?

The main configuration directory is config/ located at the repository root. This folder contains payloadRules.json for request validation, i18n.json for localization, and the quality/ subdirectory for code-quality baselines.

How do I change the payload size limit in OmniRoute?

Edit the maxBytes field in config/payloadRules.json directly, or use the Settings API endpoint at /api/settings/payload-rules to update the value programmatically. Changes take effect immediately after the server reloads the configuration.

Where are environment variables configured in OmniRoute?

Environment variables are managed via the .env.example file in the project root, which serves as a template. Copy this file to .env and populate it with your specific API keys, database paths, and feature flags before starting the server.

Does OmniRoute validate configuration file changes?

Yes. The i18n.json file is validated against config/i18n-schema.json at startup by the validation layer in src/lib/validation/i18nValidator.ts. Additionally, the Settings API performs type checking before persisting changes to disk.

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