English | ΩΨ§Ψ±Ψ³Ϋ |
Version 3.1.0
VPSH stands for VPN Proxy Share Hotspot β your all-in-one solution for sharing internet connectivity from your Android device.
Turn your Android device into a powerful network sharing hub
VPSH (VPN Proxy Share Hotspot) is an Android application that transforms your device into a versatile network gateway. Whether you need to share a VPN connection, create a secure proxy server, or build a distributed proxy network with Cloudflare Workers, VPSH has you covered.
Key capabilities:
- π Share internet connection with other devices
- π Secure HTTP & SOCKS5 proxy server
- π Full VPN NAT routing (root required)
- π Distributed proxy via BatProxy
- π Real-time client monitoring & management
- β‘ Bandwidth limiting per client
|
|
|
|
Click to expand
# 1. Download the APK from the official source
# 2. Enable "Install from unknown sources" in Android settings
# 3. Install the APK
# 4. Grant notification permission when prompted (Android 13+)Requirements:
- Android 7.0 (API 24) or higher
- Internet connection
- Root access (optional, for Full Mode only)
flowchart LR
A[Open VPSH] --> B[Tap START]
B --> C[Proxy runs on port 8888]
C --> D[Connect devices to<br>http://YOUR_IP:8888]
- Open the app
- Ensure you're connected to the internet (Wi-Fi or mobile data)
- Tap START on the Dashboard
- The HTTP proxy will start on port 8888
- Connect other devices using:
- Proxy:
http://[your-phone-ip]:8888 - SOCKS5 (if enabled):
[your-phone-ip]:1080
- Proxy:
flowchart LR
A[Enable Root] --> B[Connect VPN]
B --> C[Select FULL mode]
C --> D[Tap START]
D --> E[All hotspot traffic<br>routes through VPN]
- Enable root access
- Make sure your VPN is connected
- On the Dashboard, select FULL mode
- Tap START
- The app will route all hotspot traffic through your VPN
|
Features:
|
Limitation: Cannot share traffic from system-level VPNs (like Viva) because it cannot intercept traffic already routed to the VPN interface.
|
Features:
|
Advantage: Can share traffic from any VPN, including system-level apps like Viva, as it manipulates network routing at the system level.
- Status indicator: Shows current state (Stopped/Starting/Running/Paused/Error)
- Mode selector: Switch between PROXY and FULL modes
- Start/Stop button: Controls the service
- Interface info: Shows detected hotspot and VPN interfaces
When the service is running, connected clients appear in the list with:
flowchart LR
Client[Connected Client] --> IP[IP Address]
Client --> MAC[MAC Address]
Client --> Nickname[Custom Nickname]
Client --> Block[Block/Unblock]
Client --> Limit[Bandwidth Limit]
Client controls:
- βοΈ Tap the pencil icon to rename a device
- β±οΈ Tap the clock icon to set a bandwidth limit
- π Tap the checkmark/block icon to block or unblock a device
In Proxy Mode, tap the QR button to display a QR code containing:
PROXY http://[username:password@][phone-ip]:[port]
Scan this with another device to instantly configure proxy settings.
The Dashboard includes a tethering helper section:
- πΆ Detects Wi-Fi, USB, or Bluetooth tethering
- π USB tether enable button (root required)
- βοΈ Opens system tethering settings
- π± Shows USB cable connection status
BatProxy is an enterprise-grade, intelligent proxy tunnel that turns your Android device into a resilient gateway. Instead of relying on a single proxy server, it uses a pool of distributed "workers" β typically deployed as Cloudflare Workers β to route your traffic.
flowchart TB
subgraph Client[VPSH Android Client]
A[HTTP/SOCKS5<br>Proxy Server]
end
subgraph Workers[Worker Pool]
B[Worker 1<br>wss://us-worker.workers.dev]
C[Worker 2<br>wss://eu-worker.workers.dev]
D[Worker 3<br>wss://asia-worker.workers.dev]
end
subgraph Targets[Target Servers]
E[example.com]
F[api.github.com]
G[Target N]
end
A -->|Intelligent Selection| B
A -->|Intelligent Selection| C
A -->|Intelligent Selection| D
B --> E
B --> F
C --> F
C --> G
D --> E
D --> G
The system intelligently:
- π― Routes connections through the healthiest, fastest available worker
- π Monitors worker performance using EWMA (latency, success rate)
- π Automatically fails over to other workers if one becomes slow
- π Reopens connections through recovered workers (circuit breaker with exponential backoff)
flowchart LR
subgraph WorkerSelection[Worker Selection Algorithm]
S[Score Calculation] --> F1[Success Rate EWMA]
S --> F2[RTT EWMA]
S --> F3[Active Connections]
S --> F4[Cooldown Status]
S --> F5[Slow Streak Penalty]
F1 & F2 & F3 & F4 & F5 --> Final[Weighted Score]
Final --> Best[Select Best Worker]
end
For a complete technical deep-dive into the architecture, worker selection algorithms, and deployment, visit the official project repository:
π BatProxy on GitHub
How it Works (Briefly):
- Workers are servers (running on Cloudflare's edge network) that accept WebSocket connections
- The Android app (Client) connects to these workers using a secure, HMAC-authenticated handshake
- When you or a connected client makes a request, the app selects the optimal worker based on a real-time score
- Data is relayed through the worker to the target server, with built-in optimizations like data coalescing to reduce overhead
This setup provides exceptional reliability, low latency through Cloudflare's global network, and automatic recovery from failures.
- Go to the BatProxy tab
- Tap the + button
- Enter worker URL and password (the same
PASSWDyou set on your Cloudflare Worker) - Tap Save
Worker URL format: wss://your-worker-name.workers.dev (Secure WebSocket)
Each worker displays:
| Status | Description |
|---|---|
| π’ Closed | Healthy and available |
| π‘ Half-open | Recovering from a failure, under probation |
| π΄ Open | Failed, in a cooldown period (excluded from selection) |
Additional metrics:
- β±οΈ Cooldown: Time remaining before retry
- π‘ RTT: Average round-trip time in milliseconds
- π Score: Real-time performance score (higher is better)
- π Active connections: Current connections through this worker
- β β OK/Fail: Success and failure counts
- Set custom DNS for DNS-over-proxy resolution
- Default:
1.1.1.1:53 - DNS queries are sent through the BatProxy tunnel
βββββββββββββββββββββββββββββββββββββββ
β HTTP Proxy Port: [ 8888 ] β
β Enable SOCKS5: [β] β
β SOCKS5 Port: [ 1080 ] β
βββββββββββββββββββββββββββββββββββββββ
βββββββββββββββββββββββββββββββββββββββ
β Require Auth: [β] β
β Username: [ admin ] β
β Password: [ β’β’β’β’β’β’β’β’ ] β
βββββββββββββββββββββββββββββββββββββββ
Chain VPSH through another proxy:
βββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Upstream Type: [ None βΌ ] [ SOCKS5 ] [ HTTP ] β
β Address: [ 192.168.1.100 ] β
β Port: [ 1080 ] β
β Username: [ optional ] β
β Password: [ optional ] β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββ
βββββββββββββββββββββββββββββββββββββββ
β Auto Restart: [β] β
β Health Interval: [ 25 ] seconds β
β Kill Switch: [β] β
βββββββββββββββββββββββββββββββββββββββ
βββββββββββββββββββββββββββββββββββββββ
β Force VPN Only: [β] β
β Block IPv6 Leak: [β] β
βββββββββββββββββββββββββββββββββββββββ
βββββββββββββββββββββββββββββββββββββββ
β Hotspot Interface: [ wlan0 ] β
β VPN Interface: [ tun0 ] β
βββββββββββββββββββββββββββββββββββββββ
The Logs tab shows:
- π Service start/stop events
- π Client connections
β οΈ Errors and warnings- π Health check results
Health Check button: Manually triggers a health check and logs the result.
Add VPSH to your Quick Settings panel for one-tap control:
- Swipe down twice to open Quick Settings
- Tap the edit/pencil icon
- Find "VPSH" and drag it to your active tiles
- Tap the tile to start/stop the service
The tile shows:
- Active: Service is running
- Inactive: Service is stopped
- Subtitle: Current state (Running/Stopped/Paused/Error)
Windows:
netsh winhttp set proxy [phone-ip]:8888Linux/macOS:
export http_proxy=http://[phone-ip]:8888
export https_proxy=http://[phone-ip]:8888Android (manual):
Settings β Wi-Fi β Tap network β Proxy β Manual
Proxy hostname: [phone-ip]
Proxy port: 8888
Windows:
# Firefox: Settings β Network Settings β SOCKS5Linux/macOS:
export ALL_PROXY=socks5://[phone-ip]:1080flowchart LR
A[Start Proxy Mode] --> B[Tap QR Button]
B --> C[Scan with Other Device]
C --> D[Auto-Configure Proxy]
For quick and easy proxy configuration on your desktop, VPSH provides automated scripts for both Windows and Linux:
| Platform | Script | Description |
|---|---|---|
| πͺ Windows | client-windows.bat |
Interactive and command-line proxy manager for Windows |
| π§ Linux | client-linux.sh |
Interactive and command-line proxy manager for Linux |
Windows Usage:
# Interactive mode (double-click or run without arguments)
client-windows.bat
# Command-line mode
client-windows.bat connect 192.168.1.100 8888
client-windows.bat connect 10.0.0.1 1080 myuser mypass
client-windows.bat disconnect
client-windows.bat status
client-windows.bat testLinux Usage:
# Make executable
chmod +x client-linux.sh
# Interactive mode
./client-linux.sh
# Command-line mode
./client-linux.sh connect 192.168.1.100 8888
./client-linux.sh connect 10.0.0.1 1080 myuser mypass
./client-linux.sh disconnect
./client-linux.sh status
./client-linux.sh testWhat these scripts do:
- π§ Configure system proxy settings
- π Set HTTP_PROXY and HTTPS_PROXY environment variables
- β Test connection through the proxy
- π Display current proxy status
- π One-command disconnect
BatProxy workers are servers that connect to VPSH. To set up a worker:
-
On the worker server (Cloudflare):
- Follow the deployment guide in the BatProxy repository
- Deploy the
worker.jscode to Cloudflare Workers - Set the
PASSWDenvironment variable
-
On your VPSH Android app:
- Go to BatProxy tab
- Add the worker URL (e.g.,
wss://your-worker.workers.dev) and password - Start the BatProxy service
-
Connect clients:
- Configure clients to use the VPSH proxy (HTTP/SOCKS5)
- All traffic will be intelligently routed through healthy workers
| Issue | Solution |
|---|---|
| β Proxy not starting | Check if port is already in use. Change port in Settings. |
| π Clients can't connect | Verify you're on the same network. Check firewall settings. |
| π Full Mode not working | Ensure root is available. Check VPN is active. |
| π BatProxy workers failing | Verify worker URLs are correct. Check worker password matches. Check internet connection. |
| π Permission errors | Grant all requested permissions (notifications, VPN). |
| π USB tether not working | Enable USB tethering in system settings first. |
Always check the Logs tab for detailed error messages when troubleshooting.
Do I need root?
Only for Full Mode (VPN NAT routing). Proxy Mode works without root.What's the difference between Proxy and Full mode?
Proxy mode runs a proxy server. Full mode routes all hotspot traffic through the VPN using system-level routing.Why can't I share certain VPNs (like Viva) using Proxy Mode without root?
This is a fundamental limitation of Android's networking architecture:
1. VPNs Work at the System Level
- Most VPN apps create a virtual network interface (e.g.,
tun0) - They use Android's
VpnServiceAPI to route all device traffic through this interface - This routing happens at the OS level, before any user-space proxy can intercept
2. Proxy Mode is a User-Space Application
- VPSH's Proxy Mode runs an HTTP/SOCKS5 proxy server
- It can only accept traffic explicitly directed to it by a client app
- It cannot see traffic already routed to the VPN interface
3. The "Chicken and Egg" Problem
- When you activate a VPN, the system directs all traffic to the VPN interface
- The VPN app encrypts and forwards this traffic to its own server
- A proxy running on the same device is "downstream" of this system-level decision
The Only Solution: Full Mode (Requires Root)
- VPSH's Full Mode uses
iptablesand routing rules, requiring root access - With root, VPSH can manipulate the system's routing table and firewall to force all traffic through the VPN
- This effectively shares the VPN connection with other devices on your hotspot
In summary:
- Without root: You can only share the internet connection for apps that choose to use your proxy
- With root (Full Mode): You can share any internet connection, including system-level VPNs like Viva