{"id":47750371,"url":"https://github.com/usipipo-team/usipipo-agent","last_synced_at":"2026-04-05T11:01:10.876Z","repository":{"id":347737404,"uuid":"1195058025","full_name":"uSipipo-Team/usipipo-agent","owner":"uSipipo-Team","description":"🤖 Go-based VPN agent for multi-country server management | Outline + WireGuard | Auto-reporting metrics | Production-ready for 200+ countries | v0.1.0","archived":false,"fork":false,"pushed_at":"2026-04-03T01:10:42.000Z","size":202,"stargazers_count":1,"open_issues_count":13,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T11:11:20.840Z","etag":null,"topics":["agent","go","golang","infrastructure","monitoring","multi-cloud","outline","usipipo","vpn","vpn-management","vpn-server","wireguard"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uSipipo-Team.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-29T06:45:46.000Z","updated_at":"2026-04-03T01:10:38.000Z","dependencies_parsed_at":"2026-04-05T11:00:55.225Z","dependency_job_id":null,"html_url":"https://github.com/uSipipo-Team/usipipo-agent","commit_stats":null,"previous_names":["usipipo-team/usipipo-agent"],"tags_count":36,"template":false,"template_full_name":null,"purl":"pkg:github/uSipipo-Team/usipipo-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uSipipo-Team%2Fusipipo-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uSipipo-Team%2Fusipipo-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uSipipo-Team%2Fusipipo-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uSipipo-Team%2Fusipipo-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uSipipo-Team","download_url":"https://codeload.github.com/uSipipo-Team/usipipo-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uSipipo-Team%2Fusipipo-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31433044,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T08:13:15.228Z","status":"ssl_error","status_checked_at":"2026-04-05T08:13:11.839Z","response_time":75,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","go","golang","infrastructure","monitoring","multi-cloud","outline","usipipo","vpn","vpn-management","vpn-server","wireguard"],"created_at":"2026-04-03T03:02:30.256Z","updated_at":"2026-04-05T11:01:10.851Z","avatar_url":"https://github.com/uSipipo-Team.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# uSipipo VPN Agent\n\n[![CI](https://github.com/uSipipo-Team/usipipo-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/uSipipo-Team/usipipo-agent/actions/workflows/ci.yml)\n[![Release](https://img.shields.io/github/v/release/uSipipo-Team/usipipo-agent)](https://github.com/uSipipo-Team/usipipo-agent/releases)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n**Lightweight Go agent for managing VPN servers across 200+ countries.**\n\nPart of the **uSipipo VPN Ecosystem** - Centralized orchestration for multi-country VPN infrastructure.\n\n---\n\n## 🎯 Overview\n\nThe VPN Agent runs on each VPS server worldwide, providing:\n- **Remote VPN Management** - Create/delete Outline keys and WireGuard peers via HTTPS API\n- **Auto-Reporting Metrics** - Push system metrics to backend every 1 minute\n- **Secure Communication** - API Key authentication + HTTPS encryption\n- **Multi-Platform Support** - Linux, macOS, Windows (amd64, arm64)\n\n---\n\n## 🏗️ Architecture\n\n```\n┌─────────────────────────────────────────────────┐\n│         BACKEND CENTRAL (Orchestrator)          │\n│  - Server registry \u0026 load balancing             │\n│  - User authentication \u0026 billing                │\n│  - Metrics storage \u0026 dashboards                 │\n└─────────────────────────────────────────────────┘\n                     │ HTTPS + API Key\n                     │ (every 1 minute)\n        ┌────────────┼────────────┬────────────┐\n        │            │            │            │\n   ┌────▼────┐  ┌───▼────┐  ┌───▼────┐  ┌───▼────┐\n   │ USA VPS │  │ DE VPS │  │ BE VPS │  │ XX VPS │\n   │ ┌─────┐ │  │ ┌────┐ │  │ ┌────┐ │  │ ┌────┐ │\n   │ │Agent│ │  │ │Agent│ │  │ │Agent│ │  │ │Agent│ │\n   │ └──┬──┘ │  │ └─┬──┘ │  │ └─┬──┘ │  │ └─┬──┘ │\n   │    │    │  │   │    │  │   │    │  │   │    │\n   │ ┌──▼────┐│  │ ┌─▼───┐│  │ ┌─▼───┐│  │ ┌─▼───┐│\n   │ │Outline││  │ │Outline││ │ │Outline││ │ │Outline││\n   │ │WireGuard││ │ │WireGuard││ │ │WireGuard││ │ │WireGuard││\n   │ └───────┘│  │ └────┘│  │ └────┘│  │ └────┘│\n   └─────────┘  └───────┘  └───────┘  └───────┘\n```\n\n---\n\n## 🚀 Features\n\n### VPN Management\n- ✅ **Outline Manager Integration** - Create/delete Shadowsocks keys via Outline API\n- ✅ **WireGuard Integration** - Create/delete peers via `wg` commands\n- ✅ **Trust Tunnel Support** - AdGuard VPN integration (planned)\n\n### Metrics \u0026 Monitoring\n- ✅ **System Metrics** - CPU, memory, disk, network usage\n- ✅ **VPN Metrics** - Active keys/peers, bytes transferred\n- ✅ **Latency Tracking** - Average, p95, p99 latency\n- ✅ **Auto-Reporting** - Push metrics to backend every 1 minute\n\n### Security\n- ✅ **API Key Authentication** - X-API-Key header validation\n- ✅ **HTTPS Encryption** - Caddy + DuckDNS with Let's Encrypt\n- ✅ **Encrypted API Keys at Rest** - Fernet encryption in database\n- ✅ **No Hardcoded Secrets** - All secrets via environment variables\n\n### Infrastructure\n- ✅ **Multi-Platform Builds** - Linux, macOS, Windows (amd64, arm64)\n- ✅ **GitHub Actions CI/CD** - Auto-build on release\n- ✅ **systemd Service** - Production-ready deployment\n- ✅ **Docker Support** - Containerized deployment (planned)\n\n---\n\n## 📦 Installation\n\n### Download Pre-built Binary\n\n```bash\n# Linux AMD64 (most VPS)\nwget https://github.com/uSipipo-Team/usipipo-agent/releases/latest/download/usipipo-agent-linux-amd64.zip\nunzip usipipo-agent-linux-amd64.zip\nchmod +x usipipo-agent-linux-amd64\n\n# Linux ARM64 (Raspberry Pi, ARM VPS)\nwget https://github.com/uSipipo-Team/usipipo-agent/releases/latest/download/usipipo-agent-linux-arm64.zip\nunzip usipipo-agent-linux-arm64.zip\nchmod +x usipipo-agent-linux-arm64\n```\n\n### Build from Source\n\n```bash\ngit clone https://github.com/uSipipo-Team/usipipo-agent.git\ncd usipipo-agent\ngo build -o agent ./cmd/agent\n```\n\n---\n\n## ⚙️ Configuration\n\n### Environment Variables\n\n| Variable | Description | Default | Required |\n|----------|-------------|---------|----------|\n| `AGENT_PORT` | Port to listen on | `8080` | No |\n| `AGENT_API_KEY` | API key for authentication | - | **Yes** |\n| `BACKEND_URL` | Backend URL for metrics | - | **Yes** |\n| `SERVER_ID` | Server identifier (UUID) | - | **Yes** |\n| `OUTLINE_API_URL` | Outline Manager API URL | `http://localhost:8081` | No |\n| `WG_INTERFACE` | WireGuard interface name | `wg0` | No |\n\n### Example `.env` File\n\n```bash\n# Agent configuration\nAGENT_PORT=8080\nAGENT_API_KEY=your-unique-api-key-here\nBACKEND_URL=https://api.usipipo.duckdns.org\nSERVER_ID=us-east-1\n\n# VPN configuration\nOUTLINE_API_URL=http://localhost:8081\nWG_INTERFACE=wg0\n```\n\n---\n\n## 🎛️ API Endpoints\n\n### Public Endpoints\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/health` | Health check |\n\n### Protected Endpoints (require `X-API-Key` header)\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/status` | Server status |\n| `GET` | `/metrics` | Detailed system + VPN metrics |\n| `POST` | `/outline/keys` | Create Outline key |\n| `DELETE` | `/outline/keys/:id` | Delete Outline key |\n| `POST` | `/wireguard/peers` | Create WireGuard peer |\n| `DELETE` | `/wireguard/peers/:name` | Delete WireGuard peer |\n| `GET` | `/wireguard/peers/:name/usage` | Get peer usage stats |\n\n### Example Usage\n\n```bash\n# Create Outline key\ncurl -X POST -H \"X-API-Key: your-api-key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"user-123\"}' \\\n  https://usipipousa.duckdns.org/outline/keys\n\n# Create WireGuard peer\ncurl -X POST -H \"X-API-Key: your-api-key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"user-456\"}' \\\n  https://usipipousa.duckdns.org/wireguard/peers\n\n# Get metrics\ncurl -H \"X-API-Key: your-api-key\" \\\n  https://usipipousa.duckdns.org/metrics\n```\n\n---\n\n## 🚀 Deployment\n\n### Production Deployment (systemd)\n\n```bash\n# 1. Create directory\nsudo mkdir -p /opt/usipipo-agent\nsudo cp usipipo-agent-linux-amd64 /opt/usipipo-agent/agent\nsudo cp .env.example /opt/usipipo-agent/.env\n\n# 2. Configure environment\nsudo nano /opt/usipipo-agent/.env\n\n# 3. Install systemd service\nsudo cp systemd/usipipo-agent.service /etc/systemd/system/\n\n# 4. Create system user\nsudo useradd -r -s /bin/false usipipo\nsudo chown -R usipipo:usipipo /opt/usipipo-agent\n\n# 5. Enable and start\nsudo systemctl daemon-reload\nsudo systemctl enable usipipo-agent\nsudo systemctl start usipipo-agent\n\n# 6. Check status\nsudo systemctl status usipipo-agent\nsudo journalctl -u usipipo-agent -f\n```\n\n### Caddy + DuckDNS Configuration\n\n```caddyfile\n# /etc/caddy/Caddyfile\nusipipousa.duckdns.org {\n    reverse_proxy localhost:8080\n    tls {\n        dns duckdns YOUR_DUCKDNS_TOKEN\n    }\n}\n\nusipipode.duckdns.org {\n    reverse_proxy localhost:8080\n    tls {\n        dns duckdns YOUR_DUCKDNS_TOKEN\n    }\n}\n```\n\n---\n\n## 📊 Metrics Payload\n\nAgents push metrics to backend every 1 minute:\n\n```json\n{\n  \"server_id\": \"us-east-1\",\n  \"timestamp\": \"2026-03-28T10:00:00Z\",\n  \"system\": {\n    \"cpu_percent\": 45.2,\n    \"memory_percent\": 62.1,\n    \"disk_percent\": 38.5,\n    \"network_rx_bytes\": 1234567890,\n    \"network_tx_bytes\": 9876543210\n  },\n  \"vpn\": {\n    \"outline\": {\n      \"active_keys\": 42,\n      \"total_bytes_transferred\": 5000000000\n    },\n    \"wireguard\": {\n      \"active_peers\": 38,\n      \"total_bytes_transferred\": 4500000000\n    }\n  },\n  \"latency_ms\": {\n    \"avg\": 12.5,\n    \"p95\": 25.3,\n    \"p99\": 45.8\n  }\n}\n```\n\n---\n\n## 🧪 Testing\n\n```bash\n# Run all tests\ngo test -v ./...\n\n# Run specific package tests\ngo test -v ./internal/api/...\n\n# Run with coverage\ngo test -coverprofile=coverage.out ./...\ngo tool cover -html=coverage.out\n```\n\n---\n\n## 📁 Project Structure\n\n```\nusipipo-agent/\n├── cmd/\n│   └── agent/\n│       └── main.go              # Entry point\n├── internal/\n│   ├── api/\n│   │   ├── handlers.go          # HTTP handlers\n│   │   ├── middleware.go        # API Key auth\n│   │   └── server.go            # HTTP server setup\n│   ├── vpn/\n│   │   ├── outline.go           # Outline API client\n│   │   └── wireguard.go         # WireGuard wrapper\n│   ├── metrics/\n│   │   ├── types.go             # Metrics types\n│   │   └── collector.go         # Metrics collector\n│   ├── reporter/\n│   │   └── reporter.go          # Push metrics to backend\n│   └── config/\n│       └── config.go            # Configuration loader\n├── systemd/\n│   └── usipipo-agent.service    # systemd service file\n├── .github/workflows/\n│   ├── ci.yml                   # CI workflow\n│   └── release.yml              # Release workflow\n├── go.mod\n├── go.sum\n├── DEPLOYMENT.md                # Deployment guide\n└── README.md                    # This file\n```\n\n---\n\n## 🔒 Security\n\n### API Key Encryption\n\nAgent API keys are **encrypted at rest** in the backend database using Fernet symmetric encryption.\n\n**Generate encryption key:**\n```bash\npython -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())'\n```\n\n**Set in backend `.env`:**\n```bash\nENCRYPTION_KEY=your-generated-key-here\n```\n\n### Best Practices\n\n- ✅ Never commit `.env` files\n- ✅ Rotate API keys every 90 days\n- ✅ Use HTTPS for all communication\n- ✅ Enable firewall rules (allow only backend IP)\n- ✅ Monitor logs for suspicious activity\n\n---\n\n## 📈 Monitoring\n\n### Health Check\n\n```bash\n# Check agent health\ncurl https://usipipousa.duckdns.org/health\n# Expected: {\"status\":\"healthy\"}\n```\n\n### Logs\n\n```bash\n# View logs\nsudo journalctl -u usipipo-agent -f\n\n# View last 100 lines\nsudo journalctl -u usipipo-agent -n 100\n```\n\n### Metrics Dashboard\n\nBackend provides dashboards for:\n- Server status (online/offline/maintenance)\n- CPU, memory, disk usage per server\n- Active connections per country\n- Total bandwidth (GB) per server\n- Latency comparison across countries\n\n---\n\n## 🚧 Roadmap\n\n### Q2 2026\n- [ ] Trust Tunnel (AdGuard) integration\n- [ ] Docker container support\n- [ ] Automatic failover between servers\n- [ ] Real-time latency monitoring\n\n### Q3 2026\n- [ ] WebSocket support for real-time metrics\n- [ ] Automatic certificate renewal\n- [ ] Multi-WAN support\n- [ ] GeoDNS integration\n\n---\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'feat: add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n---\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## 🔗 Related Projects\n\n- **[usipipo-backend](https://github.com/uSipipo-Team/usipipo-backend)** - Central orchestrator (FastAPI)\n- **[usipipo-commons](https://github.com/uSipipo-Team/usipipo-commons)** - Shared library (PyPI)\n- **[usipipo-telegram-bot](https://github.com/uSipipo-Team/usipipo-telegram-bot)** - Telegram bot for user interaction\n- **[usipipo-docs](https://github.com/uSipipo-Team/usipipo-docs)** - Documentation portal\n\n---\n\n## 📞 Support\n\n- **Documentation:** https://github.com/uSipipo-Team/usipipo-docs\n- **Issues:** https://github.com/uSipipo-Team/usipipo-agent/issues\n- **Email:** dev@usipipo.com\n\n---\n\n**Built with ❤️ by uSipipo Team**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusipipo-team%2Fusipipo-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fusipipo-team%2Fusipipo-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusipipo-team%2Fusipipo-agent/lists"}