Skip to content

Frequently Asked Questions

General

What is CompassVPN?

CompassVPN is free, open-source software that turns a server you rent into your own private VPN. Instead of paying a VPN company and trusting them with your traffic, you run the service yourself. Everything, including the monitoring dashboard, belongs to you.

How is it different from commercial VPN services?

With a commercial VPN you rent a spot on someone else’s servers. With CompassVPN the server is yours:

  • No subscription, you only pay for the server itself
  • Nobody else can see or sell your data
  • No speed limits other than your server’s capacity
  • No logs, unless you turn them on yourself

Is it free?

Yes. The software is open source and free. Your only cost is renting a small server (a VPS) from a cloud provider, which typically starts at a few dollars a month.

Do I need to be a technical expert?

No. If you can rent a server and copy-paste a few commands, you can run CompassVPN. The setup is one settings file and one command, and the Quick Start guide walks you through every step.

What technology does it use?

Under the hood it runs Xray, the engine behind many modern censorship-resistant VPNs, and offers several connection types so that if one is blocked on your network, another usually still works. You choose which ones are enabled in your settings file. The Configuration guide lists them all, with technical details for those who want them.

Requirements

What kind of server do I need?

A small one is enough: any server (VPS, or your own hardware) with 1 CPU core and 1GB of RAM works, though 2 cores and 2GB are recommended. You also need a domain name. The full Requirements list covers ports and domain details.

Which operating systems are supported?

  • Ubuntu 22.04 LTS or newer
  • Debian 11 or newer

This includes ARM64 boards such as the Raspberry Pi, as long as they run a supported OS and meet the hardware requirements. Other Linux distributions are not officially supported or tested.

Does it work in countries with heavy internet censorship?

Yes, that is one of its main goals. CompassVPN uses several strategies to stay reachable:

  • Cloudflare routing: Some connection types send traffic through Cloudflare’s network, so censors see a connection to Cloudflare rather than to your server.
  • Multiple connection types: If one type is blocked, you can switch to another.
  • Disguise: To anyone who is not a real client, your server looks like an ordinary website, and some connection types disguise VPN traffic as a normal visit to a real website.

What is the Cloudflare integration for?

Connection types ending in -cdn route your traffic through Cloudflare’s network, which helps when your server’s address is blocked. To set them up, CompassVPN needs your Cloudflare API Token (CF_API_TOKEN) and Zone ID (CF_ZONE_ID) in the settings file, which it uses to:

  • Create the required DNS records for your domain automatically.
  • Obtain and renew the SSL certificates for those addresses.

Security and Privacy

Is it secure?

Security is the core design goal. Out of the box you get:

  • Encrypted connections with automatically managed SSL certificates
  • A firewall configured for you, opening only the ports that are needed
  • Built-in blocking of malware and phishing sites
  • Isolated, locked-down services (hardened Docker containers)
  • Every new configuration is tested before it goes live
  • Optional automatic updates for security patches

Does it keep logs?

Only you can see anything, and by default there is almost nothing to see:

  • Logs stay on your own server and are never sent anywhere. Detailed logging is off unless you turn it on.
  • Dashboard metrics (speeds, connection counts, server health) go only to your own monitoring account. They are anonymous numbers, not browsing activity.

You control all logging levels and how long anything is kept.

Can it block ads and malware?

Yes, at two levels:

  • DNS blocking: Point the CUSTOM_DNS setting at a filtering provider (like Cloudflare Security or ControlD) to stop bad domains before they even load.
  • Built-in blocklists: The server blocks ads, trackers, malware, phishing sites, and torrents using curated lists that update daily.

Together these typically block around 30% of unwanted traffic, which also saves bandwidth.

Running Your Server

How do I share access with family and friends?

Run ./agent.sh configs on your server. It prints connection links that anyone can paste into a free VPN app on their phone or computer. The User Guide shows which app to use on each device. If you set up monitoring, the same links also appear on your dashboard.

Do I need to maintain the server myself?

Very little. CompassVPN looks after itself:

  • A built-in watchdog restarts any service that crashes or stops responding.
  • New configurations are tested automatically before they are applied.
  • Optionally, connection settings rotate on a schedule for extra safety.
  • Optionally, the software updates itself (the AUTO_UPDATE setting).

What should I do if my server’s IP gets blocked?

Two options:

  1. Route through Cloudflare: Make sure your settings include at least one -cdn connection type and your Cloudflare credentials (CF_API_TOKEN, CF_ZONE_ID, CF_CLEAN_IP_DOMAIN), then run sudo ./agent.sh start again. Your server’s real address stays hidden behind Cloudflare.
  2. Move: Set up CompassVPN on a new server with a fresh address. Setup is quick, so this is less painful than it sounds.

Can I run more than one server?

Yes. Each server runs independently, and they can all report to the same dashboard, so you see your whole setup in one place. Add servers as your needs grow.

The Dashboard

What does the dashboard show?

Your Grafana dashboard shows what your server is doing: active connections, upload and download traffic, an estimate of unique users, blocked junk traffic, and the server’s own health (CPU, memory, network). It also lists your shareable connection links. Setting it up takes a few minutes with a free Grafana Cloud account; see the Monitoring guide.

Is monitoring mandatory?

No, but it is highly recommended, since the dashboard is also the easiest place to grab your connection links. Disabling it requires manually editing docker-compose.yml to remove the metric services, which is only advisable if you are comfortable with Docker.

Contributing

How can I contribute or report a bug?

Use the GitHub Issues section of the relevant repository:

Pull requests with fixes and improvements are welcome on both repositories.