Lightweight Go agent for managing VPN servers across 200+ countries.

Part of the uSipipo VPN Ecosystem - Centralized orchestration for multi-country VPN infrastructure.

The VPN Agent runs on each VPS server worldwide, providing:

• Remote VPN Management - Create/delete WireGuard peers via HTTPS API
• Auto-Reporting Metrics - Push system metrics to backend every 1 minute
• Secure Communication - API Key authentication + HTTPS encryption
• Multi-Platform Support - Linux, macOS, Windows (amd64, arm64)

┌─────────────────────────────────────────────────┐
│         BACKEND CENTRAL (Orchestrator)          │
│  - Server registry & load balancing             │
│  - User authentication & billing                │
│  - Metrics storage & dashboards                 │
└─────────────────────────────────────────────────┘
                     │ HTTPS + API Key
                     │ (every 1 minute)
        ┌────────────┼────────────┬────────────┐
        │            │            │            │
   ┌────▼────┐  ┌───▼────┐  ┌───▼────┐  ┌───▼────┐
   │ USA VPS │  │ DE VPS │  │ BE VPS │  │ XX VPS │
   │ ┌─────┐ │  │ ┌────┐ │  │ ┌────┐ │  │ ┌────┐ │
   │ │Agent│ │  │ │Agent│ │  │ │Agent│ │  │ │Agent│ │
   │ └──┬──┘ │  │ └─┬──┘ │  │ └─┬──┘ │  │ └─┬──┘ │
    │ ┌──▼──────┐│ │ ┌─▼──────┐│ │ ┌─▼──────┐│ │ ┌─▼──────┐│
    │ │WireGuard││ │ │WireGuard││ │ │WireGuard││ │ │WireGuard││
    │ └─────────┘│ │ └────────┘│ │ └────────┘│ │ └────────┘│
   └─────────┘  └───────┘  └───────┘  └───────┘

• ✅ WireGuard Integration - Create/delete peers via wg commands

• ✅ System Metrics - CPU, memory, disk, network usage
• ✅ VPN Metrics - Active keys/peers, bytes transferred
• ✅ Latency Tracking - Average, p95, p99 latency
• ✅ Auto-Reporting - Push metrics to backend every 1 minute

• ✅ API Key Authentication - X-API-Key header validation
• ✅ HTTPS Encryption - Caddy + DuckDNS with Let's Encrypt
• ✅ Encrypted API Keys at Rest - Fernet encryption in database
• ✅ No Hardcoded Secrets - All secrets via environment variables

• ✅ Multi-Platform Builds - Linux, macOS, Windows (amd64, arm64)
• ✅ GitHub Actions CI/CD - Auto-build on release
• ✅ systemd Service - Production-ready deployment
• ✅ Docker Support - Containerized deployment (planned)

# Linux AMD64 (most VPS)
wget https://github.com/uSipipo-Team/usipipo-agent/releases/latest/download/usipipo-agent-linux-amd64.zip
unzip usipipo-agent-linux-amd64.zip
chmod +x usipipo-agent-linux-amd64

# Linux ARM64 (Raspberry Pi, ARM VPS)
wget https://github.com/uSipipo-Team/usipipo-agent/releases/latest/download/usipipo-agent-linux-arm64.zip
unzip usipipo-agent-linux-arm64.zip
chmod +x usipipo-agent-linux-arm64

git clone https://github.com/uSipipo-Team/usipipo-agent.git
cd usipipo-agent
go build -o agent ./cmd/agent

# Agent configuration
AGENT_PORT=8080
AGENT_API_KEY=your-unique-api-key-here
BACKEND_URL=https://api.usipipo.duckdns.org
SERVER_ID=us-east-1

# WireGuard configuration
WG_INTERFACE=wg0
WG_SERVER_IP=your-server-public-ip
WG_SERVER_PORT=51820

# Create WireGuard peer
curl -X POST -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name":"user-456"}' \
  https://usipipousa.duckdns.org/wireguard/peers

# Get metrics
curl -H "X-API-Key: your-api-key" \
  https://usipipousa.duckdns.org/metrics

# 1. Create directory
sudo mkdir -p /opt/usipipo-agent
sudo cp usipipo-agent-linux-amd64 /opt/usipipo-agent/agent
sudo cp .env.example /opt/usipipo-agent/.env

# 2. Configure environment
sudo nano /opt/usipipo-agent/.env

# 3. Install systemd service
sudo cp systemd/usipipo-agent.service /etc/systemd/system/

# 4. Create system user
sudo useradd -r -s /bin/false usipipo
sudo chown -R usipipo:usipipo /opt/usipipo-agent

# 5. Enable and start
sudo systemctl daemon-reload
sudo systemctl enable usipipo-agent
sudo systemctl start usipipo-agent

# 6. Check status
sudo systemctl status usipipo-agent
sudo journalctl -u usipipo-agent -f

# /etc/caddy/Caddyfile
usipipousa.duckdns.org {
    reverse_proxy localhost:8080
    tls {
        dns duckdns YOUR_DUCKDNS_TOKEN
    }
}

usipipode.duckdns.org {
    reverse_proxy localhost:8080
    tls {
        dns duckdns YOUR_DUCKDNS_TOKEN
    }
}

Agents push metrics to backend every 1 minute:

{
  "server_id": "us-east-1",
  "timestamp": "2026-03-28T10:00:00Z",
  "system": {
    "cpu_percent": 45.2,
    "memory_percent": 62.1,
    "disk_percent": 38.5,
    "network_rx_bytes": 1234567890,
    "network_tx_bytes": 9876543210
  },
  "vpn": {
    "wireguard": {
      "active_peers": 38,
      "total_bytes_transferred": 4500000000
    }
  },
  "latency_ms": {
    "avg": 12.5,
    "p95": 25.3,
    "p99": 45.8
  }
}

# Run all tests
go test -v ./...

# Run specific package tests
go test -v ./internal/api/...

# Run with coverage
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

usipipo-agent/
├── cmd/
│   └── agent/
│       └── main.go              # Entry point
├── internal/
│   ├── api/
│   │   ├── handlers.go          # HTTP handlers
│   │   ├── middleware.go        # API Key auth
│   │   └── server.go            # HTTP server setup
│   ├── vpn/
│   │   └── wireguard.go         # WireGuard wrapper
│   ├── metrics/
│   │   ├── types.go             # Metrics types
│   │   └── collector.go         # Metrics collector
│   ├── reporter/
│   │   └── reporter.go          # Push metrics to backend
│   └── config/
│       └── config.go            # Configuration loader
├── systemd/
│   └── usipipo-agent.service    # systemd service file
├── .github/workflows/
│   ├── ci.yml                   # CI workflow
│   └── release.yml              # Release workflow
├── go.mod
├── go.sum
├── DEPLOYMENT.md                # Deployment guide
└── README.md                    # This file

Agent API keys are encrypted at rest in the backend database using Fernet symmetric encryption.

Generate encryption key:

python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())'

Set in backend .env:

ENCRYPTION_KEY=your-generated-key-here

• ✅ Never commit .env files
• ✅ Rotate API keys every 90 days
• ✅ Use HTTPS for all communication
• ✅ Enable firewall rules (allow only backend IP)
• ✅ Monitor logs for suspicious activity

# Check agent health
curl https://usipipousa.duckdns.org/health
# Expected: {"status":"healthy"}

# View logs
sudo journalctl -u usipipo-agent -f

# View last 100 lines
sudo journalctl -u usipipo-agent -n 100

Backend provides dashboards for:

• Server status (online/offline/maintenance)
• CPU, memory, disk usage per server
• Active connections per country
• Total bandwidth (GB) per server
• Latency comparison across countries

• Docker container support
• Automatic failover between servers
• Real-time latency monitoring

• WebSocket support for real-time metrics
• Automatic certificate renewal
• Multi-WAN support
• GeoDNS integration

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.

• usipipo-backend - Central orchestrator (FastAPI)
• usipipo-commons - Shared library (PyPI)
• usipipo-telegram-bot - Telegram bot for user interaction
• usipipo-docs - Documentation portal

• Documentation: https://github.com/uSipipo-Team/usipipo-docs
• Issues: https://github.com/uSipipo-Team/usipipo-agent/issues
• Email: dev@usipipo.com

Built with ❤️ by uSipipo Team