TailSocks

Advanced Tailscale Client for Android with Userspace Networking & Transparent TUN VPN

 

---

TailSocks is a high-performance Android client for Tailscale that operates in userspace-networking mode via tsnet. It provides a complete Tailscale environment — including Taildrop™, Exit Nodes, Serve & Funnel, and Taildrive™ — without requiring Android's VpnService permission, enabling seamless coexistence with other VPN and firewall applications.

Optionally, TailSocks supports a transparent TUN VPN mode powered by the native hev-socks5-tunnel engine, providing full or split tunnel routing for system-wide connectivity.

---

✨ Features

Networking & Connectivity

Feature	Description
Native LocalAPI	100% CLI-less daemon management via Unix socket (tailscaled.sock) using LocalAPI v0. No shell commands.
SOCKS5 Proxy	Built-in local SOCKS5 proxy server with optional authentication for per-app routing.
Control Plane Proxy	Route coordination server traffic through a custom SOCKS5/HTTP proxy for restricted regions.
TUN VPN Mode	Transparent system-wide VPN via native hev-socks5-tunnel — full tunnel & split tunnel, per-app exclusions, custom gateway IP.
Exit Nodes ©	Route all internet traffic through any authorized Tailscale peer with auto-healing and LAN access.
MagicDNS ©	In-memory peer resolution (0ms), Split DNS over SOCKS5 TCP, smart upstream fallback with DoH support.
NAT Traversal	Real-time InMagicSock connectivity monitoring. STUN/DERP diagnostics via native netcheck.

Services & File Sharing

Feature	Description
Tailscale Serve & Funnel ©	Expose local ports to your Tailnet or the public internet. TCP & HTTPS modes, TLS certificate export.
Tailscale Services (svc:) ©	Create named virtual services with dedicated VIPs and DNS names, managed from native UI.
Taildrop™ ©	Send & receive files between Tailnet devices. Inbox hub, system Share Sheet integration, DocumentsProvider.
Taildrive™ ©	Share local folders over WebDAV. SAF integration, remote share mounting, SOCKS5-proxied access. Cross-platform path case-insensitivity fixes.

Management & Administration

Feature	Description
Multi-Account Isolation	Strict per-profile data separation — independent state dirs, preferences, keypairs, and Taildrop folders.
Tailscale Admin API	Full api.tailscale.com/v2 integration — manage devices, DNS, users, services, webhooks, ACLs, and audit logs.
Biometric Lock	Admin Console protected by fingerprint/face authentication.
Auth Keys	Generate, view, and revoke authentication keys from inside the app.
Data Portability	Full encrypted app state backups (ZIP) and individual account exports (JSON).

User Experience

Feature	Description
Compact Dashboard	High-density 2×4 grid — Console, Peers, Logs, Files, DNS, Netcheck, Settings, Serve.
Material 3 Theming	System, Light, Dark, AMOLED Black modes. 7 color presets + Material You dynamic colors.
Localization	Crowdin-compatible i18n system. Russian language included.
Home Screen Widgets	Jetpack Glance widgets — Service Toggle, Exit Node, Stats Dashboard, Serve status.
Quick Settings Tile	System Quick Settings tile with active profile display and account switching.
Network Diagnostics	Native netcheck with DERP latency visualization, NAT type detection, and public IP reporting.

---

📸 Screenshots

Interface Screenshots

Main Dashboard	Account Switcher	Peers List
System Logs	Taildrop™ (Incoming)	Taildrive™ Shares
DNS Management	App Settings	Profile Settings
Network Diagnostics	Serve & Funnel	Send via Taildrop™

---

🏗️ Architecture

TailSocks is built as a hybrid multi-layer system:

┌─────────────────────────────────────────────────────────────────┐
│                    Jetpack Compose UI (Kotlin)                  │
│  Dashboard · Peers · Logs · DNS · Netcheck · Serve · Settings   │
│  Admin API Console · Taildrive · Taildrop · TUN Config          │
├─────────────────────────────────────────────────────────────────┤
│                   JNI / Gomobile Bridge (appctr)                │
│  LocalAPI Client · DNS Proxy · IPN Bus · Netcheck · Taildrop    │
├─────────────────────────────────────────────────────────────────┤
│              Tailscale Daemon (libtailscale.so)                 │
│  tsnet · WireGuard · magicsock · DERP · Serve/Funnel · Drive    │
├───────────────────────┬─────────────────────────────────────────┤
│   SOCKS5 Proxy Mode   │       TUN VPN Mode (optional)           │
│  Per-app proxying via │   System-wide routing via native        │
│  local SOCKS5 server  │   hev-socks5-tunnel (C library)         │
│  (no VpnService)      │   Full/Split tunnel + app exclusions    │
└───────────────────────┴─────────────────────────────────────────┘

Core Components

Layer	Technology	Purpose
Daemon	Go → libtailscale.so (PIE)	Patched Tailscale core compiled with aggressive build tags to strip desktop/enterprise features. Targets arm64, arm, x86, x86_64.
Bridge	Go → appctr.aar (Gomobile)	High-speed JNI bridge handling LocalAPI calls, DNS proxying, IPN bus monitoring, netcheck, Taildrop, and Taildrive WebDAV.
App	Kotlin + Jetpack Compose	Material 3 UI, foreground service lifecycle, Android system integrations (SAF, Widgets, Quick Settings, Share Sheet).
TUN Engine	C → hev-socks5-tunnel	Optional transparent VPN interface. Routes traffic through the SOCKS5 proxy at kernel level. Per-app and per-IP exclusions.

Key Design Patterns

• Stateless Configuration: Every config update is explicit. Serve/Funnel uses a "Reset-then-Apply" pattern (POST {} → POST new config) to prevent stale daemon state.
• Passive Daemon Management: No aggressive polling loops. The daemon manages its own lifecycle, policy sync, and reconnection.
• Account Isolation: State in files/states/{id}/, preferences in appctr_{id}. Full daemon restart on profile switch.
• DNS Wrapping: MagicDNS resolved from in-memory node cache. Split DNS wrapped as TCP-over-SOCKS5. Fallback chain: SOCKS5 UDP → Direct UDP → DoH.
• 410 Wall Mitigation: Configuration updates are blocked while a Login URL is active to protect authentication sessions.

Upstream Patches

TailSocks maintains 11 minimal atomic patches in appctr/patches/ to inject capabilities not exposed via LocalAPI:

Patch	Purpose
01-enable-socks-android	Enable SOCKS5 support in userspace-networking on Android
02-socks5-auth	Add username/password fields to the outbound SOCKS5 listener
03-taildrop-monolithic-fs	Pure-Go fsFileOps to avoid JNI panics in Taildrop
04-vip-services	Append VIP services to HostInfo for coordination server visibility
05-localapi-cert	Enable /cert endpoint compilation on Android
06-android-netmon	Custom netmon.InterfaceGetter for Android 10+ netlink restrictions
07-taildrive-android	Android-specific Taildrive adaptations
08-netstack-cgnat	CGNAT routing fix for netstack
09-netstack-loopback	Loopback routing for self-addressed packets in netstack
10-taildrive-userspace-dial	Route remote peer WebDAV via tsdial.Dialer
11-noop-dns-fallback	DNS fallback env var injection for SERVFAIL prevention

---

🚀 Getting Started

Download

Grab the latest APK from the Releases page, or use the download buttons at the top of this README.

Supported architectures: arm64-v8a, armeabi-v7a, x86, x86_64
Minimum Android version: 5.0 (API 21)

Build from Source

Build instructions

Prerequisites:

• Android NDK (set ANDROID_NDK_HOME)
• Go 1.23+
• gomobile (go install golang.org/x/mobile/cmd/gomobile@latest && gomobile init)
• Android SDK with Gradle

1. Clone:

git clone --recurse-submodules https://github.com/bropines/tailsocks.git
cd tailsocks

2. Compile Go core (downloads Tailscale v1.98.3 source, patches, and cross-compiles):

cd appctr
bash build.sh
cd ..

3. Build APK:

./gradlew app:assembleRelease

The build script automatically downloads the correct Tailscale version, applies all patches, and compiles PIE binaries for 4 architectures. No fork maintenance required.

---

📚 Documentation

Document	Description
Architecture Deep Dive	DNS wrapping, account isolation, netcheck, and patch analysis
Build Instructions	NDK setup, Go core compilation, dynamic patch pipeline
Project Retrospective	Evolution from PoC to the current architecture
AdGuard Setup	Coexistence with system-wide ad blockers
Serve & Funnel Guide	Exposing local ports and virtual services
Roadmap	Planned features and short-term goals
Changelog	Full version history

🌐 Restricted Regions & DPI Bypass

For users in restricted regions (e.g., where controlplane.tailscale.com is blocked/dropped), TailSocks offers an in-app bypass mechanism for the control plane:

1. Control Plane DPI Bypass (ByeDPI JNI)

TailSocks bundles a native JNI implementation of ByeDPI directly inside the app process. This allows bypassing SNI-based deep packet inspection (DPI) without spawning external binary processes.

• Security: ByeDPI binds strictly to a randomized loopback IP (e.g., 127.182.201.43) and a randomized port in the 127.0.0.0/8 subnet upon every startup. This prevents other applications on the device from discovering or connecting to the proxy via simple port scanning.
• Usage: Enable DPI Bypass (ByeDPI) in Settings -> Network Tab -> Control Proxy settings and configure custom ByeDPI flags (default: -s 1 -d split -r).

---

🤝 Credits & Acknowledgements

App & Patches	Bropines — app development, architecture, and the majority of upstream patches
Initial Android Patches	Asutorufa — original Android networking (anet) and network monitor (netmon) patches that served as a starting point
DPI Bypass	hufyhang/byedpi — local HTTP/SOCKS5 DPI bypass utility
TUN Engine	heiher/hev-socks5-tunnel — native SOCKS5-to-TUN implementation
Core Engine	Tailscale Inc. — userspace networking engine (tsnet)
AI Assistant	Google Gemini — interface development, LocalAPI research, and patch engineering

---

📜 License

Distributed under the BSD-3-Clause License. See LICENSE for details.

Tailscale, Taildrop, Taildrive, MagicDNS, and Funnel are trademarks of Tailscale Inc. This project is an independent open-source contribution and is not affiliated with Tailscale Inc.