MohammadBahemmat/V2ray-Collector
MohammadBahemmat/V2ray-Collector has 94 GitHub stars and 82 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-16 20:13 UTC. Last push 2026-11-15.
Measured star growth
- in 24h
- 0
- in 7 days
- Update delayed
- in 15 days
- Update delayed
- in 1 month
- Update delayed
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
💠جمعآوری خودکار و رایگان کانفیگهای V2Ray از گیتهاب و تلگرام (بدون API). آپدیت هر ۱۵ دقیقه با GitHub Actions. خروجی تفکیکشده بر اساس پروتکل. 💠Automated & free collector for V2Ray configs from GitHub repos & Telegram channels (no API needed). Updates every 15min via GitHub Actions. Split output by protocol.
ProductivityREADME.EN.md
Original🚀 V2Ray Config Collector — Free Automated Proxy Subscription
An intelligent, dependency-free, and highly optimized collector for automated harvesting of V2Ray configs and similar protocols.
This project leverages GitHub repositories and public Telegram channels simultaneously (without needing any API, bot, or phone number) to provide the most powerful source of free configs. All processes run fully automatically on GitHub Actions.
What sets this project apart from other collectors is its unified architecture, intelligent Rate Limit management with dual tokens, and always-fresh, categorized outputs.
✨ Distinctive Features
| Feature | Description |
|---|---|
| 🎯 Dual Collection (GitHub + Telegram) | Intelligent scanning of GitHub repositories and fetching of public Telegram channels (t.me/s) without any dependency on API, bot, or phone number. Both sources are merged into a shared database. |
| 🗂️ Categorized Outputs | In addition to the comprehensive all_servers.txt, configs are automatically categorized by protocol (vmess_servers.txt, vless_servers.txt, etc.) and saved. |
| 💾 Smart Deduplication & Storage | Only new configs are added to the file in each run. No duplicate configs exist in the output, and file growth is completely controlled. |
| 🪙 Dual-Token Rate Limit Management | Using a classic PAT and a GitHub App, Core request limits are cyclically managed, and the script never hits a 403 error. |
| ⏱️ 15-Minute Time Window | Only repositories pushed to in the last 15 minutes are scanned (adjustable via MAX_AGE_HOURS). The latest posts are fetched from Telegram as well. |
| 🌿 Branch Discovery with Persistent Memory | Newly discovered branches are saved in discovered_branches.json and directly checked in subsequent runs. |
| 🧩 Checkpoint (Resume After Any Stop) | Even if power goes out or Rate Limit runs out, the next run will continue exactly from where it stopped. |
| 🗃️ SQLite Database | All unique configs are stored in a local database (collector.db), preventing duplicate URL processing. |
| 🔒 No Telegram API Dependency | Unlike 90% of similar projects, this collector does not require any API, bot, or phone number for Telegram – it uses the web version (t.me/s). |
| 🚀 Completely Automated & Free | The whole system runs on a single free GitHub Actions workflow, with no external server needed. |
📦 Requirements
- Git installed on your system (to clone the repository)
- Python 3.10 or higher
-
Libraries listed in
requirements.txt:pip install -r config/requirements.txt
-
One of the following for GitHub authentication:
- A Personal Access Token (classic) with
repoandworkflowscopes (for GitHub scanning), or - A GitHub App installed on the repository (for higher security)
- A Personal Access Token (classic) with
⚙️ Configuration
All key parameters are adjustable in the CONFIG_DEFAULTS dictionary inside collector_git.py. The most important ones are:
| Parameter | Default Value | Description |
|---|---|---|
MAX_AGE_HOURS | 0.25 | Only scan repositories that have been pushed to in the last 15 minutes |
TARGET_CORE_CONSUMPTION | 5000 | Maximum allowed Core API calls (for automatic stop) |
MAX_FILE_BYTES | 10 * 1024 * 1024 | Maximum downloadable file size (10 MB) |
GENERAL_CONCURRENT_REQUESTS | 80 | Number of simultaneous file downloads |
MAX_RECURSION_DEPTH | 0 | Depth of following subscription links |
CHECKPOINT_FILE | checkpoint.json | Progress save file |
DISCOVERED_BRANCHES_FILE | discovered_branches.json | File to store newly discovered branches |
GH_TOKEN → Personal Access Token (classic) GH_APP_ID → Your GitHub App ID GH_APP_PRIVATE_KEY → Private key of your GitHub App

🧩 Quick Start
If you want to copy and run this project for yourself:
- Fork the repository (use the Fork button at the top of the GitHub page)
- Clone the forked repository:
git clone https://github.com/YOUR_USERNAME/V2ray-Collector.git cd V2ray-Collector
- Install Python dependencies:
pip install -r config/requirements.txt
- Create a
.envfile with your GitHub token, following the template inconfig/.env.example. - Fill
data/channels.txtwith the Telegram channels you want to monitor. - Run the collector once manually to test everything:
python src/collector_git.py
🚀 Manual Execution
To run the GitHub collector alone (without Telegram), simply execute the following command in your terminal:
python src/collector_git.py
To run the Telegram collector alone:
python src/telegram_collector.py
- First run (with empty database) may take 10 to 15 minutes.
- Subsequent runs are much faster due to the populated database.
🤖 Automated Execution with GitHub Actions
1. Workflow File
The project runs by default using a YAML file at .github/workflows/collector.yml which:
- Starts via workflow_dispatch (manual or chained execution) and automatically triggers the next run after completion.
- First fetches new configs from Telegram.
- Then scans GitHub repositories.
- Uses dual tokens to distribute Rate Limit pressure.
- Finally merges, categorizes, and saves the outputs into the repository.
2. Retrieving Output Files
After the first successful run, you can use the links at the top of this page to download the files. These files can be directly loaded into your V2Ray client (such as v2rayN, Nekobox, or Hiddify).
3. Adding Telegram Channels
The file data/channels.txt maintains the list of public Telegram channels (one identifier per line, without @). To add a new channel, simply insert its identifier on a new line.
📁 Output Files
All files are updated on every run and contain only unique, new configs. If a file becomes too large, you can use the split versions instead.
🗂️ Project Structure
. ├── .github/ │ └── workflows/ │ ├── collector.yml # Main workflow (unified automatic execution) │ └── cleaner_temp.yml # Temporary workflow for cleaning Telegram channels │ ├── src/ │ ├── collector_git.py # Main GitHub collector script │ ├── telegram_collector.py # Telegram collector script (no API) │ ├── split_links.py # Split joined links │ ├── dedup_configs.py # Intelligent deduplication │ ├── rebuild_protocols.py # Rebuild protocol files from cleaned all_servers.txt │ └── channel_cleaner.py # Helper script for cleaning Telegram channels │ ├── config/ │ ├── requirements.txt # Python dependencies │ ├── .gitignore # Ignored files │ └── .env.example # Sample environment variables file │ ├── data/ # Data and report files │ ├── channels.txt # Telegram channel list (input) │ ├── channel_report.txt # Report of configs extracted per channel │ ├── checkpoint.json # Progress save file (Checkpoint) │ ├── discovered_branches.json # Newly discovered branches │ ├── repo_report.txt # Report of configs extracted per GitHub repository │ ├── token_state.txt # Token rotation counter │ ├── channels_cleaned.txt # (generated) Cleaned list of valid channels │ ├── last_message_id.json # (generated) last message_id for channels │ └── invalid_channels.txt # (generated) List of invalid channels │ ├── servers/ # Split protocol output files │ ├── vmess_servers.txt # VMess configs │ ├── vless_servers.txt # VLESS configs │ ├── trojan_servers.txt # Trojan configs │ ├── ss_servers.txt # Shadowsocks configs │ ├── ssr_servers.txt # SSR configs │ ├── hysteria_servers.txt # Hysteria configs │ ├── hysteria2_servers.txt # Hysteria2 configs │ ├── tuic_servers.txt # TUIC configs │ ├── socks_servers.txt # SOCKS configs │ └── socks5_servers.txt # SOCKS5 configs │ ├── for Developers/ # Full and old versions for developers │ └── collector_git_Fullversion │ └── channels_Fullversion.txt │ ├── line.gif # animated split for README ├── all_servers.txt # All unique new configs per run (GitHub + Telegram) ├── README.md # Persian documentation └── README.EN.md # English documentation
📊 Comparison with Other Well-Known GitHub Collectors
After examining dozens of prominent projects on GitHub, the table below shows the key differences. The names of notable projects in each category are also listed at the end.
| Criterion | This Project | Other Projects |
|---|---|---|
| Collection Source | GitHub + Telegram (no API) | Mostly only one of the two |
| Rate Limit Management | Dual tokens (PAT + App) | Basic or single-token |
| Categorized Output | ✅ Yes | ❌ Often a single general file |
| Smart Deduplication | ✅ Yes (no duplicates) | ❌ Complete rewrite |
| Checkpoint (Resume after stop) | ✅ Yes | ❌ Not seen in any project |
| SQLite Database | ✅ Yes | ❌ Mostly plain text files |
| Telegram Collection Without API | ✅ (via t.me/s) | ❌ Requires Telethon/bot |
| Branch Discovery | ✅ Yes | ❌ |
| Stop at Core Limit | ✅ Yes | ❌ No |
| Free Execution on Actions | ✅ Yes | ✅ Yes |
🔍 Notable Projects by Category
| Category | Project Name | Brief Description |
|---|---|---|
| GitHub Collectors |
mahdibland/V2RayAggregator swileran/v2ray-config-collector MahanKenway/Freedom-V2Ray |
Well-known repositories that collect only from GitHub |
| Telegram Collectors |
Surfboardv2ray/TGParse Kolandone/v2raycollector denxv/TGV2RayScraper MhdiTaheri/V2rayCollector |
Projects that collect only from Telegram channels |
| Both (GitHub + Telegram) |
wzdnzd/aggregator SoroushImanian/BlackKnight |
Projects that use both sources, but usually need an API for Telegram |
❗ Common Errors and Solutions
Error: Resource not accessible by integration
This error usually occurs because the classic token lacks the workflow scope. Make sure your GH_TOKEN has both repo and workflow permissions.
Error: 403 / 429 (Rate limit) in log
The script automatically sleeps and retries. This is normal. If it happens frequently, increase MAX_AGE_HOURS.
Telegram channels not found
- Make sure the
data/channels.txtfile exists in thedatafolder. - Identifiers must be public.
- You can use the
Temp Channel Cleanerworkflow to check channel health.
Output file does not update
- Ensure that the Secrets have the correct names.
- Check that the
Commit and push updated filesstep in the Workflow ran without errors.
🙏 Contribution & Development
Suggestions, bug reports, new repositories to add to the MANUAL_REPOS_TO_SCAN list, or additional Telegram channels for the channels.txt file can be shared via Pull Request or Issue.
For developers: please test your changes locally before submitting them.
💡 Acknowledgements
The idea of using t.me/s to access Telegram channels without an API was inspired by open-source projects such as Kolandone/v2raycollector and MhdiTaheri/V2rayCollector. We are grateful to all developers who share their knowledge.
📄 License
This project is released under the MIT license. Use, modification, and distribution are free.