Version 3.3.1
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
| File | Description | Link |
|---|---|---|
vpsh-3.3.1.apk |
Android application | Download APK |
client-windows.bat |
Windows proxy setup script | Download BAT |
client-linux.sh |
Linux proxy setup script | Download SH |
This release adds a full round of quality-of-life and access-control features on top of 3.1.0:
- 🧾 One-tap setup for any OS (PAC) – a built-in Proxy Auto-Config server so Windows/macOS/Linux/ChromeOS devices can auto-configure the proxy from a single URL, no manual per-app setup.
- 🎟️ Guest links – generate short-lived, quota-limited proxy credentials to hand out without giving away your real password. They expire on their own.
- 🚫 Hotspot tab (MAC-level ban) – a new tab that bans a device by MAC address right at the hotspot interface (root), so it's locked out of everything on the hotspot, not just the sharing proxy.
- 🌍 Public IP & exit country on the Dashboard – see your current public IP and a country flag, refreshed automatically.
- 🗺️ BatProxy exit-region detection – see which country a connected worker is actually exiting through.
- ✂️ BatProxy split tunneling – choose which apps use the BatProxy tunnel (all / only selected / all-except-selected).
- 📶 Bandwidth limiting now works in Proxy Mode too – per-client speed caps are no longer Full-Mode-only; they work without root.
- 🎮 Game Mode (Full Mode) – prioritizes real-time UDP traffic (games, calls) over bulk downloads for connected devices.
- 🔌 Auto-start after reboot – if VPSH was running when the phone shut down, it can restart itself once the hotspot/root are available again.
- 🔐 Proxy-mode kill switch – previously kill-switch behavior only existed conceptually for Full Mode; Proxy Mode now has its own kill-switch that pauses the proxy if the phone's VPN drops.
- 💾 Saved upstream proxy profiles – save named upstream chains (e.g. "Home SOCKS5") and switch between them in one tap instead of retyping.
- 🌐 Full bilingual UI – switch between English, Persian, or system default from Settings, anytime, no reinstall needed.
- ℹ️ About tab – an in-app guide to every tab, plus developer links.
- 📄 Client scripts now support profiles and richer commands (see Client Setup Guide).
Note: BatProxy currently tunnels TCP-only traffic (web, apps, TLS). UDP-based protocols that rely on QUIC/HTTP3 (some games, some video calls) don't route through it yet — DNS is a special-cased exception and does work.
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, with a one-tap PAC auto-config option for any OS
- 🌐 Full VPN NAT routing (root required)
- 🚀 Distributed proxy via BatProxy, with optional split tunneling
- 📊 Real-time client monitoring & management
- ⚡ Bandwidth limiting per client (works in both Proxy and Full Mode)
- 🎟️ Temporary guest access links
- 🚫 Hard, MAC-level hotspot bans (root)
|
|
|
|
|
|
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 8.0 (API 26) or higher
- Internet connection
- Root access (optional — required only for Full Mode, the Hotspot ban tab, and Game Mode)
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 sharing on the Dashboard
- The HTTP proxy will start on port 8888
- Connect other devices any of these ways:
- Manually:
http://[your-phone-ip]:8888 - SOCKS5 (if enabled):
[your-phone-ip]:1080 - Auto (any OS): tap the QR button → Auto tab → point the other device's "automatic proxy configuration URL" setting at the PAC link shown (no manual proxy fields needed)
- Scan the Manual QR code with a phone
- Manually:
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 sharing
- The app will route all hotspot traffic through your VPN — connected devices need zero configuration
|
Features:
|
Limitation: Cannot share traffic from system-level VPNs (like Viva) because it cannot intercept traffic already routed to the VPN interface — only traffic explicitly pointed at the proxy is shared.
|
Features:
|
Advantage: Can share traffic from any VPN, including system-level apps like Viva, as it manipulates network routing at the system level. Connected devices don't need any proxy settings — it's fully transparent.
VPSH has six tabs: Dashboard, Hotspot, BatProxy, Settings, Logs, and About.
- Status indicator: Stopped / Starting / Running / Paused (kill-switch) / Error
- Sharing mode selector: switch between Proxy and Full (Full is greyed out without root)
- Start sharing / Stop sharing: controls the foreground service — once running, a persistent notification with its own Stop button lets you turn it off without reopening the app
- Public IP & exit country: shown below the status and refreshed every 5 seconds
- Interface info: shows the detected hotspot and VPN interfaces
- Stat chips: connected clients, traffic, and port
Client management — for every connected client:
flowchart LR
Client[Connected Client] --> IP[IP Address]
Client --> MAC[MAC Address]
Client --> Nickname[Custom Nickname]
Client --> Block[Block/Unblock]
Client --> Limit[Bandwidth Limit]
- ✏️ Rename — give a device a friendly nickname
- ⏱️ Limit speed — set a max speed in kbit/s (0 = unlimited); works in both Proxy and Full mode
- 🔒 Block/Unblock — a blocked device is dropped immediately from the sharing proxy. It moves to a separate "Blocked devices" list with an Unblock button, so you can always undo it later — even after the device disconnects
Blocking here only refuses the sharing proxy — the device can still reach the hotspot itself (other devices on it, the phone's own services). For a hard ban that locks a device out of the hotspot entirely, use the Hotspot tab instead.
Quick connect (QR button) — three tabs:
| Tab | What it shows | Best for |
|---|---|---|
| Manual | PROXY http://[username:password@][phone-ip]:[port] as a QR code |
Devices/apps that let you set a proxy manually |
| Auto (any OS) | A PAC URL as a QR code / link | Windows, macOS, Linux — sets the proxy for the whole OS in one step, no per-app config |
| Guest link | Create/revoke temporary guest credentials | Handing out access without sharing your real password |
Guest links — create a link with:
- An expiry time in minutes
- An optional data quota in MB (0 = unlimited)
The link gets its own random username/password. It expires automatically once the TTL passes or the quota is hit — no manual revoke needed, though you can hit Revoke any time to cut it off immediately.
A dedicated tab for the hotspot itself, separate from the sharing proxy — requires root.
- Lists every device currently on the hotspot (Wi-Fi, USB, or Bluetooth), detected straight from the system's neighbor table — this works even if Proxy/Full sharing isn't running at all
- Ban a device by its MAC address: this drops its traffic at the hotspot network interface itself, so it can't reach anything through the hotspot — not just the sharing proxy. This survives DHCP/IP changes and works the same in Proxy mode, Full mode, or with sharing stopped entirely
- A separate Banned from hotspot list with an Unban button, so past bans stay manageable even after the device disconnects
- Without root, you'll see a notice explaining the tab is unavailable and pointing you back to the Dashboard's proxy-level block
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)
For a complete technical deep-dive into the architecture, worker selection algorithms, and deployment, visit the official project repository:
👉 BatProxy on GitHub
Important: BatProxy runs as its own VPN tunnel for this device, not through the HTTP/SOCKS5 proxy servers of Proxy/Full mode. It only tunnels TCP traffic (web browsing, apps, TLS). UDP-heavy protocols like some games or QUIC/HTTP3-based video calls won't route through it yet — DNS resolution is specially handled and does work.
- Go to the BatProxy tab
- Tap Add worker
- Enter the worker URL and password (the same
PASSWDyou set on your Cloudflare Worker) - Save
Worker URL format: wss://your-worker-name.workers.dev (Secure WebSocket)
Changing the worker list while BatProxy is connected requires a reconnect (Disconnect → Connect) to take effect.
Each worker displays:
| Status | Description |
|---|---|
| 🟢 Healthy (Closed) | Healthy and available |
| 🟡 Recovering (Half-open) | Recovering from a failure, under probation |
| 🔴 Cooling down (Open) | Failed, in a cooldown period (excluded from selection) |
Additional metrics: cooldown time remaining, average RTT in ms, real-time performance score, active connections, OK/Fail counts, and — once connected — the exit country/flag the tunnel is actually using.
Choose which apps on your phone use the BatProxy tunnel:
| Mode | Behavior |
|---|---|
| Off | Everything on the phone uses the tunnel (default) |
| Exclude selected apps | The apps you pick bypass the tunnel; everything else uses it |
| Only selected apps | Only the apps you pick use the tunnel; everything else goes direct |
Handy for keeping something like a banking app on your normal connection while everything else routes through BatProxy.
- Set a custom DNS host/port 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 ] │
│ Auto proxy setup (PAC): [✓] │
│ PAC server port: [ 8199 ] │
└─────────────────────────────────────┘
┌─────────────────────────────────────┐
│ Require Auth: [✓] │
│ Username: [ admin ] │
│ Password: [ •••••••• ] │
└─────────────────────────────────────┘
Chain VPSH through another proxy — for example, to layer it on top of a VLESS/VMess/Shadowsocks client (turn on "local proxy only" mode in that client and point VPSH at its local SOCKS5/HTTP port).
┌─────────────────────────────────────────────────────┐
│ Upstream Type: [ None ▼ ] [ SOCKS5 ] [ HTTP ] │
│ Address: [ 127.0.0.1 ] │
│ Port: [ 1080 ] │
│ Username: [ optional ] │
│ Password: [ optional ] │
└─────────────────────────────────────────────────────┘
Saved profiles: save the upstream above under a name (e.g. "Home SOCKS5", "Work HTTP") and switch between saved profiles with one tap instead of retyping host/port/credentials every time.
┌─────────────────────────────────────┐
│ Auto-restart on failure: [✓] │
│ Health check interval: [ 25 ]s │
│ Kill switch (proxy mode):[✓] │
└─────────────────────────────────────┘
The kill switch pauses the proxy automatically if the phone's own VPN drops, and resumes it once the VPN is back.
┌─────────────────────────────────────┐
│ Cut off clients if VPN drops: [✓] │
│ Block IPv6 leaks: [✓] │
│ Game Mode: [✓] │
└─────────────────────────────────────┘
Game Mode prioritizes real-time traffic (games, calls, video chats) over bulk downloads on the hotspot, so one device downloading a big file doesn't add lag to another device's game.
┌─────────────────────────────────────┐
│ Hotspot Interface: [ wlan0 ] │
│ VPN Interface: [ tun0 ] │
└─────────────────────────────────────┘
- Auto-start after reboot — off by default; if enabled and the service was running when the phone shut down, it restarts itself automatically once the hotspot/root are available again
- Language — System default / English / فارسی, switchable anytime, applies instantly across the whole app
The Logs tab shows a live feed of:
- 📝 Service start/stop events
- 🔌 Client connections
⚠️ Errors and warnings- 💚 Health check results
- 🔄 Automatic restarts triggered by the health monitor (up to 5 attempts before it gives up)
Health Check button: manually triggers a health check and logs the result.
An in-app reference tab covering what each tab does, Proxy vs. Full mode at a glance, links to the client setup scripts, and the developer's GitHub/Telegram.
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 → SOCKS5
Linux/macOS:
export ALL_PROXY=socks5://[phone-ip]:1080The easiest option for a desktop/laptop — no manual proxy fields at all:
- On the Dashboard, tap the QR button, then the Auto (any OS) tab
- On the other device, open network settings and find "Automatic proxy configuration URL" (Windows: Settings → Network → Proxy; macOS: Network → Advanced → Proxies → Automatic Proxy Configuration; Linux/ChromeOS: similar wording)
- Paste in the PAC URL shown in the app (e.g.
http://192.168.43.1:8199/proxy.pac) - Every app on that device now uses the proxy automatically
flowchart LR
A[Start Proxy Mode] --> B[Tap QR Button]
B --> C[Scan with Other Device]
C --> D[Auto-Configure Proxy]
- On the Dashboard, tap the QR button → Guest link tab
- Set an expiry time and (optionally) a data cap, then create the link
- Share the generated username/password with your guest
- It stops working on its own once the timer or data cap is hit — or tap Revoke to cut it off immediately
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 the BatProxy tab
- Add the worker URL (e.g.,
wss://your-worker.workers.dev) and password - Tap Connect
-
Optional: set up split tunneling if you only want specific apps (or everything except specific apps) to use the tunnel
| Issue | Solution |
|---|---|
| ❌ Proxy not starting | Check if the port is already in use. Change the 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 the VPN is active. |
| 🧾 PAC / auto-setup doesn't apply | Confirm "Auto proxy setup (PAC)" is on in Settings, and that the other OS actually supports "Automatic proxy configuration URL". |
| 🎟️ Guest link stopped working | It expired or hit its data quota — both are intentional. Create a new one. |
| 🚫 Can't ban from the Hotspot tab | This needs root. Without it, use the Dashboard's proxy-level block instead. |
| 🌐 BatProxy workers failing | Verify worker URLs are correct. Check the worker password matches. Check your 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, the Hotspot ban tab, and Game Mode. Proxy Mode, PAC auto-setup, guest links, and BatProxy all work without root.What's the difference between Proxy and Full mode?
Proxy mode runs a proxy server that other devices connect to (manually, via PAC, or via QR). Full mode routes all hotspot traffic through the VPN transparently using system-level routing — connected devices need zero configuration.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
How do I find my phone's IP address?
Look in the app's Dashboard under the interface info, or check your Wi-Fi settings.Can I run both HTTP and SOCKS5 simultaneously?
Yes, enable SOCKS5 in Settings and both will run on their respective ports.How do I limit bandwidth per client?
On the Dashboard, tap the clock icon next to any client and set a limit in kbit/s. This now works in both Proxy and Full mode.What's the difference between blocking a device and banning it from the Hotspot?
Blocking (on the Dashboard) only refuses that device's access to the sharing proxy — it can still join the hotspot and reach other things on it. Banning (on the Hotspot tab, root required) drops the device's traffic at the hotspot interface by MAC address, locking it out of everything, regardless of whether sharing is running.What are guest links for?
They're temporary proxy credentials with their own expiry time and optional data cap, so you can let someone use your connection briefly without handing out your real username/password.What does BatProxy do?
BatProxy routes your device's own traffic through a pool of distributed workers (like Cloudflare Workers), automatically selecting the healthiest one for each request. This provides high reliability and performance, and is a separate way of getting online — not the same as the HTTP/SOCKS5 proxy in Proxy/Full mode.Why are my workers showing "Recovering" status?
A worker is recovering (half-open) if it failed but is being retried. It will either become Healthy again or fail completely and enter a cooldown period.How does the health monitor work?
It periodically checks if the service is healthy. If it fails, it attempts to restart up to 5 times before giving up. For BatProxy, it also performs health checks on each worker.Can I use my own BatProxy workers?
Yes! You can deploy the BatProxy worker code (available on GitHub) to Cloudflare Workers or any compatible WebSocket server and add the URL to the VPSH app.What are the client scripts for?
Theclient-windows.bat and client-linux.sh scripts automatically configure your desktop's proxy settings to connect to VPSH. They support interactive and command-line modes for easy connection management.