Redis

Connect Redis to CloudThinker for cache performance monitoring across self-hosted, Upstash, or Redis Cloud deployments

Connect your Redis databases to enable Tony (Database Engineer) to inspect keyspace usage, analyze command patterns, and monitor database health.

Supported platforms

Platform	Support
Self-hosted Redis	6.x, 7.x (vanilla and Redis Stack)
Upstash Redis	All plan tiers
Redis Cloud	All plan tiers

Prerequisites

• A Redis instance reachable from CloudThinker over the network.
• Admin access to create an ACL user (self-hosted) or RBAC user (Upstash/Redis Cloud).
• A REDIS_URL connection string with credentials.

Setup

Select your Redis platform for specific connection instructions.

Self-hosted Redis

Two common deployment shapes are supported:

• Vanilla Redis — minimal image, no modules. Use when you only need core Redis commands.
• Redis Stack — bundles RediSearch, RedisJSON, RedisTimeSeries, and Bloom. Use when Tony needs FT.*, JSON.*, TS.*, or BF.* commands. Vanilla soft-fails those.

1. Start Redis

   Vanilla Redis (no modules):

   docker run -d --name redis-min \
     -p 6379:6379 \
     redis:7-alpine \
     redis-server --requirepass <admin-password> --appendonly yes
   

   The admin password is set via the --requirepass server flag. --appendonly yes enables AOF for durability across restarts.

   Redis Stack (with modules and RedisInsight UI on port 8001):

   docker run -d --name redis-stack \
     -p 6379:6379 -p 8001:8001 \
     -e REDIS_ARGS="--requirepass <admin-password>" \
     redis/redis-stack:latest
   

   Verify the instance:

   redis-cli -a <admin-password> ping
   # PONG
   
2. Create a read-only ACL user

   Create a dedicated user for CloudThinker. Redis ACL usernames allow [A-Za-z0-9_-]; use cloudthinker-readonly.

   redis-cli -a <admin-password> ACL SETUSER cloudthinker-readonly on \
     '><readonly-password>' \
     '~*' \
     '+@read' '-@write' '-@dangerous' '-@admin'
   

   • on — enable the user
   • ><readonly-password> — set the password (the > prefix is ACL syntax)
   • ~* — match all keys; narrow to ~app:* for stricter scoping
   • +@read -@write -@dangerous -@admin — reads only; blocks writes, FLUSHALL/CONFIG/DEBUG/SHUTDOWN, and replication
   • Optional: append -@slow to block KEYS, SMEMBERS, HGETALL on large collections
3. Persist ACLs across restart

   Mount a users.acl file so ACLs survive container restarts:

   user default on ><admin-password> ~* &* +@all
   user cloudthinker-readonly on ><readonly-password> ~* +@read -@write -@dangerous -@admin
   

   Start Redis with the file mounted:

   -v $PWD/users.acl:/data/users.acl
   

   and add --aclfile /data/users.acl to the server command.

4. Verify the read-only user

   redis-cli -u redis://cloudthinker-readonly:<readonly-password>@localhost:6379 SET foo bar
   # (error) NOPERM ... has no permissions to run the 'set' command
   
   redis-cli -u redis://cloudthinker-readonly:<readonly-password>@localhost:6379 GET foo
   # works
   
5. Configure network access

   Ensure CloudThinker can reach your database:

   • Add CloudThinker IPs to your firewall or security group
   • Ensure Redis is bound to an accessible interface (avoid bind 127.0.0.1 only)
6. Add the connection in CloudThinker

   Navigate to Connections → Redis and enter your connection string as REDIS_URL:

   redis://cloudthinker-readonly:<readonly-password>@<your-host>:6379
   

   Use rediss:// (note the second s) if your deployment terminates TLS. Click Connect. CloudThinker shows a Connected status once it succeeds.

Upstash Redis

1. Create a database

   Open the Upstash Redis console and click Create Database. In the modal:

   • Enter a Database Name
   • Pick a Primary Region and Cloud Provider
   • Enable Eviction (recommended)
   • Click Next, choose your plan, and confirm
2. Copy the TCP connection URL

   On the database page, scroll to the Connection section. The default tab is REST — switch to the TCP tab and copy the URL:

   rediss://<username>:<password>@<hash>.upstash.io:<port>
   

   <hash> is unique to your database; <port> is typically 6379. Upstash enforces TLS, so the scheme is rediss://.

3. Create a read-only user (optional)

   Upstash supports RBAC under the RBAC tab on the database page. Activate RBAC, then create an account named cloudthinker-readonly with read-only permissions. The ACL model is the same as the self-hosted setup — grant +@read and deny -@write, -@dangerous, -@admin.

   See the Upstash RBAC documentation for the exact UI flow.

4. Add the connection in CloudThinker

   Navigate to Connections → Redis and paste the URL as REDIS_URL. Click Connect. CloudThinker shows a Connected status once it succeeds.

Redis Cloud

1. Create a database

   Open the Redis Cloud databases page and click New database. Pick your plan, Database Name, Database Version, Cloud Vendor, and Region, then click Create Database.

   Return to the databases page — your new database appears in the list.

2. Copy the connection URL

   On the database tile, find the Connection to database card and click Connect. In the side panel:

   • Close the default Redis SDK clients dropdown
   • Select Redis CLI
   • Copy the URL

   The URL follows this format:

   redis://<username>:<password>@<hash>.cloud.redislabs.com:<port>
   

   Redis Cloud ports are typically in the 13xxx range rather than 6379.

3. Create a read-only role and user

   Open the Data Access Control roles page:

   • Click New role and name it cloudthinker-readonly
   • Set ACL Rules to Read-Only
   • Pick the databases this role can access
   • Click Save role

   Then create or assign a user bound to this role and use that user’s credentials in the connection URL.

4. Add the connection in CloudThinker

   Navigate to Connections → Redis and paste the URL as REDIS_URL. Click Connect. CloudThinker shows a Connected status once it succeeds.

Connection details

Field	Description	Example
REDIS_URL	Redis connection URI including credentials	redis://cloudthinker-readonly:pass@host:6379
TLS/SSL	Use rediss:// scheme to require TLS	rediss:// for Upstash; optional elsewhere
Port	Redis port	6379 (self-hosted, Upstash); 13xxx (Redis Cloud)
Database index	Logical DB index	0

Required permissions

Recommended ACL categories for the CloudThinker user:

Category	Setting	Why
+@read	Allow	Read keys, run INFO, CLIENT LIST, etc.
-@write	Deny	Block SET, DEL, and other mutating commands
-@dangerous	Deny	Block FLUSHALL, CONFIG, DEBUG, SHUTDOWN, replication
-@admin	Deny	Block administrative commands
-@slow (optional)	Deny	Block KEYS, SMEMBERS, HGETALL on large collections

Key scoping (~* for all keys, or ~app:* for a prefix) narrows what the CloudThinker user can access. Start with ~* and tighten as needed.

Agent capabilities

Once connected, Tony can:

Capability	Description
Keyspace analysis	Inspect key patterns, sizes, and TTL distributions
Command stats	Review command latency and throughput via INFO commandstats
Performance metrics	Monitor memory, connections, eviction, and replication lag
Module insights	Inspect RediSearch indexes, RedisJSON documents, and TimeSeries (Redis Stack only)

Verify the connection

@tony #report run Redis INFO and summarize memory usage, connected clients, and keyspace stats

Example prompts

@tony #report analyze hot keys and memory distribution on the production Redis instance
@tony #report check memory fragmentation ratio and eviction stats
@tony #report review replication lag on the Redis replica

Troubleshooting

Authentication failed (NOAUTH / WRONGPASS)

• Verify the username and password in the connection URL
• For self-hosted, confirm the user is enabled with ACL WHOAMI and ACL LIST
• For Upstash and Redis Cloud, make sure you copied the TCP/Redis CLI URL, not the REST or SDK URL

NOPERM — no permissions to run the command

• The read-only user is working as intended for write commands
• If reads are also blocked, re-check the ACL rules — +@read must be granted

Connection refused or timeout

• Verify host and port are reachable from CloudThinker
• For self-hosted, ensure Redis is not bound only to 127.0.0.1
• Add CloudThinker IPs to your firewall or cloud provider allowlist

Module commands fail (FT.*, JSON.*, TS.*, BF.*)

• Vanilla Redis does not include modules. Run Redis Stack (redis/redis-stack) or a managed equivalent that bundles the required modules.

Security

• Least privilege — grant only the permissions the agents need for your use case; start read-only and widen later.
• Read-only by default — use read-only credentials unless you want agents to make changes through this connection.
• Rotate credentials — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
• Revoke on offboarding — remove the credential at the provider when you delete a connection or a teammate leaves.

• Use rediss:// for TLS — use the rediss:// scheme whenever your deployment supports TLS to encrypt data in transit.
• Persist ACLs — use aclfile for self-hosted deployments so the read-only user survives restarts.

Related

Tony Agent

Database-focused optimization agent

MongoDB Connection

Setup instructions for MongoDB databases