Meridian (uburuntu/meridian)

Meridian

https://github.com/uburuntu/meridian
Admin
Meridian deploys a private, censorship-resistant VPN server in one command, invisible to DPI, active...

Tokens:25,029
Snippets:133
Trust Score:8.3
Update:1 week ago
Show doc for...
Context Summary (auto-generated)
Raw
# Meridian

Meridian is a CLI tool that deploys censorship-resistant VLESS+Reality proxy servers in one command. It orchestrates Docker, Xray, HAProxy, Caddy, firewall configuration, and TLS certificates automatically, making your server indistinguishable from legitimate HTTPS traffic. The tool handles the complexity of setting up undetectable VPN infrastructure so users can focus on staying connected in censored regions.

The project is designed for the "tech friend" who sets up VPN access for family and friends. After deployment, users receive a shareable connection page with QR codes that work with popular VPN clients. When an IP gets blocked (common in censored regions), spinning up a new server takes minutes. Meridian supports standalone mode (IP-only), domain mode (CDN fallback via Cloudflare), and relay mode (TCP forwarding through domestic servers for additional resilience).

## Deploy a Proxy Server

Deploy a VLESS+Reality proxy server to a VPS. The wizard guides through configuration interactively, or provide all options via flags.

```bash
# Interactive deployment wizard
meridian deploy

# Deploy to a specific server with defaults
meridian deploy 1.2.3.4

# Deploy with custom SNI camouflage target
meridian deploy 1.2.3.4 --sni www.microsoft.com

# Deploy with CDN fallback via Cloudflare domain
meridian deploy 1.2.3.4 --domain proxy.example.com

# Deploy directly on the server (no SSH, run as root)
meridian deploy local

# Non-interactive deployment with all options
meridian deploy 1.2.3.4 --sni www.twitch.tv --name alice --yes

# Deploy with a non-root user (sudo required)
meridian deploy 1.2.3.4 --user ubuntu

# Skip server hardening (for servers with other services)
meridian deploy 1.2.3.4 --no-harden

# Disable XHTTP transport
meridian deploy 1.2.3.4 --no-xhttp
```

## Add Client

Add a new client to the proxy server. Each client gets unique keys and a hosted connection page with QR codes.

```bash
# Add a client named "alice"
meridian client add alice

# Add client to a specific server
meridian client add alice --server 1.2.3.4

# Add client using server name from registry
meridian client add alice --server mybox

# Add client with non-root SSH user
meridian client add alice --user ubuntu
```

## List Clients

Display all proxy clients with their status and enabled protocols.

```bash
# List all clients on the default server
meridian client list

# List clients for a specific server
meridian client list --server 1.2.3.4

# List clients using server name
meridian client list --server mybox
```

## Remove Client

Revoke a client's access by removing their keys from all protocol inbounds.

```bash
# Remove client "alice"
meridian client remove alice

# Remove client from a specific server
meridian client remove alice --server 1.2.3.4
```

## Deploy a Relay Node

Deploy a lightweight TCP relay that forwards traffic through a domestic server to an exit server abroad. Useful when the exit server's IP gets blocked.

```bash
# Deploy relay forwarding to exit server
meridian relay deploy 10.0.0.1 --exit 5.6.7.8

# Deploy relay with a friendly name
meridian relay deploy 10.0.0.1 --exit 5.6.7.8 --name ru-moscow

# Deploy relay on a custom port (default: 443)
meridian relay deploy 10.0.0.1 --exit 5.6.7.8 --port 8443

# Deploy relay using exit server name from registry
meridian relay deploy 10.0.0.1 --exit myserver

# Non-interactive relay deployment
meridian relay deploy 10.0.0.1 --exit 5.6.7.8 --yes
```

## List Relay Nodes

Display all configured relay nodes and their exit servers.

```bash
# List all relays across all exit servers
meridian relay list

# List relays for a specific exit server
meridian relay list --exit 5.6.7.8
```

## Check Relay Health

Verify a relay node is functioning correctly by testing connectivity and service status.

```bash
# Check relay health (auto-detects exit server)
meridian relay check 10.0.0.1

# Check relay with explicit exit server
meridian relay check 10.0.0.1 --exit 5.6.7.8
```

## Remove Relay Node

Remove a relay from the exit server configuration and stop the forwarding service.

```bash
# Remove relay (auto-detects exit server)
meridian relay remove 10.0.0.1

# Remove relay with explicit exit server
meridian relay remove 10.0.0.1 --exit 5.6.7.8

# Remove relay without confirmation
meridian relay remove 10.0.0.1 --yes
```

## Pre-flight Server Validation

Test server compatibility before deploying. Checks SNI reachability, port availability, DNS, OS, disk space, and ASN without installing anything.

```bash
# Run pre-flight checks
meridian preflight 1.2.3.4

# Check with specific domain
meridian preflight 1.2.3.4 --domain proxy.example.com

# Check with custom SNI target
meridian preflight 1.2.3.4 --sni www.twitch.tv

# Generate AI-ready diagnostic prompt
meridian preflight 1.2.3.4 --ai
```

## Scan for Optimal SNI Targets

Find optimal SNI camouflage targets on the server's network using RealiTLScanner. Same-ASN targets are hardest for censors to distinguish.

```bash
# Scan for SNI targets
meridian scan 1.2.3.4

# Scan using server name from registry
meridian scan --server mybox

# Scan locally (when running on the server)
meridian scan local
```

## Test Proxy Reachability

Test if the proxy is reachable from the client device. No SSH required.

```bash
# Test connectivity to server
meridian test 1.2.3.4

# Test with domain mode
meridian test 1.2.3.4 --domain proxy.example.com

# Test with specific SNI
meridian test 1.2.3.4 --sni www.microsoft.com

# Test using server name from registry
meridian test --server mybox
```

## Collect System Diagnostics

Gather server diagnostics for debugging and bug reports. Automatically redacts secrets.

```bash
# Collect diagnostics
meridian doctor 1.2.3.4

# Generate AI-ready diagnostic prompt (copies to clipboard)
meridian doctor 1.2.3.4 --ai

# Alias for doctor
meridian rage 1.2.3.4
```

## Remove Proxy Deployment

Completely remove the proxy deployment from a server.

```bash
# Remove proxy with confirmation
meridian teardown 1.2.3.4

# Remove without confirmation
meridian teardown 1.2.3.4 --yes

# Remove using server name
meridian teardown --server mybox
```

## Manage Known Servers

Track and manage servers in a local registry for easier command usage.

```bash
# Add a server to the registry
meridian server add 1.2.3.4 --name mybox --user root

# List all known servers
meridian server list

# Remove a server from registry
meridian server remove mybox
```

## Update Meridian CLI

Update the Meridian CLI to the latest version.

```bash
# Update to latest version
meridian update

# Check current version
meridian --version
```

## Installation

Install Meridian CLI on macOS or Linux. Windows users should use WSL.

```bash
# Quick install via script (recommended)
curl -sSf https://getmeridian.org/install.sh | bash

# Install via uv (recommended package manager)
uv tool install meridian-vpn

# Install via pipx (alternative)
pipx install meridian-vpn
```

## Domain Mode Cloudflare Setup

Configure Cloudflare for CDN fallback when using domain mode. The WSS connection routes through Cloudflare's CDN, working even when the server IP is blocked.

```bash
# 1. Add domain in Cloudflare with A record pointing to server IP
# 2. Keep cloud icon grey ("DNS only") - don't enable proxying yet

# 3. Deploy with domain
meridian deploy 1.2.3.4 --domain proxy.example.com

# 4. After successful deploy, switch to orange cloud (Proxied) in Cloudflare
# 5. Configure SSL/TLS → Full (Strict) and Network → Enable WebSockets
```

Meridian is ideal for individuals providing VPN access to family and friends in censored regions, power users managing multiple proxy servers, and organizations needing resilient internet access infrastructure. The three-tier connection strategy (Reality primary, XHTTP alternative, WSS/CDN backup) ensures connectivity even when direct IP access is blocked. The relay system adds another layer of resilience by routing through domestic IPs that are harder to block.

The tool follows an idempotent design — running `meridian deploy` multiple times is safe and will not regenerate credentials or duplicate work. Credentials are stored locally in `~/.meridian/credentials/` and synced to servers for the hosted connection pages. Client management through the panel API ensures consistent state across local files and server configuration.