Skip to content
Projects

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.

How these counts are measured

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.

Productivity

README.EN.md

Original
Collector Status

🚀 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.

separator

✨ Distinctive Features

FeatureDescription
🎯 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.
separator

📦 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 repo and workflow scopes (for GitHub scanning), or
    • A GitHub App installed on the repository (for higher security)
separator

⚙️ Configuration

All key parameters are adjustable in the CONFIG_DEFAULTS dictionary inside collector_git.py. The most important ones are:

ParameterDefault ValueDescription
MAX_AGE_HOURS0.25Only scan repositories that have been pushed to in the last 15 minutes
TARGET_CORE_CONSUMPTION5000Maximum allowed Core API calls (for automatic stop)
MAX_FILE_BYTES10 * 1024 * 1024Maximum downloadable file size (10 MB)
GENERAL_CONCURRENT_REQUESTS80Number of simultaneous file downloads
MAX_RECURSION_DEPTH0Depth of following subscription links
CHECKPOINT_FILEcheckpoint.jsonProgress save file
DISCOVERED_BRANCHES_FILEdiscovered_branches.jsonFile to store newly discovered branches
🔐 Setting Secrets on GitHub: To use dual tokens, define these values in Settings > Secrets and variables > Actions:
GH_TOKEN              → Personal Access Token (classic)
GH_APP_ID             → Your GitHub App ID
GH_APP_PRIVATE_KEY    → Private key of your GitHub App
separator

🧩 Quick Start

If you want to copy and run this project for yourself:

  1. Fork the repository (use the Fork button at the top of the GitHub page)
  2. Clone the forked repository:
    git clone https://github.com/YOUR_USERNAME/V2ray-Collector.git
    cd V2ray-Collector
  3. Install Python dependencies:
    pip install -r config/requirements.txt
  4. Create a .env file with your GitHub token, following the template in config/.env.example.
  5. Fill data/channels.txt with the Telegram channels you want to monitor.
  6. Run the collector once manually to test everything:
    python src/collector_git.py
separator

🚀 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.
separator

🤖 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.

separator

📁 Output Files

FileDescriptionDirect Link
all_servers.txt All unique new configs per run (GitHub + Telegram) All Configs
vmess_servers.txt VMess configs only VMess
vless_servers.txt VLESS configs only VLESS
trojan_servers.txt Trojan configs only Trojan
hysteria_servers.txt Hysteria configs only Hysteria
hysteria2_servers.txt Hysteria2 configs only Hysteria2
tuic_servers.txt TUIC configs only TUIC
ss_servers.txt Shadowsocks configs only Shadowsocks
ssr_servers.txt SSR configs only SSR
socks_servers.txt SOCKS configs only SOCKS
socks5_servers.txt SOCKS5 configs only SOCKS5

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.

separator

🗂️ 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
separator

📊 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.

CriterionThis ProjectOther Projects
Collection SourceGitHub + Telegram (no API)Mostly only one of the two
Rate Limit ManagementDual 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

CategoryProject NameBrief 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
separator

❗ 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.txt file exists in the data folder.
  • Identifiers must be public.
  • You can use the Temp Channel Cleaner workflow to check channel health.
Output file does not update
  • Ensure that the Secrets have the correct names.
  • Check that the Commit and push updated files step in the Workflow ran without errors.
separator

🙏 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.

separator

💡 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.

separator

📄 License

This project is released under the MIT license. Use, modification, and distribution are free.