Guide: Implementing Custom Users Storage in Xray-core (with Redis example)

[thearialume]

🤔 What is this document about?

This document covers all of the essentials for implementation of custom users storage for Xray-core and it's integration into other protocols. Everything written here doesn't imply any workarounds or hacks, it's completely compatible with all the existing Xray-core functionality.

Although, protocols based on AEAD such as ShadowSocks and VMess, require more research due to their unique user validation logic.

This document also doesn't cover protocols without proxy.UserManager implementation such as HTTP and SOCKS5, they require different approach.

All further information was fully tested and confirmed only for VLESS protocol, expect other protocols to have different structure and underlying logic.

📝 A little backstory

Right now, there are no possible ways in Xray-core to dynamically authenticate users at the runtime. It only supports users management via the gRPC API. It works, but it's not great at scale, as it requires you to sync current users across every server.

So, in March of this year, I started working on external authentication for Xray Core. The main goal was to bring support for dynamic users authentication through HTTP API and CLI as it was made in Hysteria2, while also creating a simple interface for developers to create their own methods.

But exploring Xray-core, I realized that architecture of my solution was too complicated. I took one more look at the Alternative for clients storage discussion. The only reasonable solution, given the Xray-core architecture.

With the gained experience I changed project's direction from users authentication to alternative users storage. However, I never managed to finish it: it was important to me for this feature to be merged in Xray-core, but it brought so significant changes, it seemed unlikely to me. Project was shelved and eventually removed.

Last week I received a message with questions about current state of project. I told everything as it is. They told me they want to continue on this idea and in case I have anything left, it will be helpful.

Unfortunately, all the code was deleted, but I still had bunch of notes with explanations, overall architecture, methods, ideas and code snippets. So, I decided to collect them all into one document and release it to the community.

📌 Introduction to Validator

All of the major protocols like VLESS, Hysteria2, Trojan, VMess and ShadowSocks are implementing Validator interface as their authentication backend.

Although, it is not a standardized solution, all of these protocols implement it almost identically with slight difference for AEAD based protocols.

Here is exact interface found in /proxy/vless/validator.go:

type Validator interface {
	Get(id uuid.UUID) *protocol.MemoryUser // Arguments are protocol specific
	Add(u *protocol.MemoryUser) error
	Del(email string) error
	GetByEmail(email string) *protocol.MemoryUser
	GetAll() []*protocol.MemoryUser
	GetCount() int64
}

Protocols based on AEAD can have additional methods like:

	GetAEAD(userHash []byte) (*protocol.MemoryUser, bool, error)
	GetBehaviorSeed() uint64	

Why do protocols need this? Since all of these protocols are exposed through API's HandlerService, it requires them to implement proxy.UserManager interface. So Validator helps to satisfy this requirement, while also being useful as an authentication backend. You can find proxy.UserManager implementation in each of the protocols and all of them are wrapping Validator, e.g. in /proxy/vless/inbound/inbound.go:

// AddUser implements proxy.UserManager.AddUser().
func (h *Handler) AddUser(ctx context.Context, u *protocol.MemoryUser) error {
	return h.validator.Add(u)
}

// RemoveUser implements proxy.UserManager.RemoveUser().
func (h *Handler) RemoveUser(ctx context.Context, e string) error {
	h.RemoveReverse(h.validator.GetByEmail(e))
	return h.validator.Del(e)
}

// GetUser implements proxy.UserManager.GetUser().
func (h *Handler) GetUser(ctx context.Context, email string) *protocol.MemoryUser {
	return h.validator.GetByEmail(email)
}

// GetUsers implements proxy.UserManager.GetUsers().
func (h *Handler) GetUsers(ctx context.Context) []*protocol.MemoryUser {
	return h.validator.GetAll()
}

// GetUsersCount implements proxy.UserManager.GetUsersCount().
func (h *Handler) GetUsersCount(context.Context) int64 {
	return h.validator.GetCount()
}

How is it useful for us? Well, since our goal is to implement custom users storage, there is no better place, than modifying existing Validator: we don't need to reinvent the wheel, we just need to rewrite storage interaction.

💾 Validator and in-memory storage

Let's take a look at /proxy/vless/validator.go and its Add, Del and Get methods:

// Add a VLESS user, Email must be empty or unique.
func (v *MemoryValidator) Add(u *protocol.MemoryUser) error {
	if u.Email != "" {
		_, loaded := v.email.LoadOrStore(strings.ToLower(u.Email), u)
		if loaded {
			return errors.New("User ", u.Email, " already exists.")
		}
	}
	v.users.Store(ProcessUUID(u.Account.(*MemoryAccount).ID.UUID()), u)
	return nil
}

// Del a VLESS user with a non-empty Email.
func (v *MemoryValidator) Del(e string) error {
	if e == "" {
		return errors.New("Email must not be empty.")
	}
	le := strings.ToLower(e)
	u, _ := v.email.Load(le)
	if u == nil {
		return errors.New("User ", e, " not found.")
	}
	v.email.Delete(le)
	v.users.Delete(ProcessUUID(u.(*protocol.MemoryUser).Account.(*MemoryAccount).ID.UUID()))
	return nil
}

// Get a VLESS user with UUID, nil if user doesn't exist.
func (v *MemoryValidator) Get(id uuid.UUID) *protocol.MemoryUser {
	u, _ := v.users.Load(ProcessUUID(id))
	if u != nil {
		return u.(*protocol.MemoryUser)
	}
	return nil
}

Since Xray-core exclusively implements only in-memory storage, everything in terms of users storage, basically narrows down to v.users and v.email usage, which are sync.Map:

// MemoryValidator stores valid VLESS users.
type MemoryValidator struct {
	// Considering email's usage here, map + sync.Mutex/RWMutex may have better performance.
	email sync.Map
	users sync.Map
}

Although, that statement is right only for VLESS and Trojan protocols, because VMess and ShadowSocks are using users list (slice) with sync.RWMutex for better performance.

proxy/vmess/validator.go:

type TimedUserValidator struct {
	sync.RWMutex
	users []*protocol.MemoryUser

	behaviorSeed  uint64
	behaviorFused bool

	aeadDecoderHolder *aead.AuthIDDecoderHolder
}

proxy/shadowsocks/validator.go:

type Validator struct {
	sync.RWMutex
	users []*protocol.MemoryUser

	behaviorSeed  uint64
	behaviorFused bool
}

Further notes will follow idea of implementing custom users storage, by creating sync.Map compatible solution, so we can just drag and drop it for protocols like VLESS and Trojan. It can also be used for any other protocol, but it will require little bit of changes in each Validator.

📦 Users storage implementation with Redis

📋 Preparation

Let's get to creation of users storage compatible with current sync.Map methods used in Xray-core. Redis was picked to build proof of concept, because it's simple and fast. However, you can use any database with binary data support.

First of all, we need to install go-redis:

go get github.com/redis/go-redis/v9

I'm not sure about suitable place for our storage module according to Xray-core structure, so we'll create it under common folder like this /common/storage/. Let's create /common/storage/storage.go with following contents:

package storage

type Storage interface {
	Load(key any) (any, bool)
	Store(key, value any)
	Delete(key any)
	LoadOrStore(key any, value any) (actual any, loaded bool)
	Range(f func(key, value any) bool)
}

This Storage interface is literally everything you need to implement. It doesn't include all of the sync.Map methods, but it includes all of the methods used across Validators in Xray-core.

We need to move in /proxy/vless/validator.go, swap sync.Map with our storage.Storage and create a new method called NewMemoryValidator (We will use it in injection later, because we can't inject directly in email and users fields, since they are private):

// MemoryValidator stores valid VLESS users.
type MemoryValidator struct {
	// Considering email's usage here, map + sync.Mutex/RWMutex may have better performance.
	email storage.Storage
	users storage.Storage
}

func NewMemoryValidator(email, users storage.Storage) *MemoryValidator {
	return &MemoryValidator{
		email: email,
		users: users,
	}
}

Also, create base for our RedisStorage in /common/storage/redis.go:

package storage

import (
	"context"
	"fmt"
	
	"github.com/redis/go-redis/v9"
)

type RedisStorage struct {
	rdb    *redis.Client
	prefix string
}

func NewRedisStorage(url string, prefix string) (*RedisStorage, error) {
	opts, err := redis.ParseURL(url)
	if err != nil {
		return nil, fmt.Errorf("failed to parse url: %v", err)
	}

	return &RedisStorage{
		rdb:    redis.NewClient(opts),
		prefix: prefix,
	}, nil
}

// Helper function, should be used for all queries
// E.g. s.rdb.Get(..., s.Key(key))
func (s *RedisStorage) Key(value any) string {
	switch v := value.(type) {
	case string:
		return s.prefix + ":" + v
	case []byte:
		return s.prefix + ":" + string(v)
	case [16]byte:
		u := uuid.UUID(v)
		return s.prefix + ":" + u.String()
	default:
		return s.prefix + ":" + fmt.Sprintf("%v", v)
	}
}

🛠️ Creating an entry point

Take a look at proxy/vless/inbound/inbound.go and find this block of code:

func init() {
	common.Must(common.RegisterConfig((*Config)(nil), func(ctx context.Context, config interface{}) (interface{}, error) {
		var dc dns.Client
		if err := core.RequireFeatures(ctx, func(d dns.Client) error {
			dc = d
			return nil
		}); err != nil {
			return nil, err
		}

		c := config.(*Config)

		validator := new(vless.MemoryValidator)
		for _, user := range c.Users {
			u, err := user.ToMemoryUser()
			if err != nil {
				return nil, errors.New("failed to get VLESS user").Base(err).AtError()
			}
			if err := validator.Add(u); err != nil {
				return nil, errors.New("failed to initiate user").Base(err).AtError()
			}
		}

		return New(ctx, c, dc, validator)
	}))
}

That's the entry point. We need to create two instances of RedisStorage, one for emails and one for users, we will use prefix to separate them. We also need to somehow pass connection string to our RedisStorage, I'll use environment variables for that.

In case you want absolute integration with Xray-core, like ability to configure with JSON, you should modify /infra/conf/ and read from config. Such things aren't covered in this document.

Also, don't forget to use NewMemoryValidator method. After all modifications, this code block should look like that:

func init() {
	common.Must(common.RegisterConfig((*Config)(nil), func(ctx context.Context, config interface{}) (interface{}, error) {
		var dc dns.Client
		if err := core.RequireFeatures(ctx, func(d dns.Client) error {
			dc = d
			return nil
		}); err != nil {
			return nil, err
		}

		c := config.(*Config)

		usersStorage, err := storage.NewRedisStorage(os.Getenv("REDIS_URL"), "users")
		if err != nil {
			panic(err)
		}

		emailStorage, err := storage.NewRedisStorage(os.Getenv("REDIS_URL"), "emails")
		if err != nil {
			panic(err)
		}

		validator := vless.NewMemoryValidator(emailStorage, usersStorage)
		for _, user := range c.Users {
			u, err := user.ToMemoryUser()
			if err != nil {
				return nil, errors.New("failed to get VLESS user").Base(err).AtError()
			}
			if err := validator.Add(u); err != nil {
				return nil, errors.New("failed to initiate user").Base(err).AtError()
			}
		}

		return New(ctx, c, dc, validator)
	}))
}

Different protocols and unrelated inbounds should always be separated. Implementation doesn't matter, you can use separate databases, tables, prefixes or any other form of identity, just keep this principle in mind.

👥 Storing and loading users

Remember I said we don't need to reinvent the wheel? In fact, we don't need to invent anything at all! Thanks to all previous developers, we have /common/protocol/user.go:

package protocol

import (
	"github.com/xtls/xray-core/common/errors"
	"github.com/xtls/xray-core/common/serial"
)

func (u *User) GetTypedAccount() (Account, error) {
	if u.GetAccount() == nil {
		return nil, errors.New("Account is missing").AtWarning()
	}

	rawAccount, err := u.Account.GetInstance()
	if err != nil {
		return nil, err
	}
	if asAccount, ok := rawAccount.(AsAccount); ok {
		return asAccount.AsAccount()
	}
	if account, ok := rawAccount.(Account); ok {
		return account, nil
	}
	return nil, errors.New("Unknown account type: ", u.Account.Type)
}

func (u *User) ToMemoryUser() (*MemoryUser, error) {
	account, err := u.GetTypedAccount()
	if err != nil {
		return nil, err
	}
	return &MemoryUser{
		Account: account,
		Email:   u.Email,
		Level:   u.Level,
	}, nil
}

func ToProtoUser(mu *MemoryUser) *User {
	if mu == nil {
		return nil
	}
	return &User{
		Account: serial.ToTypedMessage(mu.Account.ToProto()),
		Email:   mu.Email,
		Level:   mu.Level,
	}
}

// MemoryUser is a parsed form of User, to reduce number of parsing of Account proto.
type MemoryUser struct {
	// Account is the parsed account of the protocol.
	Account Account
	Email   string
	Level   uint32
}

We can easily make and absolutely should make use of Xray-core obsession with Protocol Buffers. This code may not mean much to you, but take a look at ToProtouser method:

func ToProtoUser(mu *MemoryUser) *User {
	if mu == nil {
		return nil
	}
	return &User{
		Account: serial.ToTypedMessage(mu.Account.ToProto()),
		Email:   mu.Email,
		Level:   mu.Level,
	}
}

For a long time, my biggest problem with this project was user serialization and deserialization. I was trying to make use of JSON format, but Account was always getting in my way, because it is unique for each protocol. Which means, you need to know, which exact protocol stores and asks storage module for data. This required me to make some crazy amount of abstractions for each Validator. And then I found out about Protocol Buffers and their implementation in Xray-core.

ToProtoUser function serializes Account to a TypedMessage, meaning it carries not only a Value, but also a Type. Thanks to Protocol Buffers, all of the existing types are globally registered in Xray-core, meaning Account deserialized from TypedMessage is automatically comes with right Type. You serialized vless.Account, you will get vless.Account back on deserialization, it's simple as it is!

Marshaling and unmarshaling Protocol Buffers is also pretty simple, there is no difference with JSON at all:

// Turn User into bytes
bytes, err := proto.Marshal(protocol.ToProtoUser(value.(*protocol.MemoryUser)))
if err != nil {
	return
}

// Read user from bytes
user := &protocol.User{}
if err := proto.Unmarshal(bytes, user); err != nil {
	return nil, false
}

// We need to convert user to MemoryUser, because that's what validator expects
mUser, err := user.ToMemoryUser()
if err != nil {
	return nil, false
}

Now, you know basically everything and I'm ready to show you final implementation of RedisStorage in /common/storage/redis.go:

package storage

import (
	"context"
	"fmt"
	"strings"

	"github.com/redis/go-redis/v9"
	"github.com/xtls/xray-core/common/protocol"
	"github.com/xtls/xray-core/common/uuid"
	"google.golang.org/protobuf/proto"
)

type RedisStorage struct {
	rdb    *redis.Client
	prefix string
}

func NewRedisStorage(url string, prefix string) (*RedisStorage, error) {
	opts, err := redis.ParseURL(url)
	if err != nil {
		return nil, fmt.Errorf("failed to parse url: %v", err)
	}

	return &RedisStorage{
		rdb:    redis.NewClient(opts),
		prefix: prefix,
	}, nil
}

// Helper function, should be used for all queries
// E.g. s.rdb.Get(..., s.Key(key))
func (s *RedisStorage) Key(value any) string {
	switch v := value.(type) {
	case string:
		return s.prefix + ":" + v
	case []byte:
		return s.prefix + ":" + string(v)
	case [16]byte:
		u := uuid.UUID(v)
		return s.prefix + ":" + u.String()
	default:
		return s.prefix + ":" + fmt.Sprintf("%v", v)
	}
}

func (s *RedisStorage) Store(key, value any) {
	bytes, err := proto.Marshal(protocol.ToProtoUser(value.(*protocol.MemoryUser)))
	if err != nil {
		return
	}

	s.rdb.Set(context.Background(), s.Key(key), bytes, 0)
}

func (s *RedisStorage) Load(key any) (any, bool) {
	bytes, err := s.rdb.Get(context.Background(), s.Key(key)).Bytes()
	if err != nil {
		return nil, false
	}

	user := &protocol.User{}
	if err := proto.Unmarshal(bytes, user); err != nil {
		return nil, false
	}

	mUser, err := user.ToMemoryUser()
	if err != nil {
		return nil, false
	}

	return mUser, true
}

func (s *RedisStorage) Delete(key any) {
	s.rdb.Del(context.Background(), s.Key(key))
}

func (s *RedisStorage) LoadOrStore(key any, value any) (actual any, loaded bool) {
	existing, ok := s.Load(key)
	if ok {
		return existing, true
	}

	s.Store(key, value)

	return value, false
}

// This thing exists just for example, it is really ineffective,
// Don't even think about using it in production
func (s *RedisStorage) Range(f func(key, value any) bool) {
	ctx := context.Background()

	keys, err := s.rdb.Keys(ctx, s.prefix+":*").Result()
	if err != nil {
		return
	}

	for _, fullKey := range keys {
		key := strings.TrimPrefix(fullKey, s.prefix+":")

		val, ok := s.Load(key)
		if !ok {
			continue
		}

		if !f(key, val) {
			return
		}
	}
}

🧪 Let's do some tests

Binaries were built against source code provided above with simple docker-compose.yml running along:

services:
  redis:
    image: redis:latest
    restart: always
    ports:
      - "6379:6379"

Two configurations were created in order to test our users storage and its ability to share users across multiple instances of Xray-core. One instance had a client to add to Validator with our storage and another one, was completely empty.

config.json:

{
    "log": {
        "loglevel": "info"
    },
    "inbounds": [
        {
            "listen": "0.0.0.0",
            "port": 1234,
            "protocol": "vless",
            "settings": {
                "clients": [
                    {
                        "id": "02276781-1fc8-4666-b111-78e7a348b936",
                        "level": 0,
                        "email": "love@example.com"
                    }
                ],
                "decryption": "none"
            },
            "streamSettings": {
                "network": "tcp"
            }
        }
    ],
    "outbounds": [
        {
            "protocol": "freedom",
            "tag": "direct"
        }
    ]
}

config2.json:

{
    "log": {
        "loglevel": "info"
    },
    "inbounds": [
        {
            "listen": "0.0.0.0",
            "port": 12345,
            "protocol": "vless",
            "settings": {
                "decryption": "none"
            },
            "streamSettings": {
                "network": "tcp"
            }
        }
    ],
    "outbounds": [
        {
            "protocol": "freedom",
            "tag": "direct"
        }
    ]
}

Here are logs from launch of first instance (IPs are censored intentionally):

[thearialume@cachyos Xray-core]$ REDIS_URL="redis://localhost:6379/0" ./xray -c config.json
Xray 26.6.1 (Xray, Penetrates Everything.) Custom (go1.26.4-X:nodwarf5 linux/amd64)
A unified platform for anti-censorship.
2026/06/18 02:34:39.531790 [Info] infra/conf/serial: Reading config: &{Name:config.json Format:json}
2026/06/18 02:34:40.221078 [Info] transport/internet/tcp: listening TCP on 0.0.0.0:1234
2026/06/18 02:34:40.221247 [Warning] core: Xray 26.6.1 started
2026/06/18 02:43:33.888537 [Info] [1163906622] proxy/vless/inbound: firstLen = 138
2026/06/18 02:43:33.888962 [Info] [1163906622] proxy/vless/inbound: received request for tcp:cp.cloudflare.com:80
2026/06/18 02:43:33.889036 [Info] [1163906622] app/dispatcher: default route for tcp:cp.cloudflare.com:80
2026/06/18 02:43:33.889127 from 127.0.0.1:54552 accepted tcp:cp.cloudflare.com:80 [direct] email: love@example.com
2026/06/18 02:43:33.999521 [Info] [1163906622] proxy/freedom: dialing to tcp:104.16.132.229:80
2026/06/18 02:43:33.999590 [Info] [1163906622] transport/internet/tcp: dialing TCP to tcp:104.16.132.229:80
2026/06/18 02:43:34.048409 [Info] [1163906622] proxy/freedom: connection opened to tcp:cp.cloudflare.com:80, local endpoint ***.***.***.***:35700, remote endpoint ***.***.***.***:80

And here are logs from launch of second instance at the same time:

[thearialume@cachyos Xray-core]$ REDIS_URL="redis://localhost:6379/0" ./xray -c config2.json
Xray 26.6.1 (Xray, Penetrates Everything.) Custom (go1.26.4-X:nodwarf5 linux/amd64)
A unified platform for anti-censorship.
2026/06/18 02:34:53.304109 [Info] infra/conf/serial: Reading config: &{Name:config2.json Format:json}
2026/06/18 02:34:53.306777 [Info] transport/internet/tcp: listening TCP on 0.0.0.0:12345
2026/06/18 02:34:53.306830 [Warning] core: Xray 26.6.1 started
2026/06/18 02:34:58.547737 [Info] [100929031] proxy/vless/inbound: firstLen = 138
2026/06/18 02:34:58.890355 [Info] [100929031] proxy/vless/inbound: received request for tcp:cp.cloudflare.com:80
2026/06/18 02:34:58.890387 [Info] [100929031] app/dispatcher: default route for tcp:cp.cloudflare.com:80
2026/06/18 02:34:58.890454 from 127.0.0.1:45904 accepted tcp:cp.cloudflare.com:80 [direct] email: love@example.com
2026/06/18 02:34:58.997766 [Info] [100929031] proxy/freedom: dialing to tcp:104.16.133.229:80
2026/06/18 02:34:58.997790 [Info] [100929031] transport/internet/tcp: dialing TCP to tcp:104.16.133.229:80
2026/06/18 02:34:59.045595 [Info] [100929031] proxy/freedom: connection opened to tcp:cp.cloudflare.com:80, local endpoint ***.***.***.***:59102, remote endpoint ***.***.***.***:80

Exactly, everything works just as expected! While not having any clients, second instance successfully loaded our user from Redis users storage, which was added there by the first one.

Remember I told you, it will be completely compatible with existing functionality? Well, as far as I tested, it's absolutely is:

[thearialume@cachyos Xray-core]$ ./xray api stats -name "user>>>love@example.com>>>traffic>>>uplink"
{
    "stat": {
        "name": "user>>>love@example.com>>>traffic>>>uplink",
        "value": 523468
    }
}

[thearialume@cachyos Xray-core]$ ./xray api stats -name "user>>>love@example.com>>>traffic>>>downlink"
{
    "stat": {
        "name": "user>>>love@example.com>>>traffic>>>downlink",
        "value": 1222479
    }
}

[thearialume@cachyos Xray-core]$ ./xray api inbounduser -tag=VLESS
{
    "users": [
        {
            "account": {
                "_TypedMessage_": "xray.proxy.vless.Account",
                "id": "02276781-1fc8-4666-b111-78e7a348b936"
            },
            "email": "love@example.com"
        }
    ]
}

💡 What's next?

Use it however you want! You can easily integrate such solution with any existing backend of your own, using Xray-core gRPC API or implement your own way of adding users directly to database, it's not that hard either!

Thanks for reading and hope this helps someone! I would be really happy, if users storages support will be added to Xray-core at some point!

Feel free to ask questions here or even message me, I'm always glad to help!