Quick Start

This guide covers the fastest way to get CompassVPN set up on your server.

Single Server Setup

Setting up a single server takes four steps: prepare the server, clone the repository, fill in your configuration, and start the agent.

Step 1: Prepare the Server

Update the system and install the required packages (as root, or with sudo):

sudo apt update -qq && sudo apt upgrade -yqq && sudo apt install -yqq curl git

A system reboot is recommended after this command.

Step 2: Clone the Repository

git clone https://github.com/compassvpn/agent.git
cd agent

Step 3: Create and Edit Your `env_file`

Copy the example configuration and open it in your editor:

cp env_file.example env_file
nano env_file   # or your preferred editor

Fill in your settings:

Monitoring credentials (ALLOY_REMOTE_WRITE_*): get these three values from a free Grafana Cloud account by following the Monitoring guide. It takes a few minutes.
Cloudflare API details (CF_*): required only if you enable Cloudflare CDN inbounds.

See the Configuration guide for a full explanation of every parameter.

Step 4: Start the Agent

sudo ./agent.sh start

This one command does everything: it prepares the server, builds the services, and starts them. It is safe to re-run whenever you change env_file or just want to make sure everything is in order.

Once it finishes, print your shareable VPN connection links with:

./agent.sh configs

If you have configured monitoring according to the Monitoring guide, allow about 5 to 10 minutes after the agent starts for metrics data to populate your Grafana dashboards.

Agent Commands

agent.sh is the single entry point for managing your deployment:

Command	Description
`./agent.sh start`	Set up, update, or restart everything (safe to re-run)
`./agent.sh stop`	Stop and remove the containers, networks, volumes, and images
`./agent.sh update`	Pull the latest code and re-converge
`./agent.sh configs`	Print the VPN configuration links
`./agent.sh logs [service]`	Tail the container logs (optionally for a single service)
`./agent.sh help`	Show the command reference

Advanced: ./agent.sh start is a wrapper around a single Ansible playbook (agent.yml) whose stages are tagged prepare, docker, identifier, cron, and deploy. To re-run one stage alone, invoke the playbook directly from the agent directory, e.g. uv run --frozen ansible-playbook agent.yml --tags deploy.

Automated Deployment with GitHub Actions (Multiple Servers)

If you need to deploy CompassVPN to multiple servers simultaneously or want to automate your deployment process, GitHub Actions is the recommended approach. This method is ideal for managing a fleet of VPN servers without configuring each one individually. The workflow connects to every server in your list and runs ./agent.sh start for you.

Setting Up GitHub Actions

Fork the CompassVPN agent repository to your GitHub account.
Navigate to your repository’s Settings tab, then on the left menu, select Secrets and variables → Actions

GitHub repository secrets section — GitHub repository secrets configuration page

Authentication Methods

CompassVPN supports two authentication methods:

Password Authentication: Use the format username:password@ip in your SERVERS secret
SSH Key Authentication: Use the format username@ip in your SERVERS secret and provide your private key in the SSH_KEY secret

SSH key authentication is recommended for better security.

You must use either password OR SSH key authentication for ALL servers. These methods cannot be mixed. If you want to use password authentication and have an SSH_KEY secret present, delete the SSH_KEY secret first.

Required Secrets

Setting Up the `SERVERS` Secret

This secret contains the list of your servers, one per line, along with the authentication information.

Password Authentication

Add your servers in the format username:password@ip as shown below:

SERVERS without SSH key — Setting up SERVERS secret for password authentication

SSH Key Authentication

Add your servers in the format username@ip as shown below:

SERVERS with SSH key — Setting up SERVERS secret for SSH key authentication

Setting Up the `SSH_KEY` Secret (SSH Key Authentication)

If you’re using SSH key authentication, you’ll need to add your private SSH key in OpenSSH format:

Setting Up the `ENV_FILE` Secret

The ENV_FILE secret holds your complete CompassVPN environment configuration, the exact same content as the local env_file. Build it from env_file.example in the agent repository, fill in your values, and paste the result into this secret.

See the Configuration guide for a full explanation of every parameter, so you can be sure all required values are set.

Running the Workflow

Once you’ve set up all required secrets:

Navigate to the Actions tab in your repository
Select the Deployment workflow from the sidebar
Click the Run workflow button
Select the branch you want to deploy from (usually main)
Click the green Run workflow button to start the deployment

The workflow will connect to each server in your SERVERS list and deploy CompassVPN with your configuration.

After deployment completes, import the dashboard to monitor your servers by following Import the Dashboard in the Monitoring guide.

After deployment completes, allow 10 to 20 minutes for all servers to initialize and begin reporting metrics fully. The setup time varies based on the number of servers and their connection speeds. You can monitor progress in the Actions tab and verify each server’s status in your Grafana dashboard.

Configuration