Connect to Amazon ElastiCache for Redis OSS or Valkey from your Mac

What you need

• The cluster’s primary endpoint and port (6379 unless you chose another).
• A way into the VPC. AWS designs ElastiCache to be used from EC2 instances in the same VPC (or a peered one); a node-based cluster has no public IP address, so opening its security group to 0.0.0.0/0 still doesn’t expose it to the internet. From a Mac, the usual way in is an SSH tunnel through an EC2 instance in that VPC (a bastion host) that you can SSH to, and that the cache’s security group lets in on port 6379. AWS’s alternatives for regular use are Site-to-Site VPN and Client VPN.
• Credentials, if access control is on: the cluster’s AUTH token, or the name and password of an RBAC user. Both need in-transit encryption.
• TLS in your client if the cluster has in-transit encryption (always, for serverless caches).

AWS also describes reaching a cluster through an EC2 instance doing NAT port forwarding, but only for development and testing: that traffic isn’t encrypted, and it doesn’t work with cluster mode enabled.

Find your connection details

1. Open the ElastiCache console and choose Valkey clusters or Redis OSS clusters.
2. Choose the cluster’s name (not the button beside it). For cluster mode disabled you see the Primary endpoint and Reader endpoint; for cluster mode enabled, the Configuration endpoint under Cluster details. The Nodes tab lists each node’s own endpoint.

Or from the AWS CLI:

aws elasticache describe-replication-groups --replication-group-id <id>

Look for PrimaryEndpoint and ReaderEndpoint in the output. A primary endpoint looks like master.<cluster>.<id>.<region>.cache.amazonaws.com:6379 when in-transit encryption is on, and like <cluster>.<id>.0001.<region>.cache.amazonaws.com:6379 when it’s off.

Cluster mode disabled or enabled

With cluster mode disabled, one primary holds every key, and any client can use the primary endpoint. With cluster mode enabled, keys are split across shards by hash slot, and AWS says to use a client that supports Valkey Cluster or Redis OSS Cluster. A client connected to one node gets a MOVED reply for keys that another shard holds. On a two-node Redis 8.10.2 cluster we built on temporary containers, reading a key in slot 14984 from the node that holds slots 0–8191 returned:

MOVED 14984 192.168.215.9:6379

and SELECT 1 returned ERR SELECT is not allowed in cluster mode, so cluster-mode connections use database 0.

Serverless caches

ElastiCache Serverless always runs with cluster mode enabled and TLS on, and AWS says clients must support cluster mode (all slots appear as owned by a single virtual node). It listens on port 6379 for reads and writes and on 6380 for lower-latency, eventually consistent reads from replicas. It uses RBAC users, not AUTH tokens.

Since 29 September 2026, a serverless cache running Valkey 9.0 or later can have a public endpoint instead of a VPC endpoint, reachable from a laptop without a tunnel. Every connection to it must use IAM authentication over TLS 1.3: the password is a token, valid for 15 minutes, that AWS’s Developer Toolkit for ElastiCache or Valkey GLIDE generates from your AWS credentials.

MemoryDB

Amazon MemoryDB, AWS’s durable Valkey- and Redis OSS-compatible database, is reached the same way, from inside its VPC. Its clusters always speak the cluster protocol: AWS says to connect to the Cluster endpoint, which clients use to find which node holds which slots, so keys on another shard answer MOVED to a client that stays on one node.

Connection string

Through a tunnel that listens on your Mac’s port 6379:

rediss://<user>:<password>@localhost:6379
rediss://:<auth-token>@localhost:6379

The first is an RBAC user; the second an AUTH token, which belongs to the default user. Use redis:// if the cluster has no in-transit encryption. AUTH tokens are 16–128 printable characters whose only allowed symbols are ! & # $ ^ < > -; percent-encode # as %23 in a URL. See Redis connection strings and special characters in passwords.

TLS

AWS calls TLS in-transit encryption. It’s always on for serverless caches. For node-based clusters you choose it when you create the cluster; replication groups running Valkey 7.2 or later, or Redis OSS 7 or later, can also turn it on later. AUTH tokens and RBAC both require it.

ElastiCache’s certificates are publicly trusted: AWS issues them through AWS Certificate Manager, which records them in public Certificate Transparency logs (so don’t put anything confidential in a cluster’s name). Your Mac already trusts them; there’s no CA file to download. Since 28 April 2026 the minimum TLS version is 1.2 on Valkey 7.2 and later and Redis OSS 6 and later; public endpoints need TLS 1.3. ElastiCache doesn’t support client certificates (mutual TLS).

The certificate names the endpoint, not localhost. Through a tunnel, a client that checks host names needs to be told the endpoint’s name; redis-cli checks the certificate chain but, in our tests with 8.10.2, not the host name.

Connect with Inlet

1. Choose New Connection, pick Redis, and enter the primary endpoint as the host and port 6379.
2. Turn on the SSH tunnel and enter the bastion host and its user (ec2-user on Amazon Linux). Inlet uses the system ssh, so your ~/.ssh/config and SSH agent work. Keep the endpoint as the host: the bastion connects to it on your behalf.
3. If the cluster has in-transit encryption, turn TLS on. Inlet checks the server’s certificate.
4. For an AUTH token, enter it as the password with no user; for RBAC, the user name and password. Save it in the Keychain, or have Inlet ask every time.
5. Tag the environment. On a connection tagged production, Inlet refuses write and admin commands before they’re sent. Connecting to the reader endpoint also gives you a server that refuses writes.

Inlet connects to one node and doesn’t follow cluster redirects yet. It works with cluster mode disabled; with cluster mode enabled it explains each MOVED reply. We haven’t tried it against a serverless cache.

Connect from the command line

Open the tunnel (it runs until you press Control-C):

ssh -N -L 6379:<primary endpoint>:6379 ec2-user@<bastion>

Then, in another window, connect to your end of it:

REDISCLI_AUTH='<auth-token>' redis-cli --tls --sni <primary endpoint> -h localhost -p 6379 PING

--sni sends the endpoint’s name in the TLS handshake, as a direct connection would. For an RBAC user, add --user <user> and put that user’s password in REDISCLI_AUTH. Leave out --tls and --sni if the cluster has no in-transit encryption. If something else on your Mac already uses port 6379, pick another local port: -L 6380:<primary endpoint>:6379, then -p 6380.

We checked the tunnel against an OpenSSH server in Docker standing in for the bastion, forwarding a local port to a Redis 8.10.2 server behind it. A PING sent to the local port reached Redis, which answered -NOAUTH Authentication required., and after AUTH, +PONG.

On the bastion itself, AWS suggests the Valkey package on Amazon Linux 2023, whose valkey-cli has TLS built in:

sudo dnf install valkey -y
valkey-cli -h <primary endpoint> --tls --askpass -p 6379

For cluster mode enabled, connect to the configuration endpoint and add -c, which makes the client follow MOVED and ASK redirects.

Troubleshooting

• A timeout, or a connection that hangs: the cache’s security group doesn’t let the bastion in on 6379, the bastion is in another VPC, or TLS is off in your client while the cluster has in-transit encryption (AWS lists a hung connection as the sign of that).

• Connection refused on localhost: the tunnel isn’t running, or it listens on a different local port. Inlet reports Couldn’t connect to localhost:6379: Connection refused.

• READONLY You can’t write against a read only replica: you’re on the reader endpoint or a replica’s node endpoint. Use the primary endpoint to write. On a temporary Redis 8.10.2 replica:

  READONLY You can't write against a read only replica.
  

• MOVED: the cluster has cluster mode enabled. Inlet says This key is on another node of the cluster (slot <n>, on <host:port>). Inlet connects to one node: connect to that one to use it. Through an SSH tunnel, that node’s address is inside the VPC: tunnel to it instead.

• CROSSSLOT: with cluster mode enabled (and on serverless caches), a command, transaction or script used keys in different hash slots.

• NOAUTH Authentication required or WRONGPASS: a missing or wrong AUTH token or password, or an RBAC user that’s off or isn’t in the user group attached to this cache. Inlet says The server needs a password. or Wrong user name or password. and asks again.

• Max number of clients reached: every connection slot is taken (serverless caches allow 65,000 clients).