Meridian

Deploy it right. Share it easily.
One command turns a fresh VPS into a hardened self-hosted VPN server, with a built-in web panel and a connection page for each person.

A VPN that connects can still give itself away: an open admin port, a self-signed certificate, a container that skips the firewall. Meridian sets up every layer on a fresh Debian or Ubuntu VPS, tests the server with real traffic, and gives you two interfaces: a connection page for each person who connects and a web panel to manage people and servers from any browser. When an address gets blocked, add a relay, turn on domain mode, or move an exit; apps pick up the change on their next refresh.

_{Watch a full meridian setup, start to finish (3½ min) · download the MP4 · по-русски}

Web panel and connection pages

Each person gets a connection page at their subscription URL; you get a self-hosted web panel (owner console) on the control server. Both demos below run in your browser on invented data: click around, nothing is real and nothing is sent anywhere.

Try the connection page · Try the web panel

• Web panel (meridian panel): runs on the control server behind a secret HTTPS path, protected by a password and optional authenticator code, with a strict CSP and no external requests. Add people, share links and QR codes, set expiry dates, traffic limits, and device caps, keep private notes and tags, reissue links, remove access, or cut off active sessions. Check server health, traffic, and monthly allowances, set the default page language and a notice for everyone, issue scoped API tokens, and choose privacy levels. Server and routing topology stays reviewed in the CLI.
• Connection page: served at every person's subscription URL in English, Russian, Persian, and Chinese. In a browser it shows recommended apps for their device, one-tap import, a QR code, account status, traffic, and plain help; in a VPN app the same URL delivers native profiles (Xray JSON, Mihomo, sing-box, or Base64).

Install

macOS or Linux (on Windows, use WSL):

curl -sSf https://getmeridian.org/install.sh | bash

Or from PyPI: uv tool install meridian-vpn (or pipx install meridian-vpn). When the newest release is a beta, add --prerelease allow (pipx: --pip-args=--pre) to get the version this page describes.

You need a fresh Debian or Ubuntu VPS you can reach over SSH with a key, as root or a user with passwordless sudo. Meridian runs on your computer, not on the server.

Quick start

meridian deploy 198.51.100.10 --client-name alice

When it prints "Done", send Alice the connection page link. They open it, install the recommended app, and tap once to connect. Then:

meridian panel                     # web panel URL and a one-time setup link
meridian client add bob carol      # or add people from the CLI
meridian client show bob           # print their link and status
meridian test                      # real traffic through the delivered subscription

Re-run deploy at any time: keys, paths, and clients are kept. meridian setup asks the same questions as a guided wizard.

What one deploy sets up

• Methods: VLESS+Reality and XHTTP on TCP 443, Hysteria2 on UDP 443 with salamander. Every subscription lists all of them (with Chrome and Firefox TLS fingerprints), and capable apps switch on their own.
• Camouflage: nginx routes TCP 443 by SNI without decrypting. A probe without the key reaches a real website and gets its genuine certificate. Deploy picks the target from the server's own network.
• Hardening: key-only SSH, fail2ban, BBR, UFW opening only SSH and 443, and a Let's Encrypt certificate for the IP. No domain needed.
• Control service and web panel: Meridian's own, on a secret HTTPS path: users, subscriptions, and the web panel. Shared links never reveal the path, and each server's agent dials out to it, so nodes open no extra ports. No Docker, no third-party panel.
• Privacy and backups: no client IPs or connection logs are stored; device and daily history tracking are opt-in and off by default. After every change your machine pulls an encrypted snapshot sealed to your device keys and a recovery key. If the control server is lost or seized, meridian restore rebuilds it on another server.

Options worth knowing:

meridian deploy 198.51.100.10 --domain vpn.example.com    # XHTTP + WSS through Cloudflare when the IP is blocked
meridian deploy 198.51.100.10 --display-name "Family VPN" # label on every connection page
meridian deploy 198.51.100.10 --no-geo-block              # allow Russian sites through the VPN (blocked by default)
meridian deploy local                                     # run on the server itself

Grow the fleet

meridian node add 198.51.100.20 --name germany        # another exit
meridian relay add 203.0.113.10 --exit 198.51.100.10  # domestic entry point (Realm TCP forwarder)
meridian route add germany --preset ai --via warp     # route chosen destinations through WARP
meridian node replace EXIT_ID 198.51.100.30           # move a blocked exit, keys and clients included
meridian setup                                        # any shape: relay chains, routing gateways

Every change edits one topology in ~/.config/meridian/cluster.yml. meridian plan shows what would change; meridian apply applies exactly that, with checkpoints, so an interrupted run resumes. Back up that folder and the recovery key deploy shows once: together they bring the fleet back on a new machine.

When something breaks

meridian test 198.51.100.10           # which step fails: network, TLS, subscription, or tunnel
meridian test 198.51.100.10 --probe   # the server as a censor sees it (run from inside the censored network)
meridian check                        # server health over SSH
meridian doctor --ai                  # redacted report, ready to paste into an AI chat

IP blocked? Follow the recovery guide. Users can run "Check my connection" on their own page.

Commands

Every command takes --help; most take --json. Full list: CLI reference.

Client apps

The connection page recommends one for each device and links more.

AI agents

meridian help agents

prints a guide for Claude Code, Codex, Cursor, and other agents: how Meridian works and how to drive it safely (--yes, --json envelopes, exit codes, meridian api contracts). Every docs page is also served as Markdown, indexed at getmeridian.org/llms.txt.

More

• Docs: getmeridian.org · connection page demo · web panel demo · architecture
• Upgrading from 3.x: Meridian 4 replaces 3x-ui with its own control service and is not an in-place upgrade; every user gets a new link. How to move. A fleet on an earlier Meridian 4 release that runs Remnawave moves in place with meridian migrate, keeping every link.
• Security: SECURITY.md covers the threat model, including what Meridian does not protect against.
• Contributing: CONTRIBUTING.md · issues (attach meridian doctor output)
• License: MIT