A lightweight WireGuard-over-SOCKS5 management wrapper for Termux.
Termux WireProxy provides a simple command-line interface (twp) for managing a WireProxy-based VPN SOCKS5 proxy connection on Android using Termux.
The goal of this project is to make WireProxy easier to install, configure, start, stop, monitor, and troubleshoot from a mobile Linux environment.
- Simple
twpcommand interface - Automatic WireProxy dependency installation
- Provider/profile management
- Start, stop, and restart WireProxy
- Process and connection health checks
- Active configuration display
- VPN exit IP verification
- Log viewing and follow mode
- Version reporting
- Separation of public project files and private VPN credentials
Before installing, you need:
- Android device
- Termux
- A WireGuard-compatible VPN configuration file
Termux WireProxy uses:
- WireProxy to create a local SOCKS5 proxy from a WireGuard connection.
- WireGuard configuration files provided by your VPN provider or your own WireGuard server.
Your WireGuard configuration file contains private information such as cryptographic keys and should never be shared publicly.
Install Git if needed:
pkg install gitClone the project:
git clone https://github.com/UnB21/termux-wireproxy.gitEnter the project directory you just cloned:
cd termux-wireproxyIf you cloned the repository using a different directory name, enter that directory instead.
Example:
cd termux-wireproxy-testYou can verify your current working directory at any time by running:
pwdExample output:
/data/data/com.termux/files/home/<your-project-directory>
Run:
./install.shThe installer will:
- Verify it is running inside Termux
- Install WireProxy if it is missing
- Make the
twpcommand executable - Create the Termux command shortcut
After installation, verify:
twp versionExpected output:
Termux WireProxy
Version: 0.1.0-alpha
Run diagnostics:
twp doctorAfter installation, all project files are stored inside the directory you cloned.
To see the project files, run:
lsYou should see folders similar to:
bin
configs
lib
logs
providers
scripts
state
The most important directories are:
| Directory | Purpose |
|---|---|
providers/ |
Stores your private WireGuard configuration files |
configs/ |
Project configuration files |
scripts/ |
Internal scripts used by the twp command |
logs/ |
WireProxy log files |
state/ |
Runtime state information |
All commands shown throughout this guide should be run from inside the project directory unless stated otherwise.
Termux WireProxy uses provider profiles.
A provider profile is a WireGuard configuration file stored inside the providers directory.
The expected layout is:
providers/
└── provider-name/
└── profile-name.conf
Example:
providers/
└── proton/
└── us.conf
A WireGuard profile is a configuration file supplied by your VPN provider or generated for your own WireGuard server.
The file usually has a .conf extension and contains information such as:
- Interface private key
- VPN address
- Server public key
- Server endpoint
- Allowed IP addresses
Example filename:
us.conf
Create a directory for your VPN provider:
mkdir -p providers/protonVerify that the directory was created:
ls providersExpected output:
proton
At this point, the provider directory exists but is empty.
Your WireGuard configuration file must be copied into that directory before it can be used.
Never upload your WireGuard configuration file to GitHub or share it publicly.
Your WireGuard profile contains private cryptographic keys and should be treated like a password.
Termux WireProxy requires a WireGuard client configuration file that connects to an existing WireGuard server.
There are two common ways to obtain one.
Many VPN providers allow downloading WireGuard configuration files from their account dashboard.
This is the easiest option because the provider already operates the WireGuard server.
If you want to host your own VPN server, you can generate WireGuard configurations using tools such as:
-
Nixpoin WireGuard Config Generator https://nixpoin.com/wireguard-generator/
-
ServerSpan WireGuard Generator https://www.serverspan.com/en/tools/wireguard
These tools generate server and client configuration files.
You will still need:
- A VPS or server
- A public IP address
- A WireGuard server installation
A configuration generator does not create a VPN service by itself.
After generating your client configuration file, place it in:
providers/<provider>/<profile>.conf
Example:
providers/myserver/home.conf
Then activate it:
twp use myserver home.confPrefer tools that generate private keys locally and do not transmit private keys to third parties. Review the privacy information of any generator before trusting it with cryptographic material.
If you downloaded your WireGuard configuration using your Android web browser, it is usually saved in your Downloads folder.
To allow Termux to access Android storage, run:
termux-setup-storageWhen prompted, grant the requested storage permission.
Your Downloads folder will then be available at:
~/storage/downloads
List the downloaded files:
ls ~/storage/downloadsIf your configuration file is named us.conf, copy it into your provider directory:
cp ~/storage/downloads/us.conf providers/proton/Verify that it was copied successfully:
ls providers/protonExpected output:
us.conf
Your WireGuard configuration is now ready to be selected by Termux WireProxy.
List available provider profiles:
twp providersThe twp use command expects two arguments:
twp use <provider> <profile>
<provider>is the name of the directory insideproviders/<profile>is the name of the WireGuard configuration file
For example, if your project looks like this:
providers/
└── proton/
└── us.conf
Run:
twp use proton us.confAnother example:
providers/
└── myserver/
└── home.conf
Run:
twp use myserver home.confAfter selecting a profile, verify the active configuration:
twp currentThe following example demonstrates a complete first-time setup after installation.
Create a provider directory:
mkdir -p providers/myvpnCopy your WireGuard configuration file into that directory:
providers/myvpn/home.conf
Select the profile:
twp use myvpn home.confVerify the active configuration:
twp currentRun diagnostics:
twp doctorStart WireProxy:
twp startCheck that WireProxy is running:
twp statusVerify your VPN exit IP:
twp ipIf everything is configured correctly, your public IP address should now be the IP address of your VPN server or VPN provider.
Run:
twp healthThis checks:
- WireProxy availability
- Configuration validity
- Running process
- SOCKS5 availability
To check your VPN exit IP:
twp ipThe twp command manages WireProxy without requiring you to manually run WireProxy commands.
twp starttwp stoptwp restarttwp statustwp healthtwp doctortwp currenttwp iptwp logsFollow logs:
twp logs -ftwp providerstwp use <provider> <profile>Example:
twp use proton us.conftwp versionRun the installer again:
./install.shThen verify:
twp versionRun:
./install.shThe installer will install WireProxy automatically.
You can also verify manually:
wireproxy --versionThis usually means Termux WireProxy could not find the WireGuard configuration file it expects.
First, list your provider directories:
ls providersThen list the profiles inside your provider directory:
ls providers/protonVerify the currently selected configuration:
twp currentIf you selected the wrong provider or profile, activate the correct one:
twp use <provider> <profile>Example:
twp use proton us.confRun:
twp doctorThen check logs:
twp logsRestart if needed:
twp restartIf twp doctor reports that SOCKS5 is unavailable:
Check status:
twp statusReview logs:
twp logsRestart WireProxy:
twp restartPrivate files are intentionally excluded from Git tracking.
Ignored files include:
providers/**/*.conf
logs/
state/
Never upload:
- WireGuard configuration files
- Private keys
- VPN credentials
Treat your WireGuard profile the same way you would treat a password.
Current version:
0.1.0-alpha
This project is actively under development.
This project is licensed under the MIT License.
See the LICENSE file for details.