Skip to content

About

A lightweight, serverless telegram bot that deploys a disposable OpenVPN server on Google Cloud Platform (GCP) on demand.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

32 Commits

Folders and files

Repository files navigation

English | 繁體中文

🛡️ GCP-Telegram-VPN-Bot

Python Version Google Cloud Platform Telegram Bot API Protocol License: MIT

A cost-optimized, fully serverless Telegram Bot that provisions disposable, high-performance VPN servers on Google Cloud Platform (GCP) on demand. Designed for personal digital privacy and ephemeral tunneling with zero idle hosting costs.


Table of Contents


Overview & Highlights

  • 💸 Zero Idle Cost: Built entirely upon GCP Cloud Functions (2nd Gen) scaling down to 0 instances when idle. You pay $0 when no VPN is running.
  • ⚡ Spot VM Economics: Automatically spins up Google Compute Engine f1-micro Spot/Preemptible instances (~$0.004/hour), reducing compute expenses by up to 80%.
  • 📱 Interactive In-Chat UI: Clean Telegram Inline Keyboards for one-tap deployment region selection and multi-peer configuration.
  • 📲 Instant QR Code Delivery: Automatically generates client configuration profiles and renders crisp QR codes sent directly to your Telegram chat for instant mobile camera import.
  • 🔐 Hardened Zero-Trust Security: Multi-tier access control via Google Secret Manager, Telegram User ID whitelisting, and strict ingress firewall policies.
  • 🧹 One-Click Teardown: Issue /del anytime to instantly delete compute instances, release external IP leases, and prevent runaway cloud billing.

System Architecture

sequenceDiagram
    autonumber
    actor User as User (Telegram App)
    participant TG as Telegram Bot API
    participant GCF as Cloud Function 2nd Gen (deploy_vpn)
    participant SM as Google Secret Manager
    participant GCE as Compute Engine (Instances API)
    participant VM as Disposable VM (f1-micro Spot)

    User->>TG: /new command
    TG->>GCF: Webhook (HTTP POST)
    GCF->>SM: Validate User ID & fetch Bot Token
    GCF-->>TG: Send Region Selection Inline Keyboard
    User->>TG: Selects "Taiwan" / "Tokyo"
    TG->>GCF: Callback Query
    GCF->>GCE: Insert VM Instance with Custom Startup Script
    Note over VM: VM Boots Debian 11/12<br/>1. Configures 1GB Swapfile<br/>2. Enables IPv4 Forwarding<br/>3. Installs WireGuard & qrencode<br/>4. Generates Keys & Client QR
    VM->>TG: Posts QR Code PNG & .conf file directly via Bot API
    TG->>User: Displays QR Code in chat
    User->>VM: Scans QR code & establishes VPN Tunnel (UDP 51820)
    Note over User,VM: Encrypted Tunnel Active
    User->>TG: /del command
    TG->>GCF: Webhook request
    GCF->>GCE: Delete VM Instance (Zero lingering costs)
Loading

Directory Structure

GCP-Telegram-VPN-Bot/
├── assets/
│   └── demo_interaction.png # Architectural demo & screenshot assets
├── .gitignore               # Git exclusions (credentials, caches, virtualenvs)
├── AGENTS.md                # AI Agent guidelines and project context
├── main.py                  # Serverless function webhook handler & VM orchestrator
├── README.md                # English documentation
├── README_zh.md             # Traditional Chinese documentation
└── requirements.txt         # Python runtime dependencies

Prerequisites

  1. Google Cloud Platform Account: An active GCP account with billing enabled.
  2. Google Cloud SDK (gcloud CLI): Installed locally or accessed via Google Cloud Shell.
  3. Telegram Account:
    • Create a bot and receive an API token via @BotFather.
    • Find your numerical Telegram User ID using @userinfobot.
  4. WireGuard Client: Installed on your mobile phone or laptop (WireGuard Installation).

Configuration & Secret Management

The bot stores sensitive credentials in Google Secret Manager to keep the codebase completely credential-free.

Secret / Environment Name Type Example / Format Purpose
TELEGRAM_BOT_TOKEN Secret Manager 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ Telegram Bot token issued by BotFather.
AUTHORIZED_USER_ID Secret Manager 123456789,987654321 Comma-delimited list of numerical Telegram IDs allowed to trigger actions.
GCP_PROJECT_ID Environment Var my-vpn-project-45678 Target Google Cloud project identifier.
vpn-server Network Tag N/A Target compute network tag applied to VPN VMs for firewall binding.

Step-by-Step Deployment Guide

1. Enable Google Cloud APIs

Execute in Cloud Shell or your terminal:

gcloud services enable \
  cloudfunctions.googleapis.com \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  compute.googleapis.com \
  secretmanager.googleapis.com

2. Store Secrets in Google Secret Manager

Replace placeholders with your real values:

# Store Telegram Bot Token
printf "YOUR_TELEGRAM_BOT_TOKEN" | gcloud secrets create TELEGRAM_BOT_TOKEN --data-file=-

# Store Authorized User ID(s)
printf "YOUR_NUMERIC_TELEGRAM_USER_ID" | gcloud secrets create AUTHORIZED_USER_ID --data-file=-

3. Configure Cloud IAM Permissions & Firewall

The Cloud Function's default service account requires permissions to read secrets and provision Compute Engine instances:

PROJECT_ID=$(gcloud config get-value project)
PROJECT_NUMBER=$(gcloud projects describe "$PROJECT_ID" --format="value(projectNumber)")
SERVICE_ACCOUNT="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"

# Grant Secret Manager read access
gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member "serviceAccount:${SERVICE_ACCOUNT}" \
  --role "roles/secretmanager.secretAccessor"

# Grant Compute Engine admin rights for instance provisioning & teardown
gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member "serviceAccount:${SERVICE_ACCOUNT}" \
  --role "roles/compute.admin"

# Create firewall rule allowing incoming VPN tunnel traffic
gcloud compute firewall-rules create allow-wireguard-vpn \
  --direction=INGRESS \
  --priority=1000 \
  --network=default \
  --action=ALLOW \
  --rules=udp:51820 \
  --source-ranges=0.0.0.0/0 \
  --target-tags=vpn-server

4. Deploy Google Cloud Function (2nd Gen)

Deploy main.py using Cloud Functions 2nd Gen (backed by Cloud Run):

gcloud functions deploy vpn-bot \
  --gen2 \
  --runtime=python311 \
  --region=asia-northeast1 \
  --source=. \
  --entry-point=deploy_vpn \
  --trigger-http \
  --allow-unauthenticated \
  --set-env-vars GCP_PROJECT_ID=$(gcloud config get-value project) \
  --memory=512MB \
  --timeout=60s

Note: 512MB memory allocation is chosen to ensure smooth Python dependency imports without triggering OOM crashes.


5. Register Telegram Webhook

Retrieve the deployed Cloud Function endpoint URL and register it with the Telegram Bot API:

FUNCTION_URL=$(gcloud functions describe vpn-bot --gen2 --region=asia-northeast1 --format="value(serviceConfig.uri)")
BOT_TOKEN=$(gcloud secrets versions access latest --secret=TELEGRAM_BOT_TOKEN)

curl -s "https://api.telegram.org/bot${BOT_TOKEN}/setWebhook?url=${FUNCTION_URL}"

Bot Commands & Usage

Command Action Description
/start Welcome Screen Greets authorized users and presents the command summary.
/new Launch Server Displays an inline region keyboard. Selecting a zone initiates VM creation.
/status Query Active Nodes Lists all currently active VPN instances, public IPs, and running uptime.
/del Immediate Teardown Terminates and purges all provisioned VPN instances to halt billing.
/log System Diagnostics Displays project runtime diagnostics and instance counts.

Supported Global Regions

The bot supports deploying to any of the following Google Cloud zones with a single tap:

Location Region / Zone Best For
🇹🇼 Taiwan asia-east1-b Ultra-low latency East Asian routing
🇯🇵 Tokyo asia-northeast1-b High-bandwidth Japanese media & services
🇸🇬 Singapore asia-southeast1-b Southeast Asian regional hub
🇺🇸 Iowa us-central1-a US Central backbone connectivity
🇺🇸 Oregon us-west1-b US West Coast trans-Pacific transit
🇺🇸 S. Carolina us-east1-b US East Coast low latency
🇬🇧 London europe-west2-c UK & European Union testing
🇩🇪 Frankfurt europe-west3-c Central European routing hub
🇳🇱 Netherlands europe-west4-a Western European low-latency access

Security & Cost Architecture

  • RAM Swap Safeguard: f1-micro instances provide ~600MB RAM. The provisioning startup script initializes a 1GB swapfile on the root disk before package installation, preventing Linux Out-Of-Memory kernel kills.
  • Strict Network Whitelist: Unauthenticated Telegram users receive an immediate access denied notification; no cloud resources can be spent by third parties.
  • Disposable Identity: No logs or credentials remain after VM termination.

Trademarks & License Notices

Source Code License

This project is open-source software licensed under the MIT License.

Trademark Attributions

  • Google Cloud Platform®, GCP®, and Compute Engine™ are trademarks or registered trademarks of Google LLC.
  • Telegram® is a registered trademark of Telegram FZ-LLC.
  • WireGuard® is a registered trademark of Jason A. Donenfeld.
  • OpenVPN® is a registered trademark of OpenVPN Inc.
  • All other product names, logos, and brands are property of their respective owners.

About

A lightweight, serverless telegram bot that deploys a disposable OpenVPN server on Google Cloud Platform (GCP) on demand.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Contributors

Languages