Hero Redis

A high-performance, Redis-compatible server built on redb with ChaCha20-Poly1305 encryption and dual authentication modes.

Features

• Redis Protocol Compatible - Works with any Redis client including Redis Desktop Manager
• Dual Authentication:
  • Simple: Secret-based auth with AUTH <secret> (recommended for most users)
  • Advanced: Ed25519 signature-based auth (for high-security environments)
• Multi-Database with ACL - Per-database Read/Write/Admin permissions
• Persistent Storage - Data stored in redb (pure Rust embedded database)
• Encryption - All values encrypted with ChaCha20-Poly1305
• Multiple Databases - Up to 1000 databases with lazy loading
• Low Memory - ~3MB at startup, databases loaded on demand
• Auto-cleanup - Idle databases automatically closed after 5 minutes
• Unix Socket & TCP - Both connection methods supported
• Vector Search - HNSW-based similarity search with hannoy library
• Cross-platform - Linux (x86_64, aarch64) and macOS (x86_64, aarch64)

Quick Start

Build from Source

git clone https://github.com/herocode/hero_redis.git
cd hero_redis
cargo build --release

Start Server (Simple Auth)

# Start with admin secret (simplest way)
./target/release/hero_redis \
  --encryption-key "your-encryption-key" \
  --admin-secret "your-admin-secret" \
  --data-dir ~/.hero_redis

Connect and Use

# Using redis-cli (default port is 6666)
redis-cli -p 6666

# Authenticate with your secret
> AUTH your-admin-secret
OK

# Now use any Redis command
> SET mykey myvalue
OK
> GET mykey
"myvalue"

Using with Redis Desktop Manager

1. Start server with --admin-secret
2. In Redis Desktop Manager, configure connection:
   • Host: 127.0.0.1
   • Port: 6666
   • Auth: your-admin-secret
3. Connect and use normally

Authentication Modes

1. Simple Auth (Recommended)

Start the server with --admin-secret:

./target/release/hero_redis \
  --encryption-key "encryption-key" \
  --admin-secret "my-secret-password"

Connect with AUTH:

AUTH my-secret-password

Create users with secrets:

USER.CREATESECRET alice alice-secret-123
USER.GRANT 1 alice write

Users authenticate with:

AUTH alice-secret-123

2. Advanced Auth (Ed25519)

For high-security environments, use Ed25519 signature-based authentication:

# Generate keypair
./target/release/hero_redis_login --generate

# Start server with pubkey
./target/release/hero_redis \
  --encryption-key "encryption-key" \
  --admin-pubkey "a1b2c3d4..."

Authentication flow:

CHALLENGE          → returns random challenge
TOKEN <pubkey> <signature>  → returns session token
AUTH <token>       → authenticates session

Command Line Options

Server (hero_redis)

Note: At least one of --admin-secret or --admin-pubkey must be provided.

User Management

Create Users (Secret-based)

# As admin, create a user with a secret
USER.CREATESECRET <username> <secret>

# Example
USER.CREATESECRET alice mysecretpassword

Create Users (Ed25519-based)

# As admin, register a user's public key
USER.CREATE <pubkey>

# Example
USER.CREATE a1b2c3d4e5f6...

Grant Permissions

# Grant access to a database
USER.GRANT <db_number> <username_or_pubkey> <read|write|admin>

# Examples
USER.GRANT 1 alice write
USER.GRANT 2 bob read
USER.GRANT 1 a1b2c3d4e5f6... admin

Revoke Permissions

USER.REVOKE <db_number> <username_or_pubkey>

# Example
USER.REVOKE 1 alice

Permission Levels

Admin Commands

Server Admin Commands

Public Read-Only Access

You can make a database publicly readable (no authentication required for reads):

# As admin, make database 1 public
DATABASE.PUBLIC 1 on

# Now anyone can read without AUTH
SELECT 1
GET publickey    # Works without authentication
SET key value    # Fails - writes still require auth

Database Admin Commands

Supported Redis Commands

Authentication

AUTH, SAUTH, CHALLENGE, TOKEN

String Commands

GET, SET, MGET, MSET, DEL, EXISTS, EXPIRE, TTL, KEYS, SCAN, INCR, INCRBY, DECR, DECRBY, APPEND, STRLEN, GETRANGE, SETNX, SETEX, GETSET, TYPE

Hash Commands

HSET, HGET, HMSET, HMGET, HGETALL, HDEL, HEXISTS, HLEN, HKEYS, HVALS, HINCRBY, HSETNX, HSCAN

List Commands

LPUSH, RPUSH, LPOP, RPOP, LRANGE, LLEN, LINDEX, LSET, LREM

Set Commands

SADD, SREM, SMEMBERS, SISMEMBER, SCARD, SPOP, SUNION, SINTER, SDIFF, SSCAN

Stream Commands

XADD, XLEN, XRANGE, XREVRANGE, XREAD, XINFO, XTRIM, XGROUP, XREADGROUP, XACK, XPENDING

Vector Commands

VECTOR.CREATE, VECTOR.ADD, VECTOR.SEARCH, VECTOR.SEARCHBYID, VECTOR.GET, VECTOR.DEL, VECTOR.BUILD, VECTOR.INFO, VECTOR.LIST, VECTOR.DROP, VECTOR.CLEAR, VECTOR.EXISTS, VECTOR.LEN

Connection Commands

PING, AUTH, SAUTH, SELECT, QUIT, COMMAND

Management Commands

COMPACT, SHUTDOWN, MEMORY USAGE, MEMORY STATS, DBSIZE, FLUSHDB, INFO, CONFIG, CLIENT

Vector Search

Hero Redis includes HNSW-based vector similarity search:

# Create a vector index (128 dimensions, cosine similarity)
VECTOR.CREATE myindex 128 cosine

# Add vectors
VECTOR.ADD myindex 1 0.1 0.2 0.3 ...
VECTOR.ADD myindex 2 0.4 0.5 0.6 ...

# Build the index
VECTOR.BUILD myindex

# Search for similar vectors (returns top 10)
VECTOR.SEARCH myindex 10 0.1 0.2 0.3 ...

# Search by existing vector ID
VECTOR.SEARCHBYID myindex 1 10

Using as a Library

use hero_redis::hero_redis_client::HeroRedisClient;

// Connect with your private key
let mut client = HeroRedisClient::new("127.0.0.1", 6379, "your_private_key_hex")?;
client.select(1)?;

// String operations
client.set("name", "Alice")?;
let name = client.get("name")?.unwrap();

// Hashes
client.hset("user:1", "name", "Bob")?;
let user = client.hgetall("user:1")?;

// Lists
client.rpush("queue", "job1")?;
let job = client.lpop("queue")?;

// Sets
client.sadd("tags", "rust")?;
let tags = client.smembers("tags")?;

Data Storage

• Data directory: ~/.hero_redis/ (configurable)
• Database files: db0.redb, db1.redb, ... db999.redb
• DB 0 is reserved for admin metadata
• Each database has its own encryption key
• Values are encrypted with ChaCha20-Poly1305

License

Apache 2.0