Skip to content
Meridian

Getting Started

View as MarkdownOpen in ChatGPTOpen in Claude

One command turns a fresh VPS into a hardened proxy and gives you a link to share. This guide takes you from zero to a working connection in a few minutes.

Someone sent you a link? You don’t need any of this: see Connecting.

Prerequisites

Section titled “Prerequisites”

You need:

  • A VPS running Debian or Ubuntu that you can reach over SSH with a key, as root or a user with passwordless sudo
  • A terminal on your own machine (macOS, Linux, or WSL on Windows)

Install the CLI

Section titled “Install the CLI”
curl -sSf https://getmeridian.org/install.sh | bash

This installs the meridian command with uv (or pipx as a fallback). See Installation for other options.

Run Meridian on your own machine rather than on the VPS: it connects over SSH, keeps credentials on your device, and lets meridian test check the server from the outside.

Coming from Meridian 3.x? Meridian 4 is not an in-place upgrade. Read Upgrading from 3.x first.

Deploy

Section titled “Deploy”
meridian deploy 198.51.100.10

Run meridian deploy without an IP and it asks for one. If you are logged into the VPS itself as root, meridian deploy local skips SSH.

What happens

Section titled “What happens”
  1. Hardens the server — SSH key-only login, fail2ban, a UFW firewall that opens only what the deployment needs, BBR congestion control
  2. Installs the control plane — the Remnawave panel, plus a node running Xray, all in Docker
  3. Picks a camouflage target — it looks for a suitable TLS 1.3 site on the server’s own network, then falls back to www.google.com, dl.google.com, and www.cloudflare.com (pass --sni to choose your own)
  4. Configures the connection methods — VLESS+Reality and XHTTP on TCP 443 behind nginx, with a Let’s Encrypt certificate for the server’s IP, and Hysteria2 on UDP 443
  5. Verifies real traffic — Meridian pushes traffic through the delivered subscription before saying “Done”, and moves to the next camouflage target if traffic doesn’t pass
  6. Publishes a connection page for the first client

The deploy is checkpointed. If it is interrupted, run the same command again and it finishes where it stopped.

Connect

Section titled “Connect”

When the deploy finishes, it prints:

  • A connection page link with a QR code — send this to the person who will connect. The page has app download links, QR codes, and one-tap “Open in app” buttons.
  • A subscription URL — paste it into any Xray/V2Ray app. Apps refresh it, so new servers and relays show up automatically.

Recommended apps:

AppPlatforms
HappiOS, Android, Windows, macOS, Linux
FlClashXAndroid, Windows, macOS, Linux
Clash MiiOS, Android, Windows, macOS, Linux
ThroneWindows, macOS, Linux

The connection page lists these first and links more apps for each platform.

Check the server from your machine at any time:

meridian test 198.51.100.10

Add more people

Section titled “Add more people”
meridian client add alice

Each person gets their own key, connection page, and subscription URL. meridian client list shows everyone, and meridian client disable alice cuts someone off immediately. See Client management.

Where things live

Section titled “Where things live”
WhatWhere
Topology, panel access, and keys~/.config/meridian/cluster.yml on your machine
Saved SSH servers~/.config/meridian/servers.json on your machine
Proxy servicesDocker, Xray, nginx on the VPS

Client commands talk to the Remnawave panel API recorded in cluster.yml; they don’t need SSH. Back up ~/.config/meridian/ — it is how Meridian manages your servers.

More than one server

Section titled “More than one server”

meridian deploy covers a single server. For several exits, relays through a domestic server, or routing gateways, use the guided wizard:

meridian setup

You can also grow a deployment one step at a time with meridian node add and meridian relay add. Every change goes through the same reviewed topology; meridian plan shows what would change and meridian apply applies it.

Next steps

Section titled “Next steps”