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

> Learn to configure embedded services like Redis and Cloudflare Workers relay in OmniRoute. Enable Redis quota backend and deploy Cloudflare Workers relay using simple API settings.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-08-10

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/quota/redisQuotaStore.ts). This module creates a lazy singleton wrapping an **ioredis** client. All quota-checking logic in [`src/domain/quotaCache.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/domain/quotaCache.ts) and [`src/domain/policyEngine.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

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

```

In your `.env` file:

```env
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/open-sse/utils/error.ts) to prevent credential leakage.

### Deployment Steps

Execute the deployment via the internal API:

```bash

# 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/proxyRelay/cloudflareWorkerScript.ts).
- **Monitor embedded services** through the dashboard components that consume data from [`src/lib/services/ServiceSupervisor.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/ServiceStatusCard.tsx) components.