Marzban on VPS: Installing Xray Panel and Multi-user

For effective management of dozens of Xray users on a Virtual Private Server (VPS), the optimal solution is to use the Marzban panel. It provides an intuitive interface for deploying, configuring, and monitoring the Xray server, as well as convenient creation of multi-user subscriptions with various protocols, including VLESS Reality.

What is Marzban and why is it ideal for managing Xray on a VPS?

Marzban is a powerful and flexible control panel for the Xray proxy server, designed to simplify the administration of multi-user VPN/proxy services. It allows centralized management of users, protocols, traffic, and subscriptions, significantly reducing the complexity of manual Xray configuration. If you plan to provide Xray access not only to yourself but also to friends, family, or even a small community, the Marzban panel becomes an indispensable tool that automates routine tasks and provides convenient control over the entire system.

Advantages of Marzban for multi-user systems

The main advantage of Marzban lies in its ability to scale Xray management. Instead of manually editing configuration files for each new user or limit change, Marzban provides a web interface where all operations are performed in a few clicks. This is critically important for those managing dozens of users. The panel supports numerous Xray protocols, including VLESS, VMess, Trojan, ShadowSocks, as well as advanced obfuscation technologies like Reality, making it a universal tool for ensuring secure and stable network access.

With Marzban, you can:

• Create an unlimited number of users with individual settings.
• Set traffic and time limits for each user.
• Generate unique subscription links for various clients (V2RayNG, Nekobox, Streisand, etc.).
• Monitor real-time traffic usage.
• Easily update Xray and the Marzban panel itself.
• Configure HTTPS for the control panel and Xray server.

Key features of the Marzban panel

The Marzban panel offers a wide range of features that make it one of the best in its class for Marzban VPS deployments:

• Easy Installation: Marzban deployment is done via Docker, which significantly simplifies the process and minimizes dependency conflicts.
• Multi-protocol Support: Full compatibility with various Xray protocols, including VLESS Reality, which provides high performance and resistance to blocking.
• Multi-user Management: Ability to create and manage dozens or even hundreds of users with individual parameters.
• Subscription System: Automatic generation of subscription links that clients can use to get up-to-date configurations.
• Monitoring and Statistics: Detailed traffic statistics for each user, allowing for efficient resource management.
• Let's Encrypt Integration: Automatic acquisition and renewal of SSL certificates for your domain.
• API: Ability to automate management via API for integration with other systems.

Thanks to these capabilities, Marzban on a VPS becomes an ideal solution for those looking for a reliable and convenient way to deploy and manage their own proxy server.

Choosing the optimal VPS for Marzban: requirements and recommendations

Choosing the right VPS is a key step for stable and productive operation of Marzban and Xray. While Marzban itself doesn't require huge resources, Xray, especially with a large number of active users and intense traffic, can be quite resource-intensive. When choosing a Marzban VPS, several factors must be considered: processor, RAM, disk space, network channel, and, of course, server location.

Minimum and recommended system requirements

For running Marzban with several dozen Xray users and stable VLESS Reality operation, the following characteristics are recommended:

• Operating System: Ubuntu 20.04/22.04 LTS, Debian 11/12, or CentOS 7/8. Ubuntu LTS is the most commonly used and well-supported OS for such tasks.
• Processor (CPU): Minimum 1 vCPU with a frequency of 2.0 GHz. For 20-50 active users, 2 vCPUs are better. If more than 50-100 users are planned, 4 vCPUs will ensure stable operation.
• Random Access Memory (RAM): Minimum 1 GB. This is sufficient for a basic Marzban installation and a few users. For comfortable operation with dozens of users and intense traffic, 2 GB RAM is recommended. For active use of resource-intensive protocols (e.g., Hysteria2 or OpenVPN in conjunction with Xray), 4 GB RAM will be the optimal choice.
• Disk Space: Minimum 10-20 GB NVMe SSD. NVMe drives are significantly faster than traditional HDDs or SATA SSDs, which is critical for Marzban database operations and fast Xray configuration processing. 20 GB will be more than enough for the system, Marzban, Docker, and logs.
• Network Channel: Minimum 100 Mbps. For stable operation and high throughput, a 1 Gbps port is recommended.
• IP Address: A clean IPv4 address without blocks. It is desirable that the IP has not been previously involved in spam or other undesirable activities.

What to look for when choosing a hosting provider

When choosing a hosting provider for your Marzban VPS, in addition to technical specifications, pay attention to the following aspects:

• Geographical Location: Choose a server that is as close as possible to your end-users to minimize latency (ping). Valebyte.com offers VPS in various data centers worldwide.
• Reliability and Uptime: Ensure that the provider guarantees high uptime (usually 99.9%).
• Support: Availability of qualified and fast technical support, ready to help in case of problems.
• Scalability: The ability to easily upgrade VPS resources as needs grow.
• Payment Methods: Valebyte.com offers flexible payment methods, including cryptocurrency payment, which is convenient for many users.
• Price: Compare prices from different providers. Sometimes you can find a cheap VPS with hourly billing, which is convenient for testing or temporary needs.

For example, here is a table with typical VPS plans suitable for Marzban:

VPS Plan	vCPU	RAM	Disk (NVMe SSD)	Network Channel	Approx. Cost/month	Recommendation
Basic	1 core	1 GB	20 GB	100 Mbps	from $5	For personal use or up to 10 users
Standard	2 cores	2 GB	40 GB	1 Gbps	from $10	For 10-50 users, good performance
Advanced	4 cores	4 GB	80 GB	1 Gbps	from $20	For 50+ users, high load, multiple protocols

When choosing a plan, always base it on the anticipated load. It's better to have a little extra capacity than to face resource shortages at the most inconvenient time.

Marzban Installation: A Step-by-Step Guide via Docker

Installing Marzban on a VPS is made incredibly simple thanks to Docker. This method ensures that all dependencies are correctly installed and isolated, minimizing potential conflicts with other applications on your server. The Marzban installation process includes preparing the VPS, installing Docker and Docker Compose, and then deploying the panel itself.

Preparing the VPS for Installation

Before starting the installation, ensure that your VPS meets the minimum requirements and has a fresh operating system installation. For example, we will use Ubuntu 22.04 LTS.

1. System Update: Always start by updating the package database and installed packages.

sudo apt update && sudo apt upgrade -y

2. Install Necessary Utilities: Install curl and git if they are not already installed.

sudo apt install curl git -y

3. Open Firewall Ports (UFW): If you are using UFW, ensure that the necessary ports are open. For Marzban and Xray, ports 80 (HTTP), 443 (HTTPS), and the Marzban panel port (default 8000) will be required.

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 8000/tcp
sudo ufw enable
sudo ufw status

If you are using a different firewall (e.g., firewalld on CentOS), configure it similarly.

Installing Docker and Docker Compose

Marzban runs as a set of Docker containers, so Docker and Docker Compose are essential components.

1. Install Docker Engine: Use the official script to install Docker.

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

2. Add User to Docker Group (optional, for working without sudo):

sudo usermod -aG docker $USER
newgrp docker

3. Install Docker Compose: Docker Compose allows you to manage multi-container Docker applications.

sudo apt install docker-compose -y

Or, if you have a newer Docker version, Docker Compose might already be built-in (docker compose without a hyphen).

Check versions:

docker --version
docker compose version

Deploying Marzban on a VPS

Now that Docker and Docker Compose are installed, you can proceed with deploying Marzban.

1. Clone the Marzban Repository: Navigate to your home directory or any other convenient location and clone the Marzban repository.

cd ~
git clone https://github.com/Gozargah/Marzban-scripts.git
cd Marzban-scripts

2. Run Marzban Installation: Use the installation script.

sudo ./install.sh

The script will ask a few questions:

• Enter a domain for Marzban panel (e.g., panel.example.com): Enter the domain name you will use to access the Marzban panel (e.g., panel.valebyte.com). Make sure the A-record for this domain points to your VPS's IP address.
• Enter a username for Marzban panel (default: admin): Enter the desired username for the panel.
• Enter a password for Marzban panel: Enter a strong password.
• Do you want to enable HTTPS for Marzban panel? (y/N): Enter y to enable HTTPS. This is highly recommended for security.

After entering the data, the script will automatically download Docker images, configure Nginx (if you enabled HTTPS), and start the containers. The process may take several minutes.

3. Check Marzban Status: After the installation is complete, you can check the status of the containers.

sudo docker compose -f docker-compose.yml -f docker-compose.override.yml ps

All containers (marzban, xray, nginx, caddy, db) should be in the "Up" state.

Your Marzban installation is complete! Now you can proceed to the initial setup.

Initial Marzban Setup: Domain, HTTPS, and Control Panel

After a successful Marzban installation, the next step is to access the web panel and perform its initial configuration. This includes ensuring secure access to the panel via HTTPS and binding a domain, if you haven't done so during installation.

Domain Binding and SSL Certificate Acquisition (Let's Encrypt)

If you already specified a domain name and selected HTTPS during installation, Marzban will automatically configure Nginx and obtain an SSL certificate from Let's Encrypt. If you skipped this step or want to change the domain, you will need to make changes manually.

1. DNS Configuration: Ensure that your domain's A-record (e.g., panel.yourdomain.com) points to your VPS's public IP address. This is critically important for obtaining an SSL certificate.
2. Modifying Marzban Configuration (if required): If you want to change the domain or enable HTTPS after installation, you need to edit the .env file in the Marzban-scripts directory.

cd ~/Marzban-scripts
nano .env

Find the lines responsible for the domain and HTTPS:

# Domain for Marzban panel
PANEL_DOMAIN=panel.yourdomain.com

# Enable HTTPS for Marzban panel
HTTPS_ENABLED=true

Change PANEL_DOMAIN to your new domain and ensure that HTTPS_ENABLED is set to true. Save the changes (Ctrl+O, Enter, Ctrl+X).

3. Restart Marzban to Apply Changes:

sudo ./install.sh --update

Use the --update command so that the script reconfigures Nginx and attempts to obtain a new SSL certificate.

4. Verify SSL Certificate: After restarting, navigate to https://panel.yourdomain.com in your browser. You should see a secure connection (a padlock icon in the address bar).

If you encounter issues obtaining the certificate, ensure that ports 80 and 443 are open on your firewall and that DNS records are correctly configured. Also, check Nginx or Caddy logs (depending on your configuration) for more information.

Accessing the Marzban Web Panel

After successfully configuring the domain and HTTPS, you can access the Marzban panel via a web browser.

1. Open the URL: Enter https://panel.yourdomain.com (replace with your domain) in your browser's address bar.
2. Log in: Use the username and password you set during installation. By default, this is admin and your chosen password.
3. Explore the Interface: After logging in, you will see the Marzban dashboard, which displays overall statistics, active users, and other information.

Now you are ready to create your first inbounds and users for the Marzban Xray server.

Configuring Inbounds in Marzban: VLESS Reality for Bypassing Blocks

One of Marzban's key features is the ability to easily configure inbounds for Xray. Marzban Xray supports numerous protocols, but VLESS Reality is of particular interest — an advanced obfuscation technology designed for effectively bypassing Deep Packet Inspection (DPI) and blocks. Reality masks Xray traffic as regular HTTPS traffic directed to real, popular domains, making it virtually indistinguishable from legitimate web traffic.

Creating an Xray Inbound with VLESS Reality

To create an inbound with VLESS Reality in Marzban, follow these steps:

1. Go to "Inbounds" Section: In the left menu of the Marzban panel, select "Inbounds".
2. Click "Add Inbound": Click the button to add a new inbound connection.
3. Configure Reality Parameters:
   • Port: Choose a free port (e.g., 443, if not occupied by Nginx for the panel). If 443 is busy, another port can be used, but 443 is preferred for better obfuscation.
   • Protocol: Select "VLESS".
   • Stream Network: Select "tcp".
   • Security: Select "reality".
   • Dest: This is the IP address or domain of a real website under which your traffic will be masked. Choose a popular site, for example, www.google.com:443 or www.microsoft.com:443.
   • SNI: Server Name Indication. This is the domain that will appear in the TLS handshake. It should match the domain specified in Dest, or be another popular domain. For example, www.apple.com.
   • Short ID: Generate a unique Short ID (you can click the "Generate" button). This is a short identifier for the Reality session.
   • Private Key / Public Key: Marzban will automatically generate a key pair. You do not need to change them unless you are creating multiple Reality servers with the same Dest.
   • Server Names (Optional): You can specify multiple SNIs for additional obfuscation.
4. Save Inbound: Click "Add" or "Save" to create the inbound.

Generating and Managing Keys (dest, sni, shortId)

In the context of Reality, dest, sni, and shortId are critically important parameters for successful obfuscation. Marzban simplifies their management:

• Dest (Destination): This is the address of a real server to which traffic appears to be directed. Choosing a reliable and popular Dest reduces the likelihood of detection. Marzban allows easy modification of this parameter.
• SNI (Server Name Indication): This is the hostname that the client sends to the server when establishing a TLS connection. It should match Dest or be close to it to make the traffic appear natural.
• Short ID: A unique identifier that allows the Reality server to distinguish legitimate requests from simulated ones. Marzban automatically generates it, but you can change it to your own if necessary.

It is important to remember that these parameters must be consistent between the server and the client. Marzban automatically generates subscription links that include all necessary data for the client.

Detailed information on configuring VLESS Reality, as well as other protocols like Sing-Box, can be found in our article Sing-Box on VPS: A Universal Server for VLESS, Reality, and Hysteria, which will help you gain a deeper understanding of how these technologies work.

Adding Other Protocols (VMess, Trojan)

In addition to VLESS Reality, the Marzban panel allows you to easily add inbounds for other popular Xray protocols:

• VMess: One of the oldest and most common Xray protocols. Can be configured with various transport protocols (TCP, WS, HTTP/2, gRPC).
• Trojan: A protocol designed to masquerade as HTTPS. Effective, but less resistant to DPI than Reality.
• Shadowsocks: A lightweight proxy protocol, simple to configure, but less resistant to blocking.

The process of adding them is similar to VLESS Reality: select the protocol, configure the port and transport, and Marzban will take care of the rest. For better block circumvention, VLESS Reality is always recommended, but having other protocols can be useful for compatibility with various clients or for backup purposes.

Managing Users and Subscriptions in Marzban

A central function of the Marzban panel is managing users and their subscriptions. This allows you to provide access to your Marzban Xray server to multiple people, controlling their traffic consumption and usage time. Effective user management is key to stable operation and preventing abuse.

Creating and Configuring Users

Creating a new user in Marzban is intuitive:

1. Go to "Users" Section: In the left menu of the Marzban panel, select "Users".
2. Click "Add User": Click the button to add a new user.
3. Fill in User Details:
   • Username: A unique username (e.g., john_doe).
   • Password: Password for logging into the panel, if you are granting management access. For regular proxy users, a password is not needed.
   • Inbounds: Select the inbounds this user will have access to. This is usually one or more inbounds you have configured (e.g., VLESS Reality).
   • Data Limit: Set a traffic limit for the user (e.g., 100 GB). You can choose "Unlimited".
   • Expire Date: Set the account's expiration date (e.g., in 30 days). You can choose "Never".
   • Status: Set to "Active" to enable the account.
4. Save User: Click "Add" or "Save".

After creating a user, they will appear in the list. You can edit their parameters, suspend, or delete the account at any time.

Generating Subscription Links and QR Codes

Marzban automatically generates subscription links for each user. This is very convenient, as the client only needs to copy one link into their application (e.g., V2RayNG, Nekobox, Shadowrocket, Streisand), and all available configurations will be automatically imported.

1. Find the User: In the "Users" section, locate the desired user.
2. Get the Link: Next to the username, you will see a "Copy Subscription URL" icon (usually a chain icon) and "Show QR Code".
3. Copy or Show QR Code:
   • Click "Copy Subscription URL" to copy the link to the clipboard.
   • Click "Show QR Code" to display a QR code that the user can scan with their mobile device.

Subscription links contain all the necessary data to connect to all inbounds the user has access to. This significantly simplifies the setup process for end-users, especially when using VLESS Reality, where manual configuration can be complex.

Traffic Monitoring and Limit Management

Marzban provides convenient tools for monitoring each user's traffic usage:

• Dashboard: On the main page of the Marzban panel, you will see overall statistics on traffic usage, the number of active users, and server status.
• User List: In the "Users" section, each user's current traffic consumption, remaining limit, and status are displayed.
• Notifications: You can configure notifications for exceeding traffic limits or account expiration.

If a user exceeds their traffic limit or their account expires, Marzban will automatically block their Xray access until you extend the limit or expiration date. This allows for efficient management of your Marzban VPS resources and prevents server overload.

For those interested in other block circumvention protocols, such as Hysteria2, we recommend checking out our article Hysteria2 on VPS: Installation and Configuration for DPI Bypass in 2026, which may be useful as an additional or backup solution.

Marzban Maintenance: Backup, Updates, and Security

Maintaining Marzban in an up-to-date and secure state is an ongoing process. Regular data backups, timely updates of the panel and Xray, and adherence to basic security principles will help ensure the stable and reliable operation of your Marzban VPS.

Regular Marzban Data Backup

Marzban data, including user information, their limits, inbound configurations, and traffic statistics, is stored in a database. Loss of this data can lead to significant problems, so regular backups are mandatory.

Marzban provides a convenient script for backup:

1. Navigate to the Marzban-scripts directory:

cd ~/Marzban-scripts

2. Execute the backup command:

sudo ./marzban.sh backup

This command will create an archive with the Marzban database and configuration files. The backup file will be located in the backup directory inside Marzban-scripts (e.g., ~/Marzban-scripts/backup/marzban_backup_YYYYMMDD_HHMMSS.zip).

3. Move the backup to a safe location: It is crucial to store backups not on the same VPS where Marzban is installed. Use SCP, SFTP, or cloud storage to move the backup to a remote server or your local computer.

# Example of copying to a local computer via SCP
scp user@your_vps_ip:~/Marzban-scripts/backup/marzban_backup_*.zip ~/local_backups/

To restore from a backup, use the command sudo ./marzban.sh restore /path/to/your/backup.zip. Always perform a backup before any major changes or updates.

Marzban and Docker Update Process

Updating Marzban allows you to get new features, bug fixes, and security improvements. Updating Docker is also important for stability and performance.

1. Update Marzban:
   • First, update the VPS system itself:

   sudo apt update && sudo apt upgrade -y

   • Then, navigate to the Marzban-scripts directory and execute the update command:

   cd ~/Marzban-scripts
   sudo ./install.sh --update

   This script will update the Marzban Docker images to the latest versions and restart the containers.

2. Update Docker Engine:
   • Docker is usually updated along with system packages if you installed it via OS repositories.
   • If you used the get-docker.sh script, you can rerun it to update, or follow the instructions on the official Docker website.

Always check Marzban's official channels (GitHub repository) for important announcements regarding updates or process changes.

Fundamentals of Securing Your Marzban Server

The security of your Marzban VPS is a priority, especially when you are managing access for other users.

• Use Strong Passwords: For Marzban panel and SSH access.
• Configure SSH Keys: Disable password login for SSH and use key-based authentication.
• Firewall (UFW/firewalld): Open only necessary ports (22 for SSH, 80/443 for web server and Xray, 8000 for Marzban panel if Nginx is not used).
• Regular Updates: Both for Marzban and the operating system.
• Monitor Logs: Periodically review Marzban and Xray logs for suspicious activity.
• Disable Unnecessary Services: Minimize the number of running services on the VPS to reduce the attack surface.
• Use HTTPS: Always enable HTTPS for the Marzban panel.

Adherence to these simple rules will significantly enhance the security of your Marzban server and protect your users' data.

Conclusion

Marzban on a VPS offers an efficient and convenient solution for organizing multi-user access to Xray, especially with the VLESS Reality protocol, which provides a high level of obfuscation and resistance to blocking. For stable operation, VPS with 2-4 vCPUs, 2-4 GB RAM, and an NVMe disk are recommended, and its installation via Docker allows for quick system deployment and management of users and subscriptions. Regular backups and updates are key to maintaining the security and reliability of your Marzban server.