How to Configure Embedded Services (Redis & Cloudflare Workers Relay) in OmniRoute

Set QUOTA_STORE_DRIVER=redis and QUOTA_STORE_REDIS_URL to enable the Redis quota backend, and provide CLOUDFLARE_ACCOUNT_ID with CLOUDFLARE_API_TOKEN to deploy the Cloudflare Workers relay via the internal /api/settings/proxy/cloudflare-deploy endpoint.

OmniRoute supports two optional embedded services that extend the core router functionality: a Redis-based quota store for high-performance rate limiting and a Cloudflare Workers relay for routing requests to Cloudflare AI endpoints. Both services are configured exclusively through environment variables and internal API calls, requiring no modifications to the source code in the diegosouzapw/OmniRoute repository.

Redis Quota Store Configuration

The Redis quota store provides a high-throughput sliding-window cache for rate limiting and cost tracking. If Redis is unavailable, OmniRoute automatically falls back to the SQLite implementation.

Environment Variables

Configure these variables in your .env file or container environment:

• QUOTA_STORE_DRIVER: Set to redis to enable the Redis backend. Defaults to sqlite.
• QUOTA_STORE_REDIS_URL: The full Redis connection URL (e.g., redis://localhost:6379).
• REDIS_URL: Legacy alias used by the warm-up scheduler and other subsystems requiring a generic Redis client.

When QUOTA_STORE_DRIVER=redis, OmniRoute imports the RedisQuotaStore class from src/lib/quota/redisQuotaStore.ts. This module creates a lazy singleton wrapping an ioredis client. All quota-checking logic in src/domain/quotaCache.ts and src/domain/policyEngine.ts calls getRedisQuotaStore(), which returns either the Redis instance or the fallback SQLite store.

Implementation Details

The Redis client is initialized as a lazy singleton to prevent unnecessary connections during startup. The resetRedisQuotaStore() function in src/lib/quota/redisQuotaStore.ts handles graceful teardown, closing the client socket and preventing connection pool exhaustion when the service restarts.

Docker Compose Example

Deploy OmniRoute with Redis using the following configuration:

services:
  omniroute:
    image: omniroute:latest
    env_file: .env
    ports:
      - "20128:20128"
  redis:
    image: redis:7
    ports:
      - "6379:6379"

In your .env file:

QUOTA_STORE_DRIVER=redis
QUOTA_STORE_REDIS_URL=redis://redis:6379
REDIS_URL=redis://redis:6379

After startup, OmniRoute uses Redis for all quota-related operations. Removing or stopping the Redis container triggers an automatic fallback to SQLite without data loss.

Cloudflare Workers Relay Setup

The Cloudflare Workers relay acts as a thin HTTP proxy that forwards requests from OmniRoute to Cloudflare-hosted AI endpoints (cloudflare-ai). The router deploys and manages this worker automatically.

Required Environment Variables

• CLOUDFLARE_ACCOUNT_ID: The Cloudflare account identifier that owns the worker script.
• CLOUDFLARE_API_TOKEN: API token with Account.Workers Scripts edit permissions.
• CLOUDFLARE_WORKER_NAME: The script name (defaults to omniroute-relay).
• CLOUDFLARE_WORKER_SUBDOMAIN: Optional custom subdomain for *.workers.dev. If omitted, Cloudflare generates a random subdomain.

Deployment Mechanism

The deployment logic resides in src/lib/proxyRelay/cloudflareWorkerScript.ts. This file contains the worker JavaScript code and constructs a multipart/form-data request to Cloudflare's Workers API (/accounts/:accountId/workers/scripts/:scriptName).

The API route src/app/api/settings/proxy/cloudflare-deploy/route.ts handles the deployment trigger. It streams the request to Cloudflare and returns the worker URL upon success. Errors are sanitized through src/open-sse/utils/error.ts to prevent credential leakage.

Deployment Steps

Execute the deployment via the internal API:

# Set required environment variables

export CLOUDFLARE_ACCOUNT_ID=abcd1234
export CLOUDFLARE_API_TOKEN=xxxxxxxxxxxxxxxxxxxx
export CLOUDFLARE_WORKER_NAME=omniroute-relay

# Trigger deployment

curl -X POST http://localhost:20128/api/settings/proxy/cloudflare-deploy \
  -H "Authorization: Bearer <admin-api-key>" \
  -H "Content-Type: application/json" \
  -d '{}'

On success, the response contains the worker URL (e.g., https://omniroute-relay.yourname.workers.dev). OmniRoute stores this endpoint in src/lib/proxyRelay/registry.ts, automatically routing subsequent cloudflare-ai provider requests through the deployed worker.

Dashboard Integration

The service status is monitored by src/lib/services/ServiceSupervisor.ts, which polls the worker's health endpoint (/healthz). The UI components in src/app/(dashboard)/dashboard/providers/services/components/ServiceStatusCard.tsx display this status, while src/app/(dashboard)/dashboard/providers/services/tabs/*ServiceTab.tsx files provide deployment controls and log viewing capabilities.

Summary

• Set QUOTA_STORE_DRIVER=redis and provide QUOTA_STORE_REDIS_URL to enable the Redis quota backend implemented in src/lib/quota/redisQuotaStore.ts.
• Configure CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN to authorize Cloudflare Workers deployments via the internal API at /api/settings/proxy/cloudflare-deploy.
• Use the Cloudflare Workers relay to proxy AI requests through Cloudflare's infrastructure, with deployment logic managed in src/lib/proxyRelay/cloudflareWorkerScript.ts.
• Monitor embedded services through the dashboard components that consume data from src/lib/services/ServiceSupervisor.ts.

Frequently Asked Questions

What happens if the Redis connection fails?

OmniRoute automatically falls back to the SQLite quota store. The getRedisQuotaStore() function in src/lib/quota/redisQuotaStore.ts handles this fallback gracefully, ensuring continuous rate limiting functionality even when Redis is unavailable.

Can I customize the Cloudflare Worker subdomain?

Yes. Set the CLOUDFLARE_WORKER_SUBDOMAIN environment variable to your preferred subdomain before calling the deployment endpoint. If omitted, Cloudflare generates a random subdomain under workers.dev.

Where is the Cloudflare Worker source code located?

The worker JavaScript is embedded in src/lib/proxyRelay/cloudflareWorkerScript.ts. This file contains the forwarding logic that sends requests to https://api.cloudflare.com/client/v4/accounts/:accountId/ai/v1/... and is uploaded to Cloudflare's edge during the deployment process.

How do I check if the embedded services are healthy?

The ServiceSupervisor class in src/lib/services/ServiceSupervisor.ts monitors all embedded services by polling their health endpoints. Access the dashboard at /dashboard/providers/services/ to view real-time status through ServiceStatusCard.tsx components.

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