⚠️ Caution: This project is under active development! ⚠️

Compass VPN Agent

A self-contained, Dockerized Xray VPN node. You provision the whole host with one command, and it ships its metrics back to your manager's Grafana.

• Full guide
• Features

Requirements

• A fresh Debian 11+ or Ubuntu 22.04+ server, with root access.
• The auth values from your manager setup; they go in env_file.

Full requirements are on the website.

Quick start

# 1. Get the code
git clone https://github.com/compassvpn/agent.git
cd agent

# 2. Configure it
cp env_file.example env_file
nano env_file          # paste the values from your manager setup

# 3. Bring it up
./agent.sh start

The first run installs Docker and builds the images, so give it a few minutes. Metrics should appear in your Grafana within 5 to 10 minutes.

Commands

Everything goes through ./agent.sh (run ./agent.sh help to list them):

How it works

Two files drive everything:

• agent.sh is the launcher you run. It makes sure uv is installed (Ansible's control side needs Python 3.12+, newer than these releases ship, and uv fetches one on its own, so there's nothing system-wide to manage), then runs the playbook from a pinned toolchain (pyproject.toml plus uv.lock) so every server gets the exact same Ansible and dependency versions.
• agent.yml is a single Ansible playbook that provisions the host and deploys the stack, in stages.

./agent.sh start runs the playbook top to bottom:

1. prepare: base packages, DNS and UTC timezone, kernel/network tuning (BBR, conntrack, file limits), the UFW firewall (SSH plus the service ports), and the log files and rotation.
2. docker: installs Docker if it's missing.
3. identifier: generates a stable per-node ID once (stored in env_file), used as a metrics label.
4. cron: schedules the optional hourly auto-update and the periodic re-deploy and cert renewal.
5. deploy: docker compose up -d --build to (re)start the stack.

It's idempotent, so re-running ./agent.sh start only changes what has drifted (usually just a container rebuild). Each stage is also a tag, so you can run one on its own, for example uv run --frozen ansible-playbook agent.yml --tags deploy.

The Ansible version is pinned in pyproject.toml and locked in uv.lock. To move to a newer Ansible, bump it there and run uv lock; to refresh the pinned dependencies without changing Ansible, run uv lock --upgrade. Commit both files either way.

The stack

Six containers, wired up in docker-compose.yml: