This project provides a patched version of the official Tailscale CLI (tailscale and tailscaled) designed specifically to run inside Termux on Android 11 and above without requiring Root or /dev/net/tun.
Run this single command in Termux to download and install the latest package:
curl -fsSL https://raw.githubusercontent.com/bropines/tailscale-termux-cli/main/remote-install.sh | bashThe installer detects whether your Termux uses dpkg or pacman and fetches the matching package (.deb or .pkg.tar.xz). It asks Termux itself (TERMUX_APP_PACKAGE_MANAGER) rather than looking for a dpkg binary, because a pacman-based Termux has one too. Releases carry a SHA256SUMS file if you want to verify the download by hand.
The one-line installer above needs none of this — it downloads the package and installs the local file. But pacman -U <URL> refuses to fetch a package without a detached signature beside it, so releases ship one. To use that form, import the signing key into pacman's keyring first (it is separate from your personal GPG keyring):
curl -fsSL https://raw.githubusercontent.com/bropines/tailscale-termux-cli/main/keys/tailscale-termux-cli.asc | pacman-key --add -
pacman-key --lsign-key 2D5133D5E2C7C8E7BE2D0CBB6EAA7CF6CEFB203EThen:
pacman -U https://github.com/bropines/tailscale-termux-cli/releases/latest/download/tailscale-termux-1.102.3.4-1-aarch64.pkg.tar.xzThe key is 2D5133D5E2C7C8E7BE2D0CBB6EAA7CF6CEFB203E, published at keys/tailscale-termux-cli.asc and attached to every release. If you have it in your ordinary GPG keyring, the one-line installer verifies the signature as well as the checksum.
Once installed, the tailscaled background service is enabled and started. You can immediately connect:
tailscale up(or tailscale-cli up)
- Netmon Bypass (Android 11+): Intercepts interface discovery (
anetioctl,/proc/net/if_inet6,ifconfigfallback) to bypass Android netlink restrictions. - Userspace Networking: Runs without Root or
/dev/net/tunout of the box. - Automatic Socket Resolution: Both
tailscaleandtailscale-cliroute requests to~/.tailscale/tailscaled.sockwithout a manual--socketflag. - Auto-Start Daemon: The
tailscale-cliwrapper startstailscaledif it is not running. (The baretailscalebinary only gets the socket path filled in — start the daemon yourself, or use the service.) - Runit (
termux-services) Integration: Background service management, started when a Termux session opens. - Authenticated SOCKS5 proxy: credentials are generated for you on first start — see below.
tailscaled runs a SOCKS5 proxy on 127.0.0.1:1055 so you can route other apps through your tailnet.
Android's loopback interface is not isolated per app. Any app on the device holding only the INTERNET permission can connect to 127.0.0.1:1055. If the proxy were open, that app would get egress into your tailnet as this node — reaching private hosts, subnet routes and your exit node.
So the proxy requires a username and password. They are generated on the first daemon start and stored in ~/.tailscale/socks5.env (mode 0600). Show them with:
tailscale-socks5Tailscale SOCKS5 Proxy
======================
Address : 127.0.0.1:1055 (running daemon)
Username : termux
Password : 5f3a9c1e8b7d2046
URL : socks5://termux:5f3a9c1e8b7d2046@127.0.0.1:1055
Other useful forms:
| Command | Purpose |
|---|---|
tailscale-socks5 |
Show address and credentials |
tailscale-socks5 --url |
Print just the proxy URL, for scripts |
tailscale-socks5 --regenerate |
Issue a new password (restart the daemon to apply) |
The credentials are passed to the daemon through its environment, never as command-line flags — anything on argv is readable by every process on the device via /proc.
To turn the proxy off entirely, set TS_SOCKS5=off in ~/.tailscale/.env.
Warning
TS_SOCKS5_NO_AUTH=1 restores the old unauthenticated proxy. It exists only for clients that cannot send SOCKS5 credentials, and it reopens your tailnet to every app on the device.
You can use standard tailscale commands or the tailscale-cli wrapper interchangeably.
Tip
Subcommands like tailscale funnel, tailscale serve, tailscale status, and tailscale ping work natively out of the box!
- Connect / Log in:
tailscale up
- Check connection status:
tailscale status
- Expose a local service (Funnel / Serve):
tailscale funnel 8096
- Show the SOCKS5 proxy credentials:
tailscale-socks5
- Diagnose a problem (daemon, login, DNS, network, proxy — run this first if anything misbehaves):
tailscale-test
The background daemon is managed via termux-services (runit) or helper commands:
- Check daemon status:
tailscaled-start --service=status
- Enable auto-start & start daemon:
tailscaled-start --service=on
- Disable auto-start & stop daemon:
tailscaled-start --service=off
- View daemon logs:
tailscaled-log
Note
"Auto-start" means when a Termux session opens, not at device boot. termux-services starts its supervisor from $PREFIX/etc/profile.d/start-services.sh, so after a reboot the node stays offline until you open Termux. To get closer to real boot start, install the Termux:Boot add-on, and consider termux-wake-lock so Android does not doze the daemon.
Configure the daemon by creating/editing ~/.tailscale/.env. It is read on both start paths — the termux-services service and a manual tailscaled-start.
| Variable | Effect | Description |
|---|---|---|
TS_SOCKS5_PORT |
--socks5-server |
SOCKS5 port on 127.0.0.1 (default 1055) |
TS_SOCKS5_SERVER |
--socks5-server |
Full address (e.g. 127.0.0.1:1055) |
TS_SOCKS5 |
— | Set to off to disable the proxy entirely |
TS_SOCKS5_USER / TS_SOCKS5_PASS |
proxy credentials | Override the generated pair |
TS_SOCKS5_NO_AUTH |
proxy credentials | 1 disables proxy authentication (not recommended) |
TS_HTTP_PROXY |
--outbound-http-proxy-listen |
HTTP proxy address |
TS_PORT |
--port |
UDP port for WireGuard |
TS_LOG_VERBOSITY |
log verbosity | 1, 2… (TS_VERBOSE is accepted as an alias) |
TS_NO_LOGS_NO_SUPPORT |
log upload | true disables log upload to Tailscale (TS_NO_LOGS is an alias) |
TS_EXTRA_ARGS |
(raw flags) | Additional raw flags to pass |
Example ~/.tailscale/.env:
TS_SOCKS5_PORT=1055
TS_LOG_VERBOSITY=1
TS_EXTRA_ARGS="--hostname=termux-node"Changes apply on the next daemon restart (sv restart tailscaled, or tailscaled-stop && tailscaled-start).
Worth knowing before you put this on a tailnet you do not own:
- Reported identity: the daemon reports itself to the control plane as
App=tailscale-cli,DeviceModel=Termux. This avoids mobile-specific client policies. Tailnet admins relying on client type for posture rules should know this node reports as a CLI client.
That is the whole list. Interface discovery and DNS used to be patched here too; they are not any more — see below.
Android has no /etc/resolv.conf, and Go's resolver reads exactly that file, so a stock Go binary resolves nothing on a phone. Termux solves this in the Go it ships, by pointing the resolver at $PREFIX/etc/resolv.conf instead — and this project builds with the same patch. So the daemon uses the same resolver as the rest of your Termux:
cat $PREFIX/etc/resolv.confTo change it, edit that file (or pkg install resolv-conf if it is missing) and restart the daemon. There is no project-specific DNS setting any more, and nothing is hardcoded to a public resolver.
If you have Go installed in Termux, you can build from source:
./install.shinstall.sh produces both a .deb and a .pkg.tar.xz in dist/.
Two build-time guards worth knowing about:
- The upstream tarball is checksummed.
checksums/<version>.sha256pins the SHA-256 of Tailscale's source archive, verified before anything is unpacked, compiled or run. A version with no pin yet is recorded and reported so you can commit it; setTS_REQUIRE_CHECKSUM=1to make an unpinned version a hard failure instead. - The binary is checked for the patches. After every compile
build.shgrepstailscaledfor the netmon,anetand SOCKS5-auth markers and fails if any are missing. A//go:buildtag that stops matching produces no warning anywhere, which is exactly how three architectures once shipped unpatched.
Note
All four architectures are built as GOOS=android with -buildmode=pie, using a Go toolchain patched with Termux's own standard-library fixes — which is what makes net.Interfaces() and DNS work on Android at all. Cross-compiling arm, i686 and x86_64 needs an Android NDK for the C compiler (Go refuses GOOS=android without cgo on those); aarch64 does not. Building on a phone needs neither: Termux's own Go already carries the patches.
Start here. One command checks the daemon, the socket, login state, the resolver, network reachability and the proxy, and prints the tail of the daemon log:
tailscale-testIt reports every check rather than stopping at the first failure, and its output is what to paste into an issue. For the full log:
tailscaled-log1. tailscale up hangs forever and status says "Logged out."
Almost always DNS. Termux has no
/etc/resolv.conf, so the daemon pins a resolver of its own — the device's, if Android reports one, otherwise 8.8.8.8, which some networks and providers block. Your shell resolves names through Android and works fine, which is why this is confusing.
tailscale-test reports whether the resolver in $PREFIX/etc/resolv.conf is reachable. If it is not, point it somewhere that works:
echo 'nameserver 1.1.1.1' > $PREFIX/etc/resolv.conf
sv restart tailscaledAny resolver works, including one on your own network.
2. "failed to connect to local tailscaled process"
If the daemon was stopped manually, start it using:
tailscaled-startOr ensure termux-services is running:
sv up tailscaled3. My SOCKS5 client stopped working after an update
The proxy now requires a password. Get it with:
tailscale-socks5and add the username/password to your client, or use the printed
socks5://user:pass@host:port URL directly.
4. Shell Autocompletions not working
Autocompletions for **Bash**, **Zsh**, and **Fish** are installed automatically. Restart your shell session or reload your shell profile to apply them.
- Core Logic: Tailscale Team.
- IPv6 UDP Probing & Netmon Enhancements: @sailshen (PR #8).
- Patch Inspiration: asutorufa/tailscale.
The tailscale and tailscaled binaries are built from Tailscale's BSD-3-Clause source; the full notice ships in the package at $PREFIX/share/doc/tailscale-termux/copyright.
Note: This project is not affiliated with Tailscale Inc.