English | فارسی | 🚀 راهاندازی سریع
BatProxy is a sophisticated, high-performance proxy solution that combines the power of Cloudflare Workers with an intelligent Python client. It creates a resilient, self-healing tunnel network that automatically adapts to network conditions, provides automatic failover, and delivers exceptional throughput through intelligent request routing and data coalescing.
⚠️ Important Security Note: For enhanced privacy, we strongly recommend using disposable email addresses (such as ProtonMail or temporary email services) when creating Cloudflare accounts for this project.
- Banner & Introduction
- Key Features
- Architecture Diagram
- How It Works
- Technical Deep Dive
- Monitoring & Dashboards
- Prerequisites & Requirements
- Installation Guide
- Configuration
- Usage Examples
- Troubleshooting Guide
- Frequently Asked Questions
╔════════════════════════════════════════════════════════════════╗
║ BATPROXY ║
║ Intelligent Proxy Tunnel for the Modern Web ║
╠════════════════════════════════════════════════════════════════╣
║ HTTP/HTTPS │ SOCKS5 │ Auto-Failover │ Load Balancing ║
║ Circuit Breaker │ Health Checks │ Real-time Dashboard ║
╚════════════════════════════════════════════════════════════════╝
BatProxy is not just another proxy tool—it's a complete traffic routing ecosystem designed for reliability, performance, and ease of use. Whether you're a developer needing to bypass geographic restrictions, a security researcher testing network configurations, or simply someone who values privacy, BatProxy provides enterprise-grade features in a lightweight, easy-to-deploy package.
The system leverages Cloudflare's global edge network to provide low-latency connections worldwide, while the intelligent Python client ensures optimal worker selection, automatic recovery from failures, and seamless failover between multiple workers.
- Dual Protocol Support: Full-featured HTTP/HTTPS proxy with CONNECT method support for TLS tunnels, plus complete SOCKS5 protocol implementation
- Intelligent Worker Selection: Multi-factor scoring system that considers success rates, latency, active connections, and recent failure history
- Automatic Circuit Breaking: Workers that become unhealthy are temporarily excluded, with exponential backoff cooldown periods
- Zero-Downtime Failover: Requests automatically retry through alternative workers when failures occur
- Idempotent Request Retry: Automatic retry for GET, HEAD, and other idempotent methods with transparent failover
- Data Coalescing: Reduces WebSocket message overhead by batching small packets (configurable timing and size thresholds)
- Connection Pooling: Efficient reuse of worker connections with configurable maximum concurrent connections
- Asynchronous I/O: Built on Python's
asynciowith optionaluvloopintegration for maximum performance - Buffer Management: Intelligent buffering with configurable limits to prevent memory exhaustion
- Real-time Health Checks: Continuous monitoring of worker health through dedicated ping/pong mechanism
- EWMA-Based Metrics: Exponentially Weighted Moving Average for success rates and latency, providing smooth, responsive scoring
- Destination Cache: Speeds up repeated connections by remembering which worker last handled a destination
- Comprehensive Dashboards: Both terminal (with rich colors) and web-based dashboards with real-time metrics
- JSON API: Programmatic access to all metrics for custom monitoring solutions
- HMAC Authentication: Secure challenge-response authentication using HMAC-SHA256
- Replay Attack Protection: Nonce-based system with configurable time windows
- Timestamp Validation: Prevents clock-skew attacks and ensures freshness
- Configurable Secrets: Environment variable-based password management
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ CLIENT APPLICATIONS │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Browser │ │ curl │ │ wget │ │ git │ │ Docker │ ... │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │ │ │
│ └─────────────┴─────────────┴─────────────┴─────────────┘ │
│ │ │
│ ┌────────▼────────┐ │
│ │ HTTP/SOCKS5 │ │
│ │ Proxy Server │ │
│ │ (127.0.0.1:1080)│ │
│ └────────┬────────┘ │
│ │ │
│ ┌─────────────────┼─────────────────┐ │
│ │ │ │ │
│ ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐ │
│ │ Worker 1 │ │ Worker 2 │ │ Worker N │ │
│ │ Scoring │ │ Scoring │ │ Scoring │ │
│ │ Health │ │ Health │ │ Health │ │
│ │ Checks │ │ Checks │ │ Checks │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
│ └─────────────────┼─────────────────┘ │
│ │ │
│ ┌──────────▼──────────┐ │
│ │ Cloudflare Edge │ │
│ │ Network (Workers) │ │
│ └──────────┬──────────┘ │
│ │ │
└─────────────────────────────────────┼───────────────────────────────────────────────┘
│
┌────────────┼────────────┐
│ │ │
┌──────▼──────┐ ┌──▼───┐ ┌─────▼─────┐
│ Target │ │Target│ │ Target │
│ Server 1 │ │Srv 2 │ │ Server 3 │
│ (example) │ │ │ │ │
└─────────────┘ └──────┘ └───────────┘
The connection establishment process is a multi-step handshake designed for security and reliability:
Client (Python) Cloudflare Worker
│ │
│ 1. Establish WebSocket │
│───────────────────────────────────►│
│ │
│ 2. Send Handshake (JSON) │
│ { │
│ "hostname": "example.com", │
│ "port": 443, │
│ "auth": { │
│ "ts": "1712345678", │
│ "nonce": "a1b2c3d4...", │
│ "sig": "e5a4d3c2..." │
│ } │
│ } │
│───────────────────────────────────►│
│ │
│ 3. Verify Auth │
│ - Check timestamp│
│ - Validate HMAC │
│ - Verify nonce │
│ │
│ 4. Response (Status) │
│ {"status": "connected"} │
│◄───────────────────────────────────│
│ │
│ 5. Raw TCP Data Relay Starts │
│ (Binary WebSocket Frames) │
│◄══════════════════════════════════►│
│ │
Detailed Steps:
- WebSocket Upgrade: The client initiates a WebSocket connection to the worker's URL (e.g.,
wss://your-worker.workers.dev). - Handshake Message: The client constructs a JSON payload containing:
hostname: Target server addressport: Target server portauth: Authentication object with timestamp, nonce, and HMAC signature
- Server Verification: The worker performs three critical checks:
- Timestamp Validity: Ensures the
tsis withinAUTH_WINDOW(default 30 seconds) of current time - HMAC Verification: Recomputes the signature using the shared secret
- Nonce Uniqueness: Ensures the nonce hasn't been used in the current time window (prevents replay attacks)
- Timestamp Validity: Ensures the
- Connection Establishment: If all checks pass, the worker connects to the target server and returns a success response
- Data Relay: From this point forward, all WebSocket messages are raw TCP data, efficiently relayed between client and target
The data relay mechanism is optimized for both throughput and latency:
Client → Worker Direction:
- Data from applications is read from the local TCP socket
- The client buffers data and sends it in configurable chunks (up to
WRITE_BUFFER_MAX) - WebSocket frames are sent with minimal overhead
Worker → Client Direction:
- The worker reads data from the target server
- Coalescing Algorithm:
- Data is added to an internal buffer
- A timer (
COALESCE_MS, default 4ms) is started - If the buffer reaches
COALESCE_MAX(default 65KB), data is sent immediately - If the timer expires, any buffered data is sent
- This reduces WebSocket frame overhead while maintaining low latency
Benefits of Coalescing:
- Reduces WebSocket message count by up to 90% for small packets
- Improves throughput for bulk data transfers
- Maintains low latency for interactive protocols
BatProxy handles HTTP CONNECT method (used for HTTPS, WebSockets, and other TLS tunnels):
Browser/Client BatProxy Client Worker Target Server
│ │ │ │
│ 1. CONNECT example.com:443 │ │
│───────────────────────►│ │ │
│ │ │ │
│ │ 2. Select Worker │ │
│ │ 3. Handshake │ │
│ │───────────────────►│ │
│ │ │ │
│ │ 4. Connected │ │
│ │◄───────────────────│ │
│ │ │ │
│ 5. 200 OK │ │ │
│◄───────────────────────│ │ │
│ │ │ │
│ 6. TLS Tunnel Established (Bidirectional Relay) │
│◄══════════════════════►│◄══════════════════►│◄════════════════════►│
Process Flow:
- Client sends HTTP CONNECT request to BatProxy
- BatProxy selects the healthiest worker using the scoring algorithm
- Worker handshake and authentication complete
- Worker establishes TCP connection to the target
- BatProxy responds with 200 Connection Established
- All subsequent data is transparently relayed through the tunnel
The SOCKS5 protocol implementation supports all standard features:
Browser/Client BatProxy Client Worker Target Server
│ │ │ │
│ 1. SOCKS5 Handshake │ │ │
│───────────────────────►│ │ │
│ 2. Auth Method (NoAuth)│ │ │
│◄───────────────────────│ │ │
│ │ │ │
│ 3. CONNECT Request │ │ │
│ (host, port) │ │ │
│───────────────────────►│ │ │
│ │ │ │
│ │ 4. Select Worker │ │
│ │ 5. Handshake │ │
│ │───────────────────►│ │
│ │ │ │
│ │ 6. Connected │ │
│ │◄───────────────────│ │
│ │ │ │
│ 7. SOCKS5 Response (Success) │ │
│◄───────────────────────│ │ │
│ │ │ │
│ 8. Bidirectional Data Relay │ │
│◄══════════════════════►│◄══════════════════►│◄════════════════════►│
Supported SOCKS5 Features:
CONNECTcommand (TCP tunneling)- Domain name resolution (ATYP=0x03)
- IPv4 and IPv6 addressing
- No authentication (username/password supported via extension)
The worker selection algorithm uses a sophisticated scoring system to choose the optimal worker:
def calculate_score(worker_state):
# Base success rate (EWMA)
score = worker_state.ewma_success
# RTT penalty (lower is better)
rtt_penalty = (worker_state.ewma_rtt or 200.0) / 10.0
score -= rtt_penalty
# Slow streak penalty
if worker_state.slow_streak >= 3:
score -= 20.0
# Availability penalty
if worker_state.state == "open" and cooldown_remaining > 0:
return -1.0 # Exclude from selection
# Load penalty
if worker_state.active >= max_connections:
score -= 50.0
return scoreScoring Factors:
| Factor | Weight | Description |
|---|---|---|
| Success Rate (EWMA) | High | Weighted average of recent successes, α=0.35 |
| RTT (EWMA) | Medium | Weighted average of connection latency, α=0.35 |
| Slow Streak | Medium | Consecutive slow connections (>600ms) |
| Active Connections | Low | Current load on the worker |
| Cooldown Status | Critical | Workers in cooldown are excluded |
Selection Process:
- Filter out workers in cooldown or at capacity
- Calculate score for each remaining worker
- Sort by score (highest first)
- Select the top-scoring worker for the request
The circuit breaker pattern prevents cascading failures:
Worker States:
┌─────────┐
│ CLOSED │ ← Normal operation (successful requests)
└────┬────┘
│ Consecutive failures >= 3
▼
┌─────────┐
│HALF-OPEN│ ← Probationary state (limited retries)
└────┬────┘
│ Additional failure
▼
┌─────────┐
│ OPEN │ ← Cooldown period (excluded from selection)
└────┬────┘
│ Cooldown expires / Health check success
▼
┌─────────┐
│HALF-OPEN│ ← Retry with one request
└────┬────┘
│ Success
▼
┌─────────┐
│ CLOSED │ ← Full recovery
└─────────┘
Transition Rules:
- CLOSED → HALF-OPEN: After 3 consecutive failures
- HALF-OPEN → OPEN: After another failure (cooldown begins)
- OPEN → HALF-OPEN: Cooldown timer expires or health check succeeds
- HALF-OPEN → CLOSED: A single successful request
Cooldown Calculation:
cooldown = min(
COOLDOWN_BASE * (2 ** (consec_failures - HALF_OPEN_AFTER_FAILS)),
COOLDOWN_MAX
)- Starts at 5 seconds
- Doubles with each consecutive failure
- Caps at 120 seconds
The background health check system continuously monitors worker health:
┌─────────────────────────────────────────────────────────────────┐
│ Health Check Loop │
│ (Every HEALTH_CHECK_INTERVAL) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 1. For each worker in "open" state: │
│ ├── Send "ping" command with HMAC authentication │
│ ├── Wait for "pong" response (timeout: CONNECT_TIMEOUT) │
│ ├── If successful: │
│ │ ├── Update EWMA RTT │
│ │ ├── Transition state: OPEN → HALF-OPEN │
│ │ └── Decrement consecutive failure counter │
│ └── If failed: │
│ └── Keep in OPEN state (extend cooldown) │
│ │
└─────────────────────────────────────────────────────────────────┘
Health Check Features:
- Only targets workers in the OPEN state (reduces overhead)
- Uses the same authentication mechanism as regular requests
- Updates latency metrics even when no traffic is flowing
- Gradually recovers workers without risk of overwhelming them
The destination cache improves performance for repeated connections to the same target:
dest_cache = {
"example.com:443": {
"url": "wss://worker1.workers.dev",
"ts": 1712345678.0
},
"api.github.com:443": {
"url": "wss://worker2.workers.dev",
"ts": 1712345680.0
}
}Cache Benefits:
- Reduces worker selection overhead for repeated connections
- Prefers the last successful worker for a destination
- Automatic cleanup of expired entries (TTL: 600 seconds)
- Size-limited to prevent memory leaks
BatProxy implements intelligent retry logic for improved reliability:
Retry Conditions:
- Network errors (connection refused, timeout, etc.)
- Worker failures (handshake failure, authentication error)
- Circuit breaker activation
Idempotent Methods (GET, HEAD, OPTIONS, TRACE):
- Automatically retry on failure
- Each retry uses a different worker (if available)
- Up to
MAX_ATTEMPTS_PER_REQUESTretries
Non-Idempotent Methods (POST, PUT, DELETE, PATCH):
- No automatic retry (to prevent duplicate operations)
- User must handle failures manually
- Single attempt per request
Retry Flow:
1. Attempt request with best worker
2. If failed:
├── Mark worker as failed
├── Add worker to exclusion set
├── If method is idempotent and attempts < MAX_ATTEMPTS:
│ ├── Select next best worker
│ └── Go to step 1
└── Else:
└── Return error to client
The Cloudflare Worker component is written in JavaScript and runs on Cloudflare's V8-based edge runtime.
Core Functions:
-
fetch(request, env, ctx): The main entry point for all HTTP requests- Handles WebSocket upgrade requests
- Processes ping/pong commands
- Manages the entire connection lifecycle
-
verifyAuth(passwd, subject, auth): Authentication verification- Implements HMAC-SHA256 with the shared secret
- Validates timestamp within
AUTH_WINDOW - Uses
crypto.subtlefor secure HMAC computation
-
claimNonce(nonce, now): Nonce management- Stores used nonces with expiry timestamps
- Prevents replay attacks within the current time window
- Automatically prunes expired nonces
-
Data Coalescing: The worker implements intelligent buffering
queueSend(): Adds data to send bufferflushSend(): Sends all buffered data as a single WebSocket frame- Timer-based and size-based flushing
Key Implementation Details:
// WebSocket Pair Creation
const { 0: client, 1: server } = new WebSocketPair();
// TCP Connection via Cloudflare's connect API
tcpSocket = connect({ hostname, port });
// Bidirectional Piping
const reader = tcpSocket.readable.getReader();
while (true) {
const { value, done } = await reader.read();
if (done) break;
if (value) queueSend(value);
}The Python client is built on asyncio with a modular, event-driven architecture.
Core Components:
-
handle_client(reader, writer): Main entry point for client connections- Reads first byte to determine protocol (HTTP vs SOCKS5)
- Delegates to protocol-specific handlers
-
open_tunnel(hostname, port, exclude): Worker connection manager- Selects optimal worker using scoring algorithm
- Performs handshake and authentication
- Returns WebSocket connection and worker reference
-
relay(reader, writer, ws, preloaded): Data relay coordinator- Creates two concurrent tasks for bidirectional transfer
- Handles graceful shutdown and cleanup
-
pipe_local_to_ws(reader, ws): Local → Worker pipeline- Reads from local TCP socket
- Buffers data to reduce WebSocket writes
- Flushes on timeout or buffer size threshold
-
pipe_ws_to_local(ws, writer, preloaded): Worker → Local pipeline- Reads from WebSocket
- Writes to local TCP socket
- Handles initial data (preloaded response)
Event Loop Architecture:
┌─────────────────────────────────────────────────────────────┐
│ Asyncio Event Loop │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────┐ ┌────────────────┐ ┌──────────────┐ │
│ │ HTTP Handler │ │ SOCKS5 Handler │ │ HTTP Handler │ │
│ └───────┬────────┘ └───────┬────────┘ └──────┬───────┘ │
│ │ │ │ │
│ └───────────────────┼──────────────────┘ │
│ │ │
│ ┌───────────▼────────────┐ │
│ │ Tunnel Manager │ │
│ │ - Worker Selection │ │
│ │ - Connection Pool │ │
│ │ - Health Checks │ │
│ └───────────┬────────────┘ │
│ │ │
│ ┌───────────────────┼──────────────────┐ │
│ │ │ │ │
│ ┌───────▼───────┐ ┌───────▼───────┐ ┌───────▼──────┐ │
│ │ Worker 1 │ │ Worker 2 │ │ Worker N │ │
│ │ WebSocket │ │ WebSocket │ │ WebSocket │ │
│ └───────────────┘ └───────────────┘ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
The authentication system is designed to be secure against various attack vectors:
Authentication Token Generation (Client Side):
def make_token(password, subject):
# Generate timestamp (Unix epoch)
ts = str(int(time.time()))
# Create random nonce (8 bytes hex)
nonce = secrets.token_hex(8)
# Construct message: subject:timestamp:nonce
msg = f"{subject}:{ts}:{nonce}".encode()
# Compute HMAC-SHA256
sig = hmac.new(password.encode(), msg, hashlib.sha256).hexdigest()
return {"ts": ts, "nonce": nonce, "sig": sig}Verification Process (Worker Side):
┌─────────────────────────────────────────────────────────────────┐
│ Authentication Verification │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Input: password, subject, auth_token │
│ │
│ 1. Extract: ts, nonce, sig from auth_token │
│ │
│ 2. Timestamp Validation: │
│ └── current_time - ts <= AUTH_WINDOW (30s) │
│ │
│ 3. HMAC Recalculation: │
│ └── expected = HMAC-SHA256(password, subject:ts:nonce) │
│ │
│ 4. Signature Match: │
│ └── constant_time_compare(expected, sig) │
│ │
│ 5. Nonce Uniqueness: │
│ └── claimNonce(nonce, current_time) │
│ ├── Check if nonce exists in seenNonces map │
│ ├── If not, add with expiry (current_time + window) │
│ └── If exists, reject (replay attack) │
│ │
│ 6. All checks passed → Authentication successful │
│ │
└─────────────────────────────────────────────────────────────────┘
Security Properties:
- Replay Attack Protection: Nonce ensures each authentication token can only be used once
- Clock Skew Tolerance: 30-second window allows for slight time differences
- Integrity: HMAC ensures token hasn't been tampered with
- Confidentiality: No sensitive data transmitted in plaintext
BatProxy implements several optimizations for high performance:
1. Data Coalescing:
- Reduces WebSocket frame overhead by batching small packets
- Configurable time (4ms) and size (65KB) thresholds
- Can reduce message count by up to 90% for interactive traffic
2. EWMA Metrics:
- Smooths out anomalies in latency and success rate measurements
- Responsive to changes while filtering noise
- α = 0.35 for both success rate and RTT
3. Connection Pooling:
- Reuses worker connections for multiple requests
- Limits active connections per worker to prevent overload
- Graceful handling of connection limits
4. Asynchronous I/O:
- Non-blocking operations throughout
asyncioprovides high concurrency with low overhead- Optional
uvloopfor even better performance
5. Buffer Management:
- Configurable buffer limits prevent memory exhaustion
- Automatic flushing on timer or size threshold
- Proper handling of backpressure
1. Worker Security:
- All traffic is end-to-end encrypted between client and worker
- WebSocket connections use WSS (TLS) by default
- No persistent storage of sensitive data
2. Authentication Security:
- HMAC-SHA256 provides strong integrity protection
- Nonce mechanism prevents replay attacks
- Timestamp validation prevents expired token usage
3. Data Protection:
- All data is transmitted over TLS
- No logging of sensitive information (by default)
- Configurable to disable logging if needed
4. Operational Security:
- Cloudflare Workers run in isolated V8 isolates
- No shared memory between workers
- Automatic scaling and load distribution
5. Recommended Practices:
- Use strong, unique passwords (15+ characters)
- Rotate passwords periodically
- Monitor worker activity for anomalies
- Use dedicated Cloudflare accounts per deployment
- Consider additional encryption layers for sensitive data
The terminal dashboard provides real-time monitoring with colored output:
🦇 Bat Proxy listening on 127.0.0.1:1080 (engine: uvloop, workers: 3, verbose: False)
curl (HTTP) : curl -x http://127.0.0.1:1080 https://example.com
curl (SOCKS5) : curl -x socks5h://127.0.0.1:1080 https://example.com
Browser : set proxy to 127.0.0.1:1080 (HTTP or SOCKS5, all protocols)
(tip: pip install rich -> colored live dashboard)
╭────────────────────────────────────────────────────────────────────╮
│ 🦇 Bat Proxy │
├────────────────────────────────────────────────────────────────────┤
│ Active │ Total │ OK │ Failed │
│ 12 │ 1547 │ 1532 │ 15 │
├────────────────────────────────────────────────────────────────────┤
│ Workers │
├──────────┬──────────┬──────────┬──────────┬──────────┬──────────┤
│ Worker │ Status │ Conns │ RTT │ Score │ OK/Fail │
├──────────┼──────────┼──────────┼──────────┼──────────┼──────────┤
│ worker1 │ closed │ 8 │ 124ms │ 85 │ 512/5 │
│ worker2 │ half-open│ 2 │ 189ms │ 72 │ 421/8 │
│ worker3 │ open 45s │ 2 │ 345ms │ -1 │ 199/2 │
└──────────┴──────────┴──────────┴──────────┴──────────┴──────────┘
Dashboard Components:
- Summary Row: Active connections, total requests, success/failure counts
- Worker Table: Per-worker status, connections, RTT, score, and statistics
- Color Coding: Green (success), Yellow (warning), Red (failure)
The HTML dashboard provides a clean, browser-based interface:
Features:
- Auto-refresh: Updates every second
- Responsive Design: Works on desktop and mobile
- Visual Status: Color-coded badges for worker states
- Progress Bars: Visual representation of worker scores
- JSON API: Programmatic access at
/api/stats
Endpoint Structure:
{
"active": 12,
"total": 1547,
"ok": 1532,
"fail": 15,
"workers": [
{
"url": "worker1",
"status": "closed",
"cooldown": 0,
"active": 8,
"rtt": 124.5,
"score": 85.3,
"ok": 512,
"fail": 5
}
]
}- Python: 3.8 or higher
- Operating System: Linux, macOS, Windows (with WSL2 recommended)
- Network: Internet connection with WebSocket support
- Memory: Minimum 256MB RAM (1GB+ recommended)
- Storage: 100MB free space
- Account: Free Cloudflare account (Workers free tier included)
- Workers: Worker limit depends on Cloudflare plan
- Email: For enhanced privacy, use disposable email services
websocket-client
rich # Optional, for better dashboard
uvloop # Optional, for better performance
Step 1: Create Cloudflare Account
- Visit Cloudflare Workers
- Sign up with your email (consider using ProtonMail or similar service)
- Verify your email address
Step 2: Create Worker
- From the Cloudflare dashboard, navigate to "Compute" → "Workers & Pages"
- Click "Create application"
- If you don't have a domain:
- Click "Start with hello world"
- Click "Deploy"
- A subdomain will be auto-generated (e.g.,
your-name.workers.dev)
- If you have a domain:
- Select your domain from the list
- Click "Create Worker"
Step 3: Deploy Worker Code
- Click "Edit Code" (top right corner)
- Delete all default code
- Copy the code from worker/worker.js
- Paste the code into the editor
- Click "Save and Deploy"
Option 1: Using Cloudflare Dashboard
- Go to your Worker's settings
- Navigate to "Variables" or "Environment Variables"
- Add a new variable:
- Name:
PASSWD - Value: Your chosen password (e.g.,
MySecureP@ssw0rd2024!)
- Name:
- Click "Save"
Option 2: Using Wrangler CLI
# Install Wrangler
npm install -g wrangler
# Login
wrangler login
# Set secret
wrangler secret put PASSWD
# (Enter your password when prompted)
# Deploy
wrangler deploy1. Install Python 3.8+
# Ubuntu/Debian
sudo apt update
sudo apt install python3 python3-pip
# macOS (using Homebrew)
brew install python3
# Windows (using Chocolatey)
choco install python32. Clone the Repository
git clone https://github.com/batmanpriv/BatProxy.git
cd BatProxy3. Install Dependencies
# Install core dependencies
pip install -r requirements.txtThe client is configured via configx.py or environment variables.
Worker Configuration:
# configx.py
WORKERS = [
{"url": "wss://worker1.workers.dev", "password": "your_password"},
{"url": "wss://worker2.workers.dev", "password": "your_password"},
# Add more workers for redundancy
]Performance Settings:
# Connection and timeout settings
CONNECT_TIMEOUT = 6 # Seconds to wait for connection
COOLDOWN_BASE = 5 # Initial cooldown in seconds
COOLDOWN_MAX = 120 # Maximum cooldown in seconds
MAX_ATTEMPTS_PER_REQUEST = 4 # Maximum retry attempts
# Buffer and coalescing settings
WRITE_BUFFER_MAX = 65536 # 64KB buffer
WRITE_BUFFER_DELAY = 0.004 # 4ms delay
# Load balancing settings
MAX_CONN_PER_WORKER = 150 # Maximum concurrent connections
HALF_OPEN_AFTER_FAILS = 3 # Failures before circuit opens
# Cache settings
DEST_CACHE_TTL = 600 # 10 minutes cache TTL
DEST_CACHE_CLEANUP_INTERVAL = 60 # 1 minute cleanup interval
# EWMA settings (success rate)
ALPHA_SUCCESS = 0.35 # Smoothing factor for success rate
ALPHA_RTT = 0.35 # Smoothing factor for RTT
# Performance thresholds
SLOW_RTT_MS = 600 # Considered "slow" in milliseconds
SLOW_PENALTY = 20.0 # Score penalty for slow workersEnvironment Variables:
// worker.js - can be set via Cloudflare dashboard
const DEFAULT_PASSWORD = '123456'; // Fallback if PASSWD not set
const AUTH_WINDOW = 30; // Seconds
const COALESCE_MS = 4; // Milliseconds
const COALESCE_MAX = 65536; // Bytes
const MAX_HANDSHAKE_BYTES = 2048; // Bytes
const PING_TARGET_HOST = '1.1.1.1'; // Health check target
const PING_TARGET_PORT = 443; // Health check port
const MAX_NONCES = 5000; // Maximum stored nonces| Variable | Description | Default |
|---|---|---|
PASSWD |
Authentication password | 123456 |
AUTH_WINDOW |
Authentication time window (seconds) | 30 |
COALESCE_MS |
Data coalescing delay (milliseconds) | 4 |
COALESCE_MAX |
Data coalescing size limit (bytes) | 65536 |
MAX_HANDSHAKE_BYTES |
Maximum handshake size (bytes) | 2048 |
PING_TARGET_HOST |
Host for health checks | 1.1.1.1 |
PING_TARGET_PORT |
Port for health checks | 443 |
MAX_NONCES |
Maximum stored nonces | 5000 |
python batproxy.py [options]| Option | Description | Default |
|---|---|---|
-v, --verbose |
Enable verbose logging | False |
--host HOST |
Local proxy host | 127.0.0.1 |
--port PORT |
Local proxy port | 1080 |
--dashboard-host HOST |
Dashboard host | 127.0.0.1 |
--dashboard-port PORT |
Dashboard port | 8088 |
--no-web-dashboard |
Disable web dashboard | False |
Examples:
# Default configuration
python batproxy.py
# Custom proxy port with verbose logging
python batproxy.py --port 8080 -v
# Run without web dashboard
python batproxy.py --no-web-dashboard
# Custom dashboard port
python batproxy.py --dashboard-port 9090Firefox:
- Settings → Network Settings → Manual proxy configuration
- HTTP Proxy:
127.0.0.1Port:1080 - Also use for: HTTPS, SOCKS5
- Check "Proxy DNS when using SOCKS v5"
Chrome/Chromium:
# Command line
chrome --proxy-server="http://127.0.0.1:1080"
# Or via Settings → System → Open your computer's proxy settingsSystem Proxy (Ubuntu):
# Set HTTP/HTTPS proxy
export http_proxy="http://127.0.0.1:1080"
export https_proxy="http://127.0.0.1:1080"
# Set SOCKS5 proxy
export all_proxy="socks5://127.0.0.1:1080"HTTP/HTTPS Proxy:
# Basic HTTP GET
curl -x http://127.0.0.1:1080 https://example.com
# HTTP GET with headers
curl -x http://127.0.0.1:1080 -H "User-Agent: BatProxy" https://api.example.com/data
# POST request with data
curl -x http://127.0.0.1:1080 -X POST -d '{"key":"value"}' https://httpbin.org/post
# Download file through proxy
curl -x http://127.0.0.1:1080 -O https://example.com/file.zipSOCKS5 Proxy:
# Basic SOCKS5
curl -x socks5h://127.0.0.1:1080 https://example.com
# SOCKS5 with authentication (if enabled)
curl -x socks5h://user:pass@127.0.0.1:1080 https://example.com
# SOCKS5 for all protocols
curl --socks5-hostname 127.0.0.1:1080 https://example.comFor maximum reliability and performance, configure multiple workers:
# config.py
WORKERS = [
# Primary worker (US region)
{"url": "wss://us-worker.workers.dev", "password": "secure_password"},
# Backup worker (EU region)
{"url": "wss://eu-worker.workers.dev", "password": "secure_password"},
# Additional worker (Asia region)
{"url": "wss://asia-worker.workers.dev", "password": "secure_password"},
# Load balancing across multiple regions
{"url": "wss://worker1.example.com", "password": "secure_password"},
{"url": "wss://worker2.example.com", "password": "secure_password"},
{"url": "wss://worker3.example.com", "password": "secure_password"},
]For Maximum Reliability:
MAX_ATTEMPTS_PER_REQUEST = 5
CONNECT_TIMEOUT = 8
HALF_OPEN_AFTER_FAILS = 2
HEALTH_CHECK_INTERVAL = 15For Maximum Performance:
WRITE_BUFFER_MAX = 131072 # 128KB
WRITE_BUFFER_DELAY = 0.002 # 2ms
MAX_CONN_PER_WORKER = 300
COALESCE_MS = 2
COALESCE_MAX = 131072For Low Latency:
WRITE_BUFFER_DELAY = 0.001 # 1ms
WRITE_BUFFER_MAX = 8192 # 8KB
COALESCE_MS = 1
COALESCE_MAX = 81921. Connection Timeout
Error: ConnectionError: all workers failed
Solutions:
- Check your internet connection
- Verify worker URLs are correct
- Increase
CONNECT_TIMEOUTin config - Check if Cloudflare Workers are accessible
2. Authentication Failure
Error: invalid signature
Solutions:
- Verify password matches between client and worker
- Check system time synchronization (NTP)
- Ensure
PASSWDenvironment variable is set correctly - Restart worker after password change
3. WebSocket Connection Failed
Error: WebSocket connection failed
Solutions:
- Check if worker is running (visit URL in browser)
- Verify WebSocket support (check for
wss://protocol) - Check firewall settings
- Ensure Cloudflare Worker is not rate-limited
4. High Latency
Warning: Slow RTT detected
Solutions:
- Check network quality to Cloudflare edge
- Try different workers (different regions)
- Adjust
SLOW_RTT_MSthreshold - Consider using
uvloopfor better performance
5. Memory Issues
MemoryError: Unable to allocate buffer
Solutions:
- Reduce
WRITE_BUFFER_MAX - Reduce
MAX_CONN_PER_WORKER - Increase system memory limits
- Restart the client periodically
Enable Verbose Logging:
python batproxy.py -vCheck Worker Status:
# Access dashboard
curl http://127.0.0.1:8088/api/statsTest Worker Connectivity:
# Simple connectivity test
python -c "
import websockets
import asyncio
async def test():
try:
ws = await websockets.connect('wss://your-worker.workers.dev')
print('Connection successful')
await ws.close()
except Exception as e:
print(f'Connection failed: {e}')
asyncio.run(test())
"Monitor Logs:
# On Linux/macOS
tail -f /var/log/batproxy.log
# On Windows (PowerShell)
Get-Content -Path C:\batproxy\log.txt -WaitQ: What is the maximum throughput? A: The system can handle 1000+ concurrent connections with proper configuration. Throughput is typically limited by your network connection and Cloudflare's bandwidth limits.
Q: Can I use it for torrents or P2P? A: While technically possible, we recommend against it. Cloudflare Workers have usage limits, and P2P traffic may violate their terms of service.
Q: How much does it cost? A: Cloudflare Workers has a free tier with limited usage. Paid plans start at $5/month and offer higher limits.
Q: Can I run multiple clients? A: Yes, you can run multiple client instances on different ports, or share the same client across multiple applications.
Q: What happens if all workers fail? A: The client will return a 502 Bad Gateway response to the client application. All workers will go into cooldown and recovery.
Q: Does it support IPv6? A: Yes, both the client and Cloudflare Workers support IPv6 addressing.
Q: How do I update the worker code? A: Edit the code in Cloudflare dashboard and click "Save and Deploy". Wait 1-2 minutes for propagation.