Setup

Enable Redis

Redis is opt-in. You enable it per environment from Creator Studio:

1. Open your app in Creator Studio.
2. Go to the Infrastructure tab.
3. Find the Redis card and click Enable Redis.
4. On the Redis page, click Provision Redis for the environment you want (dev or prod).
5. Wait for the status to flip to Ready. Provisioning usually takes less than a minute.

You need hosting to be enabled for the environment first. If you see an error telling you to enable hosting, do that from the Hosting tab and come back.

You can provision dev and prod independently. Disabling one environment does not affect the other.

Use Redis from your hosted runtime

Your hosted service receives a single environment variable automatically:

Install a Redis client in your project:

npm install redis

Or with Bun:

bun add redis

Create a client that reads REDIS_URL:

import { createClient } from "redis";

const redis = createClient({
  url: process.env.REDIS_URL,
});

redis.on("error", (error) => {
  console.error("Redis client error", error);
});

await redis.connect();

export { redis };

ioredis works equally well if you prefer it — both libraries parse redis://user:password@host:port URLs.

Use Redis from local development

Because Redis is exposed through Railway's TCP proxy, you can connect to the same instance from your local machine using the same REDIS_URL.

Pull env vars locally:

buildspace env pull

REDIS_URL is included automatically — no extra wiring needed. Your local code uses the same createClient({ url: process.env.REDIS_URL }) pattern and connects to the hosted Redis over the TCP proxy.

Optional: local-only Redis

If you want to keep local development completely isolated, run Redis in a container:

docker run --rm -p 6379:6379 redis:8-alpine

Then set in .env.local:

REDIS_URL=redis://localhost:6379

Your code does not need to change — it always reads REDIS_URL.

Disable Redis

On the Redis page in Creator Studio, click Disable on an environment's card. This:

• removes the Railway volume for that environment,
• revokes the REDIS_URL env var for that environment,
• blanks the Redis reference on the runtime service.

If no environments still have Redis enabled, the shared Redis service is removed from your Railway project.

Troubleshooting

• Status stuck on "Provisioning" — Reconciliation runs through Railway and occasionally takes a minute. Refresh the Infrastructure page. If it stays stuck for several minutes, disable the environment and provision again.
• Status shows "Issue" — The card displays the underlying error message. Common causes are missing Railway credentials on the platform side and transient Railway GraphQL errors. Re-provision to retry.
• Cannot connect from local dev — Confirm REDIS_URL shows up after buildspace env pull. If it is missing, the TCP proxy did not come up; disable and re-provision the environment.