{"id":37030207,"url":"https://github.com/xenups/xenray","last_synced_at":"2026-01-14T03:40:48.869Z","repository":{"id":328274917,"uuid":"1107958502","full_name":"xenups/xenray","owner":"xenups","description":"A modern, lightweight Xray client for Windows, focusing on simplicity and enhancing VPN experience.","archived":false,"fork":false,"pushed_at":"2025-12-30T09:18:03.000Z","size":13274,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-30T11:17:05.898Z","etag":null,"topics":["client","v2ray","vpn","xray-core"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xenups.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"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":"2025-12-01T20:49:15.000Z","updated_at":"2025-12-29T20:37:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/xenups/xenray","commit_stats":null,"previous_names":["xenups/xenray"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/xenups/xenray","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xenups%2Fxenray","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xenups%2Fxenray/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xenups%2Fxenray/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xenups%2Fxenray/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xenups","download_url":"https://codeload.github.com/xenups/xenray/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xenups%2Fxenray/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28408854,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T01:52:23.358Z","status":"online","status_checked_at":"2026-01-14T02:00:06.678Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["client","v2ray","vpn","xray-core"],"created_at":"2026-01-14T03:40:48.063Z","updated_at":"2026-01-14T03:40:48.860Z","avatar_url":"https://github.com/xenups.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🌌 XenRay\n\nA modern, high-performance Xray GUI \u0026 CLI client for Windows and Linux. XenRay focuses on visual excellence, simplicity, and a premium VPN experience.\n\n![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)\n![Python](https://img.shields.io/badge/python-3.10+-green.svg)\n![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux-lightgrey.svg)\n![Coverage](https://img.shields.io/badge/coverage-80%25-yellowgreen.svg)\n![RAM](https://img.shields.io/badge/RAM-~130MB%20(GUI)%20%7C%20~30MB%20(CLI)-blueviolet)\n\n---\n\n## ✨ Features\n\n### 🚀 Performance \u0026 Architecture\n- **Unified Engine**: Single executable for both **GUI** and **Headless CLI** modes.\n- **Extreme RAM Optimization**: GUI footprint reduced to ~130MB; CLI mode runs at a lean **~30MB**.\n- **Lazy Load Architecture**: Core frameworks (like Flet) are only loaded when the UI is requested.\n- **DI Lifecycle Management**: Production-grade dependency injection with zero memory leaks.\n- **Signal-Based Monitoring**: Clean separation - monitors emit facts, ConnectionManager decides actions.\n\n### 🌍 Connection \u0026 Visuals\n- **🚩 Global Flags**: Automatic country flag emojis for all servers.\n- **📍 Smart GeoIP**: Real-time detection of server **Country** and **City**.\n- **⚡ Unified Ping**: Concurrent batch testing with visual latency feedback.\n- **🎨 Apple Glass UI**: Modern glassmorphism design with dynamic connection status glow.\n- **🔐 Dual Mode**: Intelligent switching between **VPN** (TUN) and **Proxy** (SOCKS5/HTTP) modes.\n- **🔄 Auto-Reconnect**: Automatic connection recovery with hybrid detection (log + traffic analysis).\n- **🔋 Battery Saver**: Optional monitoring toggle to disable auto-reconnect and save resources.\n\n### 🛠️ Management\n- **📥 One-Click Import**: Support for VLESS, VMess, Trojan, ShadowSocks, and Hysteria2.\n- **🔄 State Adoption**: CLI automatically detects and manages connections started by the GUI (and vice versa).\n- **📝 Real-time Diagnostics**: Live log streaming with automatic console hiding for core processes.\n- **⚡ Auto-Updates**: Seamless GitHub integration for updating Xray core and the app.\n- **🚀 Startup on Boot**: Optional Windows Task Scheduler integration for auto-start.\n\n---\n\n## 📸 Gallery\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/xenups/xenray/refs/heads/main/screenshots/main.png\" width=\"400\" alt=\"Main UI\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/xenups/xenray/refs/heads/main/screenshots/settings.png\" width=\"400\" alt=\"Settings\"\u003e\n\u003c/p\u003e\n\n---\n\n## 🚀 Getting Started\n\n### Installation (Poetry)\n\n```bash\n# Clone the repository\ngit clone https://github.com/xenups/xenray.git\ncd xenray\n\n# Install all dependencies (including CLI)\npoetry install --with cli\n\n# Run the GUI\npoetry run xenray\n\n# Run the CLI\npoetry run xenray list\n```\n\n---\n\n## 💻 CLI Usage\n\nXenRay features a powerful, colorized CLI for headless environments.\n\n| Command | Description |\n| :--- | :--- |\n| `xenray list` | List all profiles with flags and location info |\n| `xenray connect [N]` | Connect to profile #N or the default one |\n| `xenray ping [N]` | Batch test all profiles or a specific one |\n| `xenray disconnect` | Safely terminate the connection |\n| `xenray status` | Show real-time connection status |\n| `xenray add \"LINK\"` | Add a server from a share link |\n\n---\n\n## 🛠️ Architecture\n\nXenRay is built with a modular, service-oriented architecture designed for efficiency and cross-platform flexibility.\n\n```text\nsrc/\n├── core/\n│   ├── container.py           # Dependency Injection (DI) Root\n│   ├── config_manager.py      # Profile \u0026 settings persistence\n│   ├── connection_manager.py  # High-level connection facade (event authority)\n│   ├── connection_orchestrator.py # Service coordination\n│   ├── i18n.py                # Lazy-loaded internationalization\n│   └── logger.py              # Unified logging system\n│\n├── services/\n│   ├── xray_service.py        # Xray core lifecycle management\n│   ├── singbox_service.py     # TUN-based VPN integration\n│   ├── latency_tester.py      # Multi-threaded ping engine\n│   ├── connection_tester.py   # Real-world connectivity validation\n│   └── monitoring/            # Signal-based monitoring subsystem\n│       ├── signals.py         # MonitorSignal enum (facts, not events)\n│       ├── service.py         # ConnectionMonitoringService facade\n│       ├── passive_log_monitor.py    # Log-based failure detection\n│       ├── active_connectivity_monitor.py # Traffic stall detection\n│       └── auto_reconnect_service.py # Automatic reconnection\n│\n├── ui/\n│   ├── main_window.py         # GUI entry point (Glassmorphism)\n│   ├── components/            # Custom Flet widgets (Cards, Buttons, etc.)\n│   └── handlers/              # UI-to-Service event handling\n│\n├── utils/\n│   ├── admin_utils.py         # UAC \u0026 Root elevation management\n│   ├── link_parser.py         # VLESS/VMess/Trojan/Hysteria parser\n│   └── platform_utils.py      # OS-specific behavior logic\n│\n└── cli.py                     # High-performance Typer CLI interface\n```\n\n### Core Principles\n- **Dependency Injection**: Centralized lifecycle management via `dependency-injector`.\n- **Signal-Based Architecture**: Monitors emit signals (facts), ConnectionManager is the single event authority.\n- **Session-Scoped Lifecycle**: All monitoring tied to connection sessions - no stale events after disconnect.\n- **Hybrid Entry Point**: Smart routing between GUI and CLI modes based on runtime arguments.\n- **Background Persistence**: State adoption logic allows the CLI and GUI to seamlessly share active background connections.\n- **Resource Management**: Background threads and core processes are strictly lifecycle-bound to prevent zombie processes.\n\n---\n\n## 🧪 Development\n\n### Testing\n\nXenRay maintains high test coverage for core components:\n\n```bash\n# Run all tests with coverage\npoetry run pytest\n\n# Run specific test file\npoetry run pytest tests/test_link_parser.py -v\n\n# Generate HTML coverage report\npoetry run pytest --cov=src --cov-report=html\n```\n\n**Current Coverage:**\n- `LinkParser`: 88%\n- `SingboxService`: 83%\n- `ConfigManager`: 73%\n\n### Code Quality\n\nWe use automated tools to maintain code quality:\n\n```bash\n# Format code with Black\npoetry run black src tests\n\n# Sort imports with isort\npoetry run isort src tests\n\n# Lint with Flake8\npoetry run flake8 src tests --max-line-length=120\n```\n\n**Pre-commit Hooks** (Recommended):\n```bash\npoetry run pre-commit install\npoetry run pre-commit run --all-files\n```\n\nSee [`docs/CODE_QUALITY.md`](docs/CODE_QUALITY.md) for detailed information.\n\n### CI/CD\n\nGitHub Actions automatically runs code quality checks on all PRs:\n- ✅ Black formatting\n- ✅ isort import sorting\n- ✅ Flake8 linting\n- ✅ Pytest test suite\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Run tests and code quality checks\n4. Submit a pull request\n\nSee [`docs/CODE_QUALITY.md`](docs/CODE_QUALITY.md) for development setup.\n\n---\n\n## ⚖️ License\n\n[AGPL-3.0-or-later](LICENSE)\n\n---\n\n\u003cp align=\"center\"\u003e\n  Made with ❤️ by \u003ca href=\"https://github.com/xenups\"\u003eXenups\u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxenups%2Fxenray","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxenups%2Fxenray","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxenups%2Fxenray/lists"}