How OmniRoute Defines and Manages Feature Flags Across Security, Network, and Runtime Categories

OmniRoute implements a centralized feature flag system in src/shared/utils/featureFlags.ts that resolves values via a three-tier priority chain: database overrides first, environment variables second, and hard-coded defaults last, enabling dynamic toggling of security guardrails, network proxies, and runtime behaviors without redeployment.

The open-source OmniRoute project (diegosouzapw/OmniRoute) uses a unified feature flag architecture to control behavior across three logical layers. Every flag follows the same resolution pattern, allowing operators to override defaults through a database-backed dashboard or environment variables while maintaining type safety through a centralized TypeScript registry.

Centralized Feature Flag Architecture

At the heart of the system lies src/shared/utils/featureFlags.ts, which exports a strongly typed map called FEATURE_FLAGS. This registry defines every valid flag key, its default value, description, and category classification. The resolution logic treats all flags uniformly regardless of category, ensuring consistent behavior whether the flag controls a security policy or a network transport.

The resolution hierarchy follows strict precedence:

1. Database override (highest priority) – Stored in the feature_flags table via src/lib/db/featureFlags.ts
2. Environment variable – Parsed from process.env.OMNIROUTE_<UPPERCASE_KEY>
3. Hard-coded default – Defined in the FEATURE_FLAGS map

Feature Flag Categories

While the resolution engine is category-agnostic, flags are logically grouped into Security, Network, and Runtime buckets for documentation and operational clarity.

Security Flags

Security flags control guardrails, PII handling, API-key policies, and authentication checks. These are declared in the central registry but often referenced in middleware layers.

For example, the INJECTION_GUARD_MODE flag (default "off") is resolved in src/middleware/promptInjectionGuard.ts using isFeatureEnabled(). When enabled via a database override or environment variable, the middleware activates prompt injection detection. This allows security teams to enable protections in production without code changes, or to emergency-disable them if false positives occur.

Network Flags

Network flags govern proxy handling, fallback transports, WebSocket kill-switches, and stream-recovery behavior. These are consumed by transport-layer utilities throughout the open-sse/ directory.

The PROXY_SOCKS5_ENABLED flag (default false) demonstrates this pattern in open-sse/utils/proxyFetch.ts. The code checks the flag before honoring SOCKS5 proxy configurations:

import { isFeatureEnabled } from "@/shared/utils/featureFlags";

if (isFeatureEnabled("PROXY_SOCKS5_ENABLED")) {
  // Enable SOCKS5 proxy handling
}

Similarly, the Codex WebSocket kill-switch in open-sse/executors/codex.ts uses these utilities to short-circuit connections when flags are disabled.

Runtime Flags

Runtime flags affect the request pipeline, including PII transforms, commentary dropping, combo-routing, and compression modes. These are frequently accessed during request processing.

The RESPONSES_PASSTHROUGH_DROP_COMMENTARY and STREAM_RECOVERY_ENABLED flags (both defined in src/shared/utils/featureFlags.ts) control how the system processes response streams. Their defaults are seeded in src/lib/resilience/settings/types.ts, which uses the resolved values to configure resilience policies.

Core Implementation Details

Typed Flag Definitions

The FEATURE_FLAGS object in src/shared/utils/featureFlags.ts provides compile-time safety through TypeScript's satisfies operator:

export const FEATURE_FLAGS = {
  STREAM_RECOVERY_ENABLED: {
    description: "Enable stream‑recovery resilience defaults",
    default: true,
    category: "runtime",
  },
  PROXY_SOCKS5_ENABLED: {
    description: "Enable SOCKS5 proxy support",
    default: false,
    category: "network",
  },
  // ... additional flags
} satisfies Record<string, FeatureFlagMeta>;

The category field serves documentation purposes, while the actual logic treats all flags uniformly.

Resolution Logic and Priority

The resolveFeatureFlag(key) function implements the three-tier fallback mechanism. It returns both the resolved value and a source string indicating the origin ("db", "env", or "default"):

import { resolveFeatureFlag } from "@/shared/utils/featureFlags";

const { value, source } = resolveFeatureFlag("STREAM_RECOVERY_ENABLED");
console.log(`Stream recovery is ${value ? "ON" : "OFF"} (source: ${source})`);

This origin tracking powers the Settings API's transparency features, allowing administrators to see why a particular value is active.

Database Overrides and API

The src/lib/db/featureFlags.ts module implements CRUD operations for persistent overrides:

• setFeatureFlag(key, value) – Writes to the feature_flags table
• getFeatureFlagOverrides() – Returns all active overrides as a map
• clearAllFeatureFlags() – Removes all rows (used for admin resets)

These operations are exposed via src/app/api/settings/feature-flags/route.ts, enabling the dashboard to modify flags without redeployment. The API validates inputs against the FEATURE_FLAGS registry to prevent invalid keys.

Environment Variable Fallbacks

For CI/CD pipelines and containerized deployments, flags can be set via environment variables following the pattern OMNIROUTE_<UPPERCASE_KEY>. The resolver parses these as booleans ("true"/"false" strings) when no database override exists.

Practical Usage Patterns

Components access flags through two primary helpers exported from src/shared/utils/featureFlags.ts:

Boolean checks for conditional logic:

import { isFeatureEnabled } from "@/shared/utils/featureFlags";

if (isFeatureEnabled("RESPONSES_PASSTHROUGH_DROP_COMMENTARY")) {
  // Drop commentary events from the Responses API stream
}

Full resolution with source tracking:

const { value, source } = resolveFeatureFlag("PROXY_SOCKS5_ENABLED");
// value: boolean, source: "db" | "env" | "default"

Admin override via Settings API:

// POST /api/settings/feature-flags
// Body: { "key": "INJECTION_GUARD_MODE", "value": "strict" }

Clearing all overrides:

import { clearAllFeatureFlags } from "@/lib/db/featureFlags";
await clearAllFeatureFlags(); // Removes all DB overrides, reverting to defaults

Summary

• OmniRoute uses a centralized registry in src/shared/utils/featureFlags.ts that defines all valid flags with TypeScript types, defaults, and categories.
• Resolution follows strict priority: database overrides take precedence over environment variables (OMNIROUTE_*), which take precedence over hard-coded defaults.
• Security flags (e.g., INJECTION_GUARD_MODE) control middleware guardrails in src/middleware/promptInjectionGuard.ts.
• Network flags (e.g., PROXY_SOCKS5_ENABLED) govern transport behavior in open-sse/utils/proxyFetch.ts and executor modules.
• Runtime flags (e.g., STREAM_RECOVERY_ENABLED) configure request pipeline behavior and resilience settings.
• The database layer (src/lib/db/featureFlags.ts) and Settings API (src/app/api/settings/feature-flags/route.ts) enable dynamic runtime changes without redeployment.

Frequently Asked Questions

How does OmniRoute prioritize feature flag values when multiple sources define them?

OmniRoute resolves feature flags using a three-tier priority system implemented in resolveFeatureFlag(). Database overrides stored via src/lib/db/featureFlags.ts always win. If no database row exists, the system checks for an environment variable matching OMNIROUTE_<UPPERCASE_KEY>. Only if both are absent does it fall back to the hard-coded default from FEATURE_FLAGS. The function returns a source property indicating which tier provided the value.

Can feature flags be changed at runtime without restarting the server?

Yes. Flags stored in the database are read dynamically through the getFeatureFlagOverrides() function. The Settings API endpoint at src/app/api/settings/feature-flags/route.ts allows authorized users to update values via HTTP requests, and subsequent calls to isFeatureEnabled() or resolveFeatureFlag() immediately reflect the new values. Environment variables and hard-coded defaults require a restart to change.

What is the difference between isFeatureEnabled() and resolveFeatureFlag()?

isFeatureEnabled(key) returns only the boolean resolved value, making it ideal for conditional logic like if (isFeatureEnabled("PROXY_SOCKS5_ENABLED")). resolveFeatureFlag(key) returns an object containing both the value and the source string ("db", "env", or "default"), which is useful for logging, debugging, or dashboard UI that needs to show why a flag has its current value.

How are new feature flags added to the OmniRoute codebase?

Developers add entries to the FEATURE_FLAGS object in src/shared/utils/featureFlags.ts. Each entry requires a description, default value, and category field. Once defined, the flag can be consumed anywhere in the codebase using the typed helpers. Because the system uses TypeScript's satisfies Record<string, FeatureFlagMeta>, the compiler ensures all flag keys remain consistent across the application.

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