English | 繁體中文
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.
- Overview & Highlights
- System Architecture
- Directory Structure
- Prerequisites
- Configuration & Secret Management
- Step-by-Step Deployment Guide
- Bot Commands & Usage
- Supported Global Regions
- Security & Cost Architecture
- Trademarks & License Notices
- 💸 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-microSpot/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
/delanytime to instantly delete compute instances, release external IP leases, and prevent runaway cloud billing.
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)
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
- Google Cloud Platform Account: An active GCP account with billing enabled.
- Google Cloud SDK (
gcloudCLI): Installed locally or accessed via Google Cloud Shell. - Telegram Account:
- Create a bot and receive an API token via @BotFather.
- Find your numerical Telegram User ID using @userinfobot.
- WireGuard Client: Installed on your mobile phone or laptop (WireGuard Installation).
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. |
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.comReplace 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=-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-serverDeploy 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=60sNote: 512MB memory allocation is chosen to ensure smooth Python dependency imports without triggering OOM crashes.
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}"| 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. |
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 |
- RAM Swap Safeguard:
f1-microinstances 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.
This project is open-source software licensed under the MIT License.
- 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.