# Set Up Redis for a Medusa Backend

Yes. An agent registers the Redis event bus, workflow engine, caching and locking providers in your Medusa config, wires the variables, checks the boot, opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-redis/medusa/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the backend's configuration before it registers a module. In a monorepo laid out like medusajs/dtc-starter, `apps/backend/medusa-config.ts` calls `defineConfig` with a `projectConfig` holding only `databaseUrl` and the `http` block (`storeCors`, `adminCors`, `authCors`, `jwtSecret`, `cookieSecret`); it has no `modules` array and no `redisUrl`. `apps/backend/.env.template` already lists `REDIS_URL=redis://localhost:6379` beside the CORS and secret entries, so the variable exists but nothing reads it. `apps/backend/package.json` pins every `@medusajs/*` package at `2.22.2`, including `@medusajs/caching`, and requires Node 22.23.4 or newer; `src/modules/`, `src/subscribers/`, `src/workflows/` and `src/jobs/` hold only their README files, and `jest.config.js` splits tests into `integration:http`, `integration:modules` and `unit` by `TEST_TYPE`. The workspace is pnpm 10.11.1 with Turborepo, and the one workflow, `.github/workflows/update.yaml`, runs the Medusa update action on a release event; nothing in CI boots the server.

With no Redis registered, Medusa falls back to in-process implementations: events, workflow state, the cache and locks live in the memory of one server process, which is fine for `medusa develop` and wrong the moment a second instance or a separate worker runs. The agent adds a `modules` array to `medusa-config.ts` with four entries, each reading its own variable so a deployment can split them later: `@medusajs/medusa/event-bus-redis` with `redisUrl` from `EVENTS_REDIS_URL` and `jobOptions` that remove completed and failed jobs after an hour or a thousand entries; `@medusajs/medusa/workflow-engine-redis` with `redis.redisUrl` from `WE_REDIS_URL`; `@medusajs/medusa/caching` with one provider, `@medusajs/caching-redis`, id `caching-redis`, `is_default` and `redisUrl` from `CACHE_REDIS_URL`; and `@medusajs/medusa/locking` with the `@medusajs/medusa/locking-redis` provider, id `locking-redis`, `is_default` and `redisUrl` from `LOCKING_REDIS_URL`. `projectConfig.redisUrl` is set from `REDIS_URL` so the HTTP session store moves to Redis too, with `redisPrefix` left at its default.

The variables are the part a reviewer will copy, so the agent updates `.env.template` with the four module URLs set to the same `redis://localhost:6379` default as `REDIS_URL`, and adds `WORKER_MODE=shared` with a comment that a production deployment runs one `server` and one `worker` process from the same image with the same Redis. It also adds `@medusajs/caching-redis` to `apps/backend/package.json` with `pnpm add`, since the core package `@medusajs/caching` is present but the Redis provider is not, and checks `pnpm-lock.yaml` records it. `AGENTS.md` in the repository root already points at `medusa-config.ts` for module configuration, so the agent adds one row there naming the Redis variables.

To check the result the agent installs Redis and Postgres in its sandbox with `apt-get`, creates the database, runs `pnpm --filter @dtc/backend exec medusa db:migrate`, then starts `medusa develop` and reads the boot log for the `Connection to Redis in module 'event-redis' established` line and the equivalent lines for the workflow engine and the providers, and for no fallback warning. It then runs `pnpm --filter @dtc/backend test:integration:http` with `TEST_TYPE` set, which boots the app through `@medusajs/test-utils` against the same config, before opening the pull request.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Set up Redis for this Medusa backend. Read apps/backend/medusa-config.ts, apps/backend/.env.template, apps/backend/package.json, apps/backend/jest.config.js, apps/backend/integration-tests/setup.js, AGENTS.md, package.json, pnpm-workspace.yaml and turbo.json first. In medusa-config.ts add a modules array registering @medusajs/medusa/event-bus-redis with redisUrl from EVENTS_REDIS_URL and jobOptions that remove completed and failed jobs after 3600 seconds or 1000 entries, @medusajs/medusa/workflow-engine-redis with redis.redisUrl from WE_REDIS_URL, @medusajs/medusa/caching with the @medusajs/caching-redis provider as default reading CACHE_REDIS_URL, and @medusajs/medusa/locking with the @medusajs/medusa/locking-redis provider as default reading LOCKING_REDIS_URL; set projectConfig.redisUrl from REDIS_URL. Add @medusajs/caching-redis with pnpm add at the same version as the other @medusajs packages. Update .env.template with the new variables and WORKER_MODE with a comment on server and worker processes, and add a row to AGENTS.md. Install Redis and Postgres in the sandbox, run the migrations, start medusa develop and confirm the Redis connection lines for each module appear with no in-memory fallback warning, run the http integration tests, then open a pull request that lists each module, its variable and its default.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request changes `apps/backend/medusa-config.ts`, `apps/backend/.env.template`, `apps/backend/package.json`, `pnpm-lock.yaml` and `AGENTS.md`. Its description is a table of the four modules and the session store, each with the resolve path, the environment variable it reads and the local default, followed by the boot-log lines from the sandbox showing each Redis connection established, and the integration test summary.

It explains why the variables are separate even though they all point at one Redis locally: a deployment can give the event queue and the workflow engine a dedicated instance later without touching the config again. It also states what did not change: no custom module, subscriber, workflow or job was added, and the storefront was not touched.

Before merging, a reviewer sets the real Redis URLs in each environment's secrets, decides whether the `jobOptions` retention suits their event volume, and plans the switch from `WORKER_MODE=shared` to one `server` and one `worker` process, which the description describes but does not make.

## Run it on every new Medusa project

A team that starts each store from the same template sends this body once per new repository from its own server, each `POST /o/{org}/sessions` with that repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own config: a backend that already registers the event bus gets only the modules it lacks, and one on a Medusa version before 2.11 gets the older `@medusajs/medusa/cache-redis` module instead of the caching provider, with the version named in the pull request.

After the first merge, an automation on the Project with a `linear` trigger on `linear.issue.labeled`, `infra` in `config.labels`, and the prompt "this issue names a Medusa module that needs its own Redis instance or different queue options; change its entry in medusa-config.ts and .env.template, check the boot log, and open a pull request" starts one run per labelled issue. The trigger adds the issue after the prompt and fills in nothing else.

## Why run it on Rush?

A Medusa backend boots happily without Redis, which is the trap: subscribers fire, workflows run and the cache works, all inside one process, and the first symptom appears in production when a worker and a server stop seeing each other's events. Getting the four registrations right means knowing which modules are plain modules and which are providers inside a module, which variable each reads, and what the boot log says when a fallback is in use. The agent checks all of that against a real Redis in its sandbox.

The boot log, the migration output and the integration test run stay with the run, so a reviewer can see each connection line rather than trust the diff. A team that runs several stores from one template applies the same change to all of them at once, each in its own sandbox.

## Frequently asked questions

### Why four variables when there is one Redis?

Each module reads its own option, and the Medusa docs name a different variable for each (`EVENTS_REDIS_URL`, `WE_REDIS_URL`, `CACHE_REDIS_URL`, `LOCKING_REDIS_URL`). Locally they all default to the same `redis://localhost:6379`; in production the event queue and the workflow engine can move to a dedicated instance by changing one variable each.

### What about the cache module I see in older guides?

`@medusajs/medusa/cache-redis` is the module Medusa used before 2.11, and it is deprecated in favour of the Caching Module with a Redis provider. On 2.22.2 the agent registers `@medusajs/medusa/caching` with `@medusajs/caching-redis`; on an older backend it registers the old module and says so in the pull request.

### Does this split the server and the worker?

No. It adds `WORKER_MODE=shared` to `.env.template` with a comment describing the `server` and `worker` values, and the description explains the two-process layout, but the change itself only makes that layout possible by moving events, workflows, cache, locks and sessions out of process memory.

### How is the configuration checked without a deployment?

The agent installs Redis and Postgres in its sandbox, runs the migrations, starts `medusa develop` and reads the boot log for each module's connection line, then runs the `integration:http` tests, which boot the app through `@medusajs/test-utils` with the same config. The log lines are quoted in the pull request.

## More Medusa jobs

- [Add S3 File Storage to a Medusa Backend](https://getrush.ai/run/add-s3-file-storage/medusa/)
- [Add a Scheduled Job to a Medusa Backend](https://getrush.ai/run/add-scheduled-job/medusa/)
- [Add Stripe Checkout to a Medusa Store](https://getrush.ai/run/add-stripe-checkout/medusa/)

## More jobs like this: Hand off a long task

- [Add Refresh Tokens to an Axum JWT API](https://getrush.ai/run/add-refresh-tokens/axum/)
- [Add Refresh Tokens to a Gin JWT API](https://getrush.ai/run/add-refresh-tokens/gin/)
- [Add Related Posts to a Gatsby Blog](https://getrush.ai/run/add-related-posts/gatsby/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
