Marzban: a Xray proxy panel with a web UI, REST API and multi-node support

What Marzban is for, and who ends up running it

Marzban is a management layer, not a proxy protocol. It sits in front of Xray-core and turns the job of maintaining proxy accounts into a web form: create a user, pick a protocol, set a traffic quota and an expiry date, hand over a subscription link. The README describes it as a proxy management tool that provides a simple and easy-to-use user interface for managing hundreds of proxy accounts, built with Python and React. The name is the Persian word for border guard, pronounced /mærz'ban/.

The audience is narrow and fairly technical. You need a server, a domain, and enough understanding of inbounds and Xray configuration to know what you are exposing. The panel then serves the people you hand accounts to: it supports Vmess, VLESS, Trojan and Shadowsocks, allows multiple protocols for one user, multiple users on one inbound, and multiple inbounds on a single port through fallbacks. Subscription output is generated for V2Ray clients, Clash and ClashMeta, alongside share links and QR codes.

If you are looking for something to install on your phone and switch on, this is the wrong project. Marzban is the server side of that arrangement, and someone has to operate it.

How the panel, Xray and the nodes fit together

The architecture visible in the repository is a FastAPI backend, a React dashboard served by the same process, and Xray running alongside it. The Dockerfile installs Xray during the build and copies /usr/local/share/xray into the final image; the application talks to Xray, and the environment file exposes the paths it uses, including XRAY_JSON, XRAY_EXECUTABLE_PATH and XRAY_ASSETS_PATH. Configuration therefore lives in two places at once: Marzban's own .env, and the Xray JSON that defines inbounds.

State lives in a relational database. The README gives install commands for SQLite, MySQL and MariaDB, and requirements.txt pins SQLAlchemy 2.0.36 with alembic 1.14.0 for migrations. The Docker image runs alembic upgrade head before python main.py, so schema changes are applied on container start. User records, traffic counters and expiry dates are stored there, which is why the README has a dedicated backup section.

Multi-node support is the part that changes the deployment shape. Marzban Node is a separate component that lets you distribute infrastructure, and requirements.txt includes rpyc 6.0.0 and grpcio, which is consistent with a remote procedure call channel between panel and nodes. The panel stays the control plane; the nodes carry the proxy traffic. That is a real operational difference from a single-box panel, and it is also where most of the setup complexity lives.

Installing Marzban with the script and creating the first admin

The README's primary path is an install script, not a package manager. The command below installs Marzban with SQLite, which is the default database choice. It must run as root, and it fetches the script from the Marzban-scripts repository.

sudo bash -c "$(curl -sL https://github.com/Gozargah/Marzban-scripts/raw/master/marzban.sh)" @ install

MySQL and MariaDB are selected with a flag on the same command. The README shows both, and they are the only alternatives it documents.

sudo bash -c "$(curl -sL https://github.com/Gozargah/Marzban-scripts/raw/master/marzban.sh)" @ install --database mysql

After the script finishes, the README states that files land in /opt/marzban, the configuration file is /opt/marzban/.env, and data goes to /var/lib/marzban. The installer prints logs that you can stop watching with Ctrl+C.

The dashboard is not reachable by IP address. The README is explicit about this and points to a guide for issuing an SSL certificate, after which you open https://YOUR_DOMAIN:8000/dashboard/. For a quick look without a domain, the README offers SSH port forwarding, with the warning that access disappears when the terminal closes and that the method is recommended only for testing.

ssh -L 8000:localhost:8000 user@serverip

With the tunnel open, http://localhost:8000/dashboard/ serves the panel. You still need an admin account before you can log in, and the README recommends creating it through the CLI rather than the commented SUDO_USERNAME and SUDO_PASSWORD variables in .env.example.

marzban cli admin create --sudo

The CLI has its own help output, reachable with marzban --help. A manual source install is documented as an advanced alternative: install Xray, clone the repository, install requirements.txt with Python 3.8 or newer, then run alembic upgrade head before starting.

Where Marzban gets awkward: TLS, host networking and the missing rollback story

The first real obstacle is the domain requirement. Because the dashboard refuses IP access, you cannot evaluate Marzban on a throwaway VPS in two minutes. You need a certificate first, and the README treats that as a prerequisite rather than an optional hardening step. If you cannot point a domain at the host, your only documented route is the SSH tunnel, which the README itself scopes to testing.

The shipped docker-compose.yml uses network_mode: host and mounts /var/lib/marzban. Host networking means the panel does not get an isolated network namespace, and port conflicts with anything else on the machine are yours to resolve. It also means the compose file is not a template you can scale horizontally by adding replicas; distribution is handled by Marzban Node instead, which is a different mechanism with its own documentation.

Upgrades are the other soft spot. The README documents installation, configuration, backup and the CLI, but it does not document a rollback procedure. The Docker image applies alembic migrations on every start, and the README's backup section exists, so the practical position is that you take a database backup before changing versions and you treat the migration as one-way. That is a normal posture for a panel like this, but it should be a deliberate decision rather than a surprise.

Finally, multi-admin support is listed in the feature list with the marker WIP. If you need several operators with separate access, check the current state of that feature before designing your workflow around it.

Marzban compared with 3x-ui and Hiddify

The comparison people actually search for is Marzban against 3x-ui and Hiddify, and the difference is mostly about where configuration lives. Marzban keeps a database as the source of truth for users, quotas and expiry, with the panel and API writing to it, and Xray configuration supplied separately through XRAY_JSON. 3x-ui is built around managing Xray inbounds directly in its interface; if your mental model is inbounds first and users second, that mapping is more direct, while Marzban's model is users first with inbounds as the substrate.

Hiddify sits at a different level. It targets a broader end-user and multi-protocol experience, whereas Marzban's stated scope is proxy account management with a REST API, a CLI and a Telegram bot as the automation surfaces. If your requirement is a programmatic control plane that another system drives, Marzban's fully REST API backend is the reason to choose it. If your requirement is a friendlier out-of-the-box experience for non-technical operators, that is not what Marzban's feature list is optimizing for.

None of these three is a client. All of them assume you are the server operator, and the choice between them comes down to whether you want to manage users through an API and a database, or manage inbounds through a UI.

Licence, upgrade cost and what maintenance looks like

Marzban is licensed under AGPL-3.0. The practical consequence for a network-facing service is the network clause: if you modify the program and let users interact with it over a network, the licence's obligations attach to that deployment. Running an unmodified copy as a service is not the same situation as shipping a modified fork. This is a description of the licence identifier, not legal advice; read the LICENSE file in the repository and get proper advice if you plan to modify and redistribute.

The upgrade cost is mostly migration risk plus a container restart. The image runs alembic upgrade head on start, dependencies are pinned exactly in requirements.txt, and the base image is python:3.12-slim. Pinning cuts both ways: you get reproducible builds, and you inherit the job of moving those pins when something upstream needs a security fix. The last push to the repository was on 2026-06-08, and the most recent tagged release is v0.8.4 from 2025-01-09. The gap between the last release and the last commit is worth noting if you depend on tagged versions rather than the master branch.

The repository is not archived. It is also not something the README describes as having a stable release cadence, so pinning an image tag and reading the release notes before each move is the defensible approach.

Editorial conclusion

Adopt Marzban if you already understand Xray inbounds and want a single panel to hand out accounts, enforce traffic and expiry limits, and split load over several nodes. Skip it if you want a client app or a one-command tunnel for a single person, or if you cannot get a TLS certificate and a domain, because the README states the dashboard is not reachable by IP. Before you commit, check the licence text, decide between SQLite, MySQL and MariaDB at install time, and read the Marzban Node documentation to confirm whether multi-node is worth the extra moving parts for your setup.

Frequently asked questions

Official sources

1. Gozargah/Marzban on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases