Termux WireProxy
Termux WireProxy is a security-focused command-line tool for Android Termux that manages WireGuard client configurations through "WireProxy" (https://github.com/pufferffish/wireproxy).
It allows compatible applications to use a local SOCKS5 proxy whose traffic is routed through a WireGuard connection.
Termux WireProxy is designed for Android devices running Termux without root access.
What Termux WireProxy Does
The basic traffic flow is:
Application | v SOCKS5 Proxy 127.0.0.1:25344 | v WireProxy | v WireGuard | v VPN Server | v Internet
Termux WireProxy manages:
- WireGuard configuration profiles
- VPN provider organization
- WireProxy configuration
- SOCKS5 proxy operation
- Project organization
- Profile validation
- Secure file permissions
- Runtime status
- Health checks
- Diagnostics
- Configuration switching
- Configuration rollback when activation fails
Important
Termux WireProxy provides a SOCKS5 proxy.
It does not automatically force every Android application through the VPN.
Applications must support SOCKS5 themselves, or another Android-level mechanism must route their traffic to the proxy.
Termux WireProxy does not require Android root access.
Requirements
Before installing Termux WireProxy, you need:
- Android
- Termux
- Git
- A WireGuard ".conf" configuration
- A WireGuard VPN provider or your own WireGuard server
Your WireGuard configuration normally contains a private cryptographic key.
Treat your WireGuard configuration as a secret.
Do not publish a real configuration containing private credentials to GitHub, Discord, forums, paste sites, or other public locations.
Installation
- Clone the repository
Install Git if needed:
pkg install git
Clone the project:
git clone https://github.com/UnB21/termux-wireproxy.git
Enter the project directory:
cd termux-wireproxy
- Run the installer
Make sure you are inside the project directory:
cd ~/termux-wireproxy
Run:
./install.sh
The installer prepares the Termux WireProxy command and installs WireProxy if it is not already available.
After installation, verify the command:
twp version
You can also run:
twp doctor
The diagnostic command reports the current installation and configuration state.
First-Time Setup
The recommended first-time setup is:
twp setup
The setup wizard guides you through the initial configuration.
The wizard is designed for users who may not already understand WireGuard, WireProxy, providers, profiles, or Termux storage.
What the Setup Wizard Does
The setup wizard walks through the following process:
- Explain Termux WireProxy
- Explain the requirements
- Explain how to obtain a WireGuard configuration
- Request Termux storage access
- Ask for the configuration file path
- Verify that the configuration exists
- Verify that the configuration is readable
- Select an existing provider or create a new provider
- Validate the WireGuard configuration
- Install the profile securely
- Create a project
- Ask whether the project should be activated
- Verify WireProxy health
- Run diagnostic checks
- Display the final setup status
The wizard does not display the contents of your WireGuard configuration.
Your private key is therefore not printed as part of the normal setup process.
Obtaining a WireGuard Configuration
Termux WireProxy does not create a VPN service by itself.
You need a WireGuard client configuration that connects to an existing WireGuard server.
There are two common ways to obtain one.
Option 1: VPN Provider
Many VPN providers allow customers to generate or download WireGuard configurations from their account or configuration portal.
The exact process depends on the provider.
The resulting file normally ends with:
.conf
For example:
myvpn.conf
Option 2: Your Own WireGuard Server
You can also operate your own WireGuard server and create a client configuration for it.
This generally requires:
- A VPS or server
- A reachable server address
- WireGuard installed on the server
- Correctly configured WireGuard peers
- Appropriate firewall and routing configuration
A configuration generator creates configuration data.
It does not create a VPN server or VPN service by itself.
Termux Storage Access
If your WireGuard configuration was downloaded through an Android browser or another Android application, it may be located in Android shared storage.
Run:
termux-setup-storage
Termux will request Android storage permission.
After permission is granted, Termux normally exposes shared storage through:
~/storage/
For example:
~/storage/downloads/
Android shared storage may also be accessed using paths such as:
/storage/emulated/0/Download/
Termux WireProxy does not assume a particular download location.
The setup wizard asks you for the full path to the configuration you want to install.
Selecting a WireGuard Configuration
During setup, the wizard asks for the full path to your ".conf" file.
For example:
/storage/emulated/0/Download/myvpn.conf
or:
/storage/emulated/0/Download/VPN/myvpn.conf
or:
$HOME/storage/downloads/myvpn.conf
The wizard checks that:
- The path exists
- The path is a regular file
- The file is readable
- The filename is supported
- The WireGuard configuration passes validation
The configuration contents are not displayed by the wizard.
Providers
Providers are used to organize WireGuard profiles.
For example:
providers/ └── proton/ ├── profile-a.conf ├── profile-b.conf └── profile-c.conf
The provider name is an organizational label.
Termux WireProxy does not require the provider to be one particular VPN company.
During setup, you can:
- Select an existing provider
- Create a new provider
Provider names may contain:
- Letters
- Numbers
- Hyphens
- Underscores
A provider name cannot begin or end with a hyphen or underscore.
WireGuard Profiles
A profile is a WireGuard ".conf" file stored under a provider.
For example:
providers/proton/jcwgconfig3-US-FREE-46.conf
Profiles are validated before they are installed or activated.
The validation system checks the structure and required WireGuard information without printing private key contents.
Secure Profile Installation
When a profile is installed, Termux WireProxy stores it inside the project:
providers//.conf
The provider directory is protected with:
700
The WireGuard configuration file is protected with:
600
For example:
providers/proton/
has directory permissions of:
700
while:
providers/proton/example.conf
has file permissions of:
600
This is important because WireGuard configurations commonly contain private keys.
The original configuration file is not deleted or modified by the setup wizard.
Projects
Projects provide an additional organizational layer for WireGuard configurations.
A project records:
- Project ID
- Project name
- Provider
- Profile
A project does not contain a second copy of the WireGuard profile.
Instead, it references the provider and profile already installed by Termux WireProxy.
A project therefore looks conceptually like:
Project | +-- Provider | +-- Profile
Creating a project does not automatically activate it.
Project Storage
Projects are stored under:
~/termux-wireproxy/projects/
For example:
projects/ ├── home-vpn/ │ └── project.conf ├── work-vpn/ │ └── project.conf └── travel-vpn/ └── project.conf
Project directories are protected with:
700
Project metadata files are protected with:
600
Project metadata does not contain a duplicate copy of the WireGuard private key.
Project Management
List projects:
twp project list
Create a project:
twp project create
Display project information:
twp project info
For example:
twp project info home-vpn
Display project command help:
twp project help
Creating a Project
The interactive project wizard can be started with:
twp project create
The wizard asks for:
- Project ID
- Project name
- Provider
- WireGuard profile
- Confirmation
The wizard then creates the project metadata.
Creating the project does not change the currently active provider or profile.
For example, if the active configuration is:
Provider: proton Profile: NewConf2-US-FREE-106.conf
and you create a project referencing:
Provider: proton Profile: jcwgconfig3-US-FREE-46.conf
the active configuration remains unchanged until you explicitly activate the new profile.
Project IDs
Project IDs are used internally to identify projects.
They may contain:
- Letters
- Numbers
- Hyphens
- Underscores
They cannot begin or end with:
or:
_
Examples of valid project IDs:
home home-vpn vpn01 travel_vpn 8_27
Examples of invalid project IDs:
-home home home- home
A project ID must be unique.
If you attempt to create an existing project, the wizard will not overwrite it.
Activating a Profile
You can activate a provider/profile directly with:
twp use
For example:
twp use proton jcwgconfig3-US-FREE-46.conf
Activation changes the active Termux WireProxy configuration.
Before activation, the candidate profile is validated.
The system also performs security checks on the candidate configuration.
Activation Safety and Rollback
Termux WireProxy is designed so that changing profiles does not simply overwrite the previous configuration and hope that the new configuration works.
When a new profile is activated:
- The candidate profile is checked.
- The existing local configuration is backed up.
- The candidate provider/profile is written.
- WireProxy is restarted.
- The restart result is checked.
- If activation succeeds, the temporary backup is removed.
- If activation fails, the previous configuration is restored.
- WireProxy is restarted using the restored configuration.
If restoration itself fails, Termux WireProxy reports a critical error and directs you to diagnostic commands.
You can then run:
twp doctor
and:
twp health
Checking the Current Configuration
Display the active configuration:
twp current
Example:
Provider: proton
Profile: jcwgconfig3-US-FREE-46.conf
SOCKS5: 127.0.0.1:25344
Version: 0.4.0
The "current" command reports configuration information without displaying the contents of the WireGuard private key.
Checking Runtime Status
Run:
twp status
The status command reports information such as:
- Termux WireProxy version
- Active provider
- Active profile
- WireProxy process state
- Process ID
- SOCKS5 address
- VPN exit IP when available
- Recent WireProxy logs
If WireProxy is stopped, the exit IP cannot be obtained through the local proxy.
Health Checks
Run:
twp health
Health checking verifies whether the configured WireProxy service is functioning correctly.
If health checks fail, inspect diagnostics with:
twp doctor
You can also check runtime status:
twp status
Diagnostics
Run:
twp doctor
The diagnostic system checks the environment and Termux WireProxy installation.
Use it when:
- Setup fails
- WireProxy will not start
- A profile will not activate
- The SOCKS5 proxy is unavailable
- A rollback occurs
- You are troubleshooting a configuration problem
A useful troubleshooting sequence is:
twp doctor
then:
twp status
then:
twp health
Logs
WireProxy runtime logs are stored by the project and can be inspected through:
twp logs
Logs can be useful when diagnosing:
- Startup failures
- Connection problems
- DNS resolution issues
- WireGuard endpoint problems
- WireProxy configuration errors
Be careful when sharing logs publicly.
Logs can contain network information that you may not want to disclose.
Before posting logs online, inspect them for:
- IP addresses
- Hostnames
- Usernames
- Paths
- Provider-specific information
- Other identifying information
Never publish private keys.
Checking the VPN Exit IP
When WireProxy is running, you can use:
twp ip
This checks the public IP address observed through the SOCKS5 proxy.
You can also see the exit IP as part of:
twp status
An exit IP confirms what public address is observed through the proxy.
It does not, by itself, prove that every Android application is using the proxy.
Restarting WireProxy
Restart the service:
twp restart
Stop it:
twp stop
Start it:
twp start
Check whether it is running:
twp status
Browser and Application Use
Applications that support SOCKS5 can be configured to use:
127.0.0.1:25344
The SOCKS5 proxy address is:
127.0.0.1
The default SOCKS5 port is:
25344
If an application supports remote DNS through SOCKS5, enabling that option can help keep DNS resolution within the proxy path.
However, application-specific proxy behavior varies.
Termux WireProxy cannot guarantee that an application which does not support SOCKS5 will use the proxy.
DNS Considerations
DNS behavior depends on the application and how it is configured to use the SOCKS5 proxy.
For applications that support SOCKS5 hostname resolution, prefer remote DNS through the SOCKS5 proxy where appropriate.
For example, a browser may provide a setting equivalent to:
SOCKS5 Remote DNS
The exact setting name depends on the application.
Important limitation
Because Termux WireProxy operates in an unrooted Android environment, it does not provide kernel-level enforcement of all Android traffic.
Therefore:
Termux WireProxy
should not be described as an Android-wide kill switch or universal traffic firewall.
It is a managed WireGuard-backed SOCKS5 proxy.
Security Model
Termux WireProxy is designed around several security principles.
Private configuration handling
WireGuard profiles commonly contain private keys.
The project therefore:
- Avoids displaying private key contents during normal setup
- Uses restrictive permissions
- Stores installed profiles with mode "600"
- Stores provider directories with mode "700"
- Stores project metadata with mode "600"
- Validates configurations before activation
- Avoids overwriting an existing profile during setup
- Protects active configuration changes with rollback logic
No root requirement
Termux WireProxy is designed to work without Android root access.
This limits what the project can enforce at the Android networking layer.
The project therefore focuses on controlled proxy-based routing rather than pretending to provide capabilities unavailable to an unrooted application.
Protecting Your WireGuard Configuration
A WireGuard configuration may contain:
PrivateKey
That key should be treated as a credential.
Do not:
cat your-real-config.conf
and paste the result into a public forum.
Do not commit real profiles containing private keys to Git.
Do not upload real profiles to public repositories.
Do not send private configurations to people who do not need them.
If a private key is exposed, treat the key as compromised and regenerate the relevant WireGuard credentials.
Git Safety
Before committing changes, check the repository:
git status
Inspect what Git intends to commit:
git diff
Check tracked files:
git ls-files
Pay particular attention to provider profiles.
A real WireGuard configuration should normally not be committed to a public repository.
If you need example configurations for documentation or testing, use deliberately non-sensitive example data.
Common Commands
The primary command structure is:
twp setup twp start twp stop twp restart twp status twp health twp current twp providers twp doctor twp ip twp logs twp use twp project list twp project create twp project info twp project help twp version
For command-specific help, use the appropriate command's help functionality where available.
Recommended First-Time Workflow
For a new installation, the recommended sequence is:
cd ~/termux-wireproxy
Then:
twp setup
After setup completes, inspect the configuration:
twp current
Check diagnostics:
twp doctor
Check health:
twp health
Check runtime status:
twp status
If WireProxy is running, check the exit IP:
twp ip
Recommended Troubleshooting Workflow
If something does not work, do not immediately reinstall everything.
Start with:
twp doctor
Then:
twp status
Then:
twp health
If you recently changed profiles, inspect:
twp current
If necessary, inspect the logs:
twp logs
If a profile activation failed, the activation system attempts to restore the previous configuration automatically.
Understanding Projects vs. Active Configuration
This distinction is important.
A project is an organizational record.
The active configuration is what Termux WireProxy is currently using.
Creating a project:
twp project create
does not necessarily activate it.
Activating a profile:
twp use proton profile.conf
changes the active configuration.
Therefore, it is possible to have:
Projects:
home-vpn work-vpn travel-vpn
Active:
home-vpn
without activating the other projects.
Example Project Workflow
Create a project:
twp project create
List projects:
twp project list
Inspect a project:
twp project info home-vpn
When you are ready to activate its provider/profile:
twp use proton jcwgconfig3-US-FREE-46.conf
Then verify:
twp current
and:
twp health
Updating Termux WireProxy
Before updating, inspect the current state:
cd ~/termux-wireproxy
Then:
git status
If the working tree is clean, update the repository:
git pull
After updating, inspect the project:
git status
Then run:
twp version
and:
twp doctor
If an update changes configuration or behavior, read the repository documentation and release information before making additional changes.
Development and Testing
If you are developing Termux WireProxy itself, inspect a file before changing it.
For shell scripts, syntax checking can be performed with:
bash -n path/to/script.sh
ShellCheck can be run with:
shellcheck path/to/script.sh
For example:
bash -n scripts/project.sh
and:
shellcheck scripts/project.sh
A clean ShellCheck result is useful, but it does not replace functional testing.
Behavior should also be tested through the actual "twp" command.
Project Management Testing
The project management system supports:
twp project list
twp project create
twp project info
The project wizard validates:
- Project ID syntax
- Project uniqueness
- Project name input
- Provider selection
- Profile selection
- Confirmation
- Metadata creation
- Metadata integrity
- File permissions
Cancelling project creation does not create the project.
Attempting to reuse an existing project ID does not overwrite the existing project.
Current Architecture
The project is organized into several major areas:
termux-wireproxy/ ├── bin/ │ └── twp │ ├── configs/ │ ├── project.conf │ └── project.local.conf │ ├── lib/ │ ├── common.sh │ ├── diagnostics.sh │ ├── projects.sh │ └── security.sh │ ├── providers/ │ └── / │ └── .conf │ ├── projects/ │ └── / │ └── project.conf │ ├── scripts/ │ ├── doctor.sh │ ├── health.sh │ ├── ip.sh │ ├── logs.sh │ ├── project.sh │ ├── profile.sh │ ├── restart.sh │ ├── setup.sh │ ├── start.sh │ ├── status.sh │ ├── stop.sh │ └── use.sh │ ├── install.sh ├── README.md └── VERSION
The exact contents of the repository may change as development continues.
Important Limitations
Termux WireProxy is not:
- A replacement for Android's built-in VPN system
- A root-level network firewall
- A guaranteed Android-wide traffic enforcement mechanism
- A VPN provider
- A WireGuard server
- A tool that automatically routes every application through the proxy
It is a management layer around WireProxy and WireGuard designed for Termux.
Its primary networking interface is a local SOCKS5 proxy.
Privacy
Termux WireProxy is designed to keep sensitive configuration data local.
The project does not need to display your WireGuard private key during normal setup.
However, privacy ultimately depends on the configuration and applications you use.
Be especially careful with:
- VPN provider credentials
- WireGuard private keys
- Proxy credentials
- Logs
- Public IP addresses
- DNS configuration
- Browser configuration
- Third-party Android applications
A VPN does not automatically make all application activity private.
License
See the repository's license file for the applicable project license.
Repository
Source code:
https://github.com/UnB21/termux-wireproxy
Quick Start
For an experienced user who already has a WireGuard configuration:
git clone https://github.com/UnB21/termux-wireproxy.git cd termux-wireproxy ./install.sh twp setup
After setup:
twp doctor twp health twp status
If healthy, inspect the SOCKS5 endpoint:
twp current
The default endpoint is:
127.0.0.1:25344
Final Notes
Keep your WireGuard configuration private.
Do not publish private keys.
Do not assume that creating a project activates it.
Do not assume that activating a SOCKS5 proxy routes every Android application through it.
When troubleshooting, use:
twp doctor twp status twp health twp logs
When changing profiles, use the managed activation command:
twp use
Termux WireProxy is intended to make WireGuard-backed SOCKS5 proxy management on an unrooted Android device easier to understand, safer to operate, and easier to troubleshoot.