Redis cache
Use Redis for caching.
Connect your agent today
Draft from chat, review in your calendar, and publish only what you approve.
Overview
By default the backend uses Redis for cache (CACHE_PROVIDER=redis). For local development, run Redis via Docker (recommended); if you don’t want Redis locally, you can fall back to CACHE_PROVIDER=memory.
The same REDIS_HOST / REDIS_PORT / REDIS_PASSWORD values are also used for BullMQ when integration refresh runs in distributed mode (transport: bullmq in backend/config/orchestratorFlows.ts). That path uses the Flowcraft distributed execution model with the BullMQ adapter and a dedicated BullMQ client (ioredis), not the redis package used by RedisCacheProvider. Optional REDIS_BULLMQ_DB selects the logical Redis database for queues (defaults to REDIS_DB).
Steps
Create a Redis database
If you don’t have Redis already, you can create one via Redis Cloud (or your preferred provider).
Once the database is ready, open your provider’s configuration/settings page and collect:
| Detail | Where to find it |
|---|---|
| Host | Public endpoint, the hostname portion (e.g. redis-*****18904.*.ap-southeast-1-1.ec2.cloud.redislabs.com) |
| Port | Public endpoint, the port number after : (e.g. 18903) |
| Password | Database Security section (often “Default user password”) |
Local development (Docker)
The repo includes a minimal local Redis in infra/docker-compose.yml. This is the recommended way to run Redis for local development so your API + workers never accidentally point at a shared production instance.
# From repo root
docker compose -f infra/docker-compose.yml up -d redisTo stop it:
docker compose -f infra/docker-compose.yml downThen configure backend/.env.development.local to point at Docker:
CACHE_PROVIDER=redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0
REDIS_TLS=false
REDIS_TLS_REJECT_UNAUTHORIZED=true
REDIS_BULLMQ_DB=0Set the backend env variables
Edit backend/.env.development.local (or your production env). A typical Redis-backed setup looks like this (use your provider’s host, port, and password — do not commit real secrets):
# -----------------------------------------------------------------------------
# Cache (memory or redis; used for module_configs etc.)
# -----------------------------------------------------------------------------
CACHE_PROVIDER=redis
CACHE_DEFAULT_TTL=900
CACHE_LOG_HITS=true
CACHE_LOG_MISSES=true
CACHE_CHECK_PERIOD=60
CACHE_USE_CLONES=false
CACHE_ENABLED=true
CACHE_ENABLE_PATTERNS=true
# Redis (when CACHE_PROVIDER=redis). Point at your local or managed Redis host.
# These placeholder lines target localhost:6379 with no password — they will FAIL integration checks
# (e.g. pnpm test:integration:bullmq-redis) unless you run Redis locally (e.g. Docker). Copy real host/port/password
# from your provider into .env.development.local; managed Redis often needs REDIS_TLS=true as well.
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0
REDIS_TLS=false
REDIS_TLS_REJECT_UNAUTHORIZED=true
REDIS_PREFIX=app:cache:
REDIS_MAX_RECONNECT_ATTEMPTS=10
REDIS_ENABLE_OFFLINE_QUEUE=true
REDIS_USE_SCAN=true
# Optional: logical Redis DB for BullMQ / Flowcraft queues (defaults to REDIS_DB).
REDIS_BULLMQ_DB=0For Redis-backed cache, set CACHE_PROVIDER=redis and replace the placeholder REDIS_HOST / REDIS_PORT / REDIS_PASSWORD with your provider values. Managed hosts often need REDIS_TLS=true (and only in local dev, if required, REDIS_TLS_REJECT_UNAUTHORIZED=false).
Integration token refresh in BullMQ mode uses the same REDIS_* connection. Set orchestratorFlows.integrationRefresh.transport to bullmq in backend/config/orchestratorFlows.ts (enabled, queue name, and transport are documented there). See Backend orchestrator workflows.
Verify the connection
Start the backend and look for a Redis “connected” log line. If you see connection failures, re-check host/port/password.
You can also run these opt-in smoke tests:
# Local dev / Docker Redis (uses backend/.env.development.local)
cd backend
pnpm test:integration:bullmq-redis
pnpm test:integration:third-parties:redis
# Production-connection smoke test (uses backend/.env.production.local)
pnpm test:integration:third-parties:prod:redisOptional: BullMQ connectivity (distributed refresh worker)
With Redis running, you can confirm the queue client from the backend package:
cd backend
pnpm test:integration:bullmq-redisThen run the worker (after setting transport: bullmq for integration refresh in backend/config/orchestratorFlows.ts and redeploying the API):
# From repository root (recommended)
pnpm orchestrator:dev:worker:integration-refresh-bullmqFor production worker hosts (always-on), use pnpm railway:orchestrator:build and pnpm railway:orchestrator:start:integration-refresh as documented in Configuration - Worker and Railway (orchestrator workers).