Skip to content

CompassVPN: Scalable, Self-Hosted, Open-Source VPN Solution.

A powerful, scalable, and configurable VPN agent with built-in monitoring, automated management, and enhanced security features - all deployed on your own infrastructure.

View Docs
CompassVPN Dashboard

Grafana Cloud Dashboard Images

Overall Dashboard
Overall system performance and key metrics at a glance
Server Metrics Dashboard
Detailed server statistics and bandwidth usage
Xray Metrics Dashboard
Detailed Xray performance metrics and usage statistics
VPN Configuration Links Table
Table displaying available VPN configuration links and their details

Data Flow Diagram

CompassVPN Data Flow Diagram
CompassVPN Data Flow Diagram

Features

Easy Deployment

Deploy your VPN server with a single command and one config file.

  • Edit one env_file, then run ./agent.sh start
  • Idempotent Ansible playbook provisions the host end-to-end
  • Automatic SSL certificate generation using ZeroSSL or Let’s Encrypt
  • Integrated Cloudflare DNS management to automatically manage DNS records.
  • Direct & CDN options: enable any mix of direct or Cloudflare CDN inbounds.

Enhanced Security

Protect your server and network traffic with multiple layers of security features.

  • Automatic blocking: Torrents, Iranian websites, Ads, Malware, Phishing (using curated blocklists)
  • Configuration self-testing via Xray-Knife
  • Hardened Docker containers with dropped Linux capabilities
  • Automated UFW firewall configuration
  • NGINX webserver enhances security and resource efficiency

Complete Monitoring

Gain insights into performance and usage through comprehensive metrics collection.

  • Centralized monitoring via Grafana Cloud or a self-hosted Prometheus
  • Real-time connection statistics
  • Host system resource monitoring (CPU, memory, traffic, …)
  • User metrics: Track approximate unique active users and blocked junk traffic requests

Scalability

Easily scale your VPN infrastructure horizontally.

  • Effortlessly replicate agent instances using Docker for rapid capacity expansion.
  • Stateless agent design simplifies horizontal scaling behind standard load balancers for high availability.
  • Centralized monitoring via the Manager component handles metrics from numerous agents seamlessly.

Network Optimization

Optimize bandwidth usage and connection routing for better performance.

  • NGINX web server improves connection handling efficiency
  • Monitor blocked traffic requests to understand bandwidth savings
  • Flexible Custom DNS options (Default, Cloudflare, ControlD, or custom DoU/DoT/DoH/DoQ)
  • Choose between Direct or WARP outbound connections

Advanced Connectivity

Utilize modern protocols and flexible connection options.

  • WARP and Direct outbound connection choices
  • Per-inbound WireGuard/WARP tunnels (a dedicated tunnel for each inbound)
  • Multiple VLESS & VMess inbounds (TCP / HTTPUpgrade / XHTTP / QUIC)
  • Per-inbound replicas and optional automatic configuration rotation

Get Started Quickly

Deploy your own VPN server in minutes with our comprehensive setup guides.

  • Supports Ubuntu (22.04+) and Debian (11+)
  • Works on AMD64 or ARM64 architecture
  • Requires minimal resources (2 vCPUs, 2GB RAM recommended)

Installation Guide →

Open Source Architecture

CompassVPN consists of two main components:

  1. Agent - Deploys on your VPN server
  2. Manager - Handles metrics and monitoring
git clone https://github.com/compassvpn/agent.git && cd agent
cp env_file.example env_file   # then edit env_file
sudo ./agent.sh start

Agent Repository → | Manager Repository →