TigerSB-client

module
v0.0.0-...-44d3390 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 2, 2026 License: GPL-3.0

README

TigerSB VPN client

Release License GPL-3.0

Xray-core 26.3.27 sing-box TUIC gVisor TUN

Go 1.26 Flutter 3.47 Kotlin 2.4 gomobile

🇷🇺 Русский  |  🇬🇧 English


TigerSB is a VPN app with nothing to set up: paste a key and you are connected. It picks the fastest server by itself, decides which sites go through the VPN and which go direct, and keeps the connection up when the network changes. It works with its own panel, TigerSB-panel, and with subscriptions from other VPNs (Marzban, 3x-ui, Remnawave and others), including Clash (YAML) and sing-box (JSON) configs, and with WireGuard and AmneziaWG.

The app interface is in Russian.

Contents: For users · For developers

For users

Quick start

  1. Download the app:
  2. Install it: on the phone open the file and allow the install; on the computer run the installer.
  3. Add a key in any of these ways:
    • open a tigersb://… link from Telegram, email or the panel, and the app opens with the key already filled in;
    • scan a QR code (on the phone);
    • paste the key by hand: tigersb://, an https:// subscription link, or vless://, vmess://, trojan://, ss://, hysteria2://, tuic://, mierus://, mieru://, naive+https://, naive+quic://, wireguard:// links, an Amnezia vpn:// key or the text of a WireGuard / AmneziaWG config (.conf).
  4. Press the connect button. That's it.

The key comes from whoever runs the server: in TigerSB-panel it is on the Users tab. The app updates itself: menu on the right → «Проверить обновление» (Check for update).

On Windows a system service holds the VPN, so it keeps working with the window closed. Menu «⋮» → «Настройки запуска» (Startup settings) starts the app with Windows: open, minimized, or with no window at all (the VPN comes back on by itself). If the VPN was on, it comes back on after a reboot.

Modes

  • Smart (default): routes like Basic, with DPI evasion tuned for your network automatically.
  • Basic: Russian sites, banks and government services go direct, everything else goes through the VPN.
  • All: all traffic goes through the VPN except the local network.

What else it does

  • Apps outside the VPN (on Android). MAX, VK, Yandex, banking, government, marketplace and mobile operator apps always bypass the VPN, so they cannot see the tunnel or the server address. You can add your own apps to the list. On Windows the same menu item is «Процессы мимо VPN» (Programs outside the VPN): pick running programs, for example a game where your account is tied to your region.
  • Protocols your way. The «Протоколы» menu turns off the protocols that work poorly on your networks; the VPN goes through the others. Mieru and NaïveProxy always show how they run (TCP, UDP or QUIC) and AmneziaWG its version (1, 2 or 3), so each can be turned off on its own.
  • Stable connection. A dead server is replaced within seconds, and the VPN stays on when the phone switches between Wi-Fi and mobile data.
  • Several profiles. The profile name at the top opens a list: switch with one tap; each has Refresh, Link and Delete.
  • Extras. Speed, traffic and ping on the home screen, a quick settings tile, the protocol in the notification, automatic profile and block-list updates, "Send log" in the menu, light and dark themes under About.
  • Styles. About also has several looks for the app, each with its own colour, home screen icon, words for the modes and effects around the button. Which ones is for you to find out.

For developers

Components

Component Role License
Xray-core 26.3.27 VPN core: VLESS (Reality, XHTTP, gRPC), VMess, Trojan, Shadowsocks, Hysteria 2; routing, balancer, latency tests MPL-2.0
sing-quic from sing-box TUIC v5, plugged into Xray as a regular outbound GPL-3.0
mieru Mieru client (TCP and UDP), plugged into Xray as a regular outbound GPL-3.0
own code (internal/naive) NaïveProxy client: CONNECT with padding over HTTP/2 in TLS with Chrome's fingerprint or over HTTP/3 in QUIC, plugged into Xray as a regular outbound GPL-3.0
amneziawg-go WireGuard and AmneziaWG 1, 2 and 3 (junk packets, padding, header ranges, I1–I5 signature packets, header protection) with its own in-memory network stack, plugged into Xray as a regular outbound MIT
gVisor network stack for the system VPN (TUN) Apache-2.0
Go 1.26 and gomobile client core, the tigersb-core CLI, Android library BSD-3-Clause
Flutter 3.47 and Dart app interface BSD-3-Clause
Kotlin 2.4 Android system VPN (VpnService), network watcher, Keystore Apache-2.0
Wintun and winipcfg the VPN network adapter on Windows, its address, routes and DNS Wintun: free redistribution, winipcfg: MIT
Inno Setup the Windows installer its own, free

Code layout: pkg/profile is the profile and key format (the panel uses it too), internal/ is the core (subscriptions, Xray config builder, routing and DPI evasion, TUIC, Mieru, NaïveProxy and AmneziaWG, meters, network auto-tuning), mobile/ is the core's API (gomobile for Android; the Windows service calls it), desktop/ and cmd/tigersb-service are the Windows VPN service, app/ is the Flutter app (Kotlin for Android, C++ for the Windows window), cmd/tigersb-core is the CLI.

How it works

  • One core everywhere. Xray-core runs inside the process, with no separate programs. On Android traffic arrives through the system VPN (TUN on gVisor), and no local ports are open.
  • Windows. The core runs in the tigersb-service service (SYSTEM) and traffic arrives through the Wintun adapter «TigerSB», which the service gives an address, the 0/1 and 128/1 routes, DNS and the MTU. The core binds its own connections to the real interface (IP_UNICAST_IF), so they never enter the tunnel. The app runs without administrator rights and controls the service over 127.0.0.1 with a token from a file only the computer's users can read. The watchdog and the network follow are the same as on Android.
  • Smart routing. Routes like Basic (Russian sites direct, the rest through the VPN), plus DPI evasion for every protocol over TCP (Xray, NaïveProxy, Mieru): fragmentation instead of zapret, with the Xray preset tuned on every connect, network change and channel failure. Protocols over QUIC (Hysteria 2, TUIC, NaïveProxy QUIC) send noise before each connection. The protocol's name shows what was added. The protocol is picked by speed, with no TCP priority. The LTE mode and MTU tuning work in every mode. Details: docs/profile.md (in Russian).
  • List mode (main, in the CLI) splits traffic three ways from the TigerSB profile: blocked sites go through the exit abroad, everything else through the exit in Russia (the ISP sees nothing, sites see a Russian IP), and banks, government services and universities go direct.
  • Stability. In Basic and All the protocol is chosen from smoothed measurements without flapping between servers. The channel is checked with two GETs to t.me and YouTube over one connection; two failures in a row reopen the connections to the servers and four restart the core. A network change does not rebuild the tunnel, and with no internet at all the client waits instead of restarting. The MTU (1480, 1460 or 1280) follows how large a packet reaches the server without fragmenting; on mobile data TCP segments are clamped to that path and the operator's NAT is kept open.

Security

  • Signed profile. The TigerSB profile is signed with Ed25519, and the panel's public key is pinned in the tigersb:// key (pk). A profile with any other signature is rejected, so nobody on the way can swap the servers. For an https:// link without pk, the key of the first profile received is pinned. Subscriptions are fetched over HTTPS only.
  • Certificate pinning. For servers with a self-signed certificate (insecure=1 in the link) the client remembers the certificate's SHA-256 at import and accepts only that one afterwards, instead of the unsafe allowInsecure.
  • Key storage. The state file with the subscription key is encrypted with AES-256-GCM, and the encryption key is kept in Android Keystore. App backups are off (allowBackup=false). On Windows the service's data in %ProgramData%\TigerSB\data is open only to the system and administrators, and the encryption key is sealed with DPAPI.
  • Screen protection. FLAG_SECURE blocks screenshots and screen recording, taps through other windows are ignored, and other apps' overlays are hidden.
  • App isolation. MAX, VK, Yandex, banking, government, marketplace and mobile operator apps are excluded from the tunnel by the system (addDisallowedApplication) and cannot see the server address. The panel cannot turn this list off.
  • Updates. The app takes version.json and the APK only from this repository's GitHub release and hands the APK to the system installer. Android installs an update only when it is signed with the same key as the installed version. On Windows the app takes version-windows.json and the installer of its architecture from the same release.
  • Device limit. When fetching a subscription the client sends x-hwid and device details, as Remnawave and similar panels expect, so the server can count devices.

Command-line tool

go build -o tigersb-core ./cmd/tigersb-core

./tigersb-core import 'tigersb://add?url=...&pk=...'   # or https://…, vless://…, hysteria2://…, tuic://…, mierus://…, naive+https://…
./tigersb-core run                                     # SOCKS5 127.0.0.1:10808, HTTP 127.0.0.1:10809, user tigersb, password in proxy-password
All commands and modes
Command What it does
tigersb-core import <key> add a key and download the profile
tigersb-core update refresh the profile from the subscription
tigersb-core show show exits, transports and list sizes
tigersb-core run [-mode auto|main|all|off] run the VPN with local SOCKS and HTTP ports
tigersb-core config [-mode …] print the Xray config that would run
tigersb-core keygen create profile signing keys (for the panel)
tigersb-core sign -key … -in … sign a profile
tigersb-core link -url … -pk … build a tigersb:// key

Modes: auto tries every site through every server (default), basic sends Russian sites, banks and universities direct and the rest through the VPN, main uses the three-way lists, all sends everything through the VPN, off disables the VPN.

If the profile uses geosite: or geoip:, run downloads geosite.dat and geoip.dat into the state folder and keeps only the lists it needs. Use -assets to point at your own folder.

State (the key and the last profile) lives in %AppData%\TigerSB on Windows and ~/.config/TigerSB on Linux, readable only by the user.

Build and test

go test ./...
CGO_ENABLED=0 go build -o tigersb-core ./cmd/tigersb-core

The tests build configs for every mode and check that the real Xray-core accepts them.

The Android app lives in app/ (Flutter, with the system VPN in Kotlin under app/android/app/src/main/kotlin). Its core is built from the mobile/ package with gomobile:

scripts/build-core-android.sh        # needs the Android SDK and NDK
cd app && flutter build apk --split-per-abi

The Windows app is built on Windows (Visual Studio with C++ and Inno Setup needed):

GOARCH=amd64 go build -o dist/service/tigersb-service.exe ./cmd/tigersb-service   # put wintun.dll of the same architecture next to it
cd app && flutter build windows
iscc /DArch=x64 /DAppDir=... /DServiceDir=... windows/installer/TigerSB.iss

Usually you don't need to: GitHub Actions builds the APK and the Windows installers (artifact TigerSB-windows, with a check of the installed VPN on Windows) for every pull request (Actions tab, artifact TigerSB-android) and publishes the release from a tag. Publishing a version and setting the APK signing key: docs/releases.md. Profile and key format: docs/profile.md (both in Russian).

Licenses

The client is GPL-3.0, see LICENSE. The reason: the TUIC client comes from sing-box (the sing-quic and sing libraries, GPL-3.0), so the whole client is released under that license.

  • Other dependencies are MPL-2.0 (Xray-core), Apache-2.0, BSD, MIT and LGPL, all compatible with GPL-3.0. scripts/check-licenses.sh checks them on every pull request.
  • The full list with versions is in THIRD_PARTY_NOTICES.md, and the full texts are in the app under «О приложении» (About) → «Лицензии компонентов» (Component licenses).
  • The server side, TigerSB-panel, is GPL-3.0 too.

Directories

Path Synopsis
cmd
tigersb-core command
Command tigersb-core is the TigerSB client core as a console tool: import a key, build the Xray config and run it with local proxy ports.
Command tigersb-core is the TigerSB client core as a console tool: import a key, build the Xray config and run it with local proxy ports.
tigersb-service command
Command tigersb-service is the VPN service of TigerSB for Windows.
Command tigersb-service is the VPN service of TigerSB for Windows.
Package desktop runs the VPN on a computer: a system service holds the core and the TUN, and the app, which runs without administrator rights, controls it over a local connection (Serve).
Package desktop runs the VPN on a computer: a system service holds the core and the TUN, and the app, which runs without administrator rights, controls it over a local connection (Serve).
internal
awg
Package awg carries WireGuard and AmneziaWG transports.
Package awg carries WireGuard and AmneziaWG transports.
bypass
Package bypass keeps the core's own connections out of the VPN on systems where the core runs behind its own TUN.
Package bypass keeps the core's own connections out of the VPN on systems where the core runs behind its own TUN.
carry
Package carry has what the outbounds of protocols Xray does not have (TUIC, mieru, NaïveProxy) share: each is an Xray outbound handler added under its transport's tag, so pick outbounds, the observatory and the per-site picker use it like any other outbound, and its traffic is counted like Xray's.
Package carry has what the outbounds of protocols Xray does not have (TUIC, mieru, NaïveProxy) share: each is an Xray outbound handler added under its transport's tag, so pick outbounds, the observatory and the per-site picker use it like any other outbound, and its traffic is counted like Xray's.
certpin
Package certpin replaces "allowInsecure" in share links and third-party subscriptions with a pin of the server's certificate.
Package certpin replaces "allowInsecure" in share links and third-party subscriptions with a pin of the server's certificate.
device
Package device describes the computer to subscription servers.
Package device describes the computer to subscription servers.
engine
Package engine runs Xray-core in-process from a generated config.
Package engine runs Xray-core in-process from a generated config.
geodata
Package geodata downloads geosite.dat and geoip.dat when a profile's routing lists use "geosite:" or "geoip:", and keeps only the lists the profile needs: the full Russian files weigh about 90 MB, a trimmed copy a few megabytes.
Package geodata downloads geosite.dat and geoip.dat when a profile's routing lists use "geosite:" or "geoip:", and keeps only the lists the profile needs: the full Russian files weigh about 90 MB, a trimmed copy a few megabytes.
meter
Package meter reads what the app shows about a running VPN: the traffic that went through the servers and the ping of the server in use.
Package meter reads what the app shows about a running VPN: the traffic that went through the servers and the ping of the server in use.
mieru
Package mieru carries mieru transports.
Package mieru carries mieru transports.
naive
Package naive carries NaïveProxy transports.
Package naive carries NaïveProxy transports.
netauto
Package netauto picks network settings from the network the device is on, so the user never has to tune them.
Package netauto picks network settings from the network the device is on, so the user never has to tune them.
steady
Package steady keeps one transport of an exit in use: the fastest live one, chosen without flapping.
Package steady keeps one transport of an exit in use: the fastest live one, chosen without flapping.
subscription
Package subscription imports a key, downloads the profile (a signed TigerSB profile or another VPN's list of servers) and keeps it on disk.
Package subscription imports a key, downloads the profile (a signed TigerSB profile or another VPN's list of servers) and keeps it on disk.
tuic
Package tuic carries TUIC v5 transports.
Package tuic carries TUIC v5 transports.
xrayconf
Package xrayconf turns a profile and a mode into an Xray JSON config.
Package xrayconf turns a profile and a mode into an Xray JSON config.
Package mobile is the core API the Android app calls through gomobile bind.
Package mobile is the core API the Android app calls through gomobile bind.
pkg
profile
Package profile defines the TigerSB client profile (format v1): the set of exits, their transports and the routing lists the panel hands to a client.
Package profile defines the TigerSB client profile (format v1): the set of exits, their transports and the routing lists the panel hands to a client.
scripts
licensetexts command
Command licensetexts writes the license texts of the Go modules inside the core, and of TigerSB itself, to app/assets/licenses.json.
Command licensetexts writes the license texts of the Go modules inside the core, and of TigerSB itself, to app/assets/licenses.json.
soak command
Command soak runs the test servers for the long emulator test (scripts/soak-android.sh): the app on the emulator connects to them at 10.0.2.2 and its traffic leaves through the runner's network.
Command soak runs the test servers for the long emulator test (scripts/soak-android.sh): the app on the emulator connects to them at 10.0.2.2 and its traffic leaves through the runner's network.
soak/load
Package load is the client of the soak test's bulk server: it downloads, uploads and keeps a stream going both ways through the VPN, as apps do.
Package load is the client of the soak test's bulk server: it downloads, uploads and keeps a stream going both ways through the VPN, as apps do.
soakload command
Command soakload runs on the emulator during the soak test (scripts/soak-android.sh) and loads the VPN like an app: a download, an upload or a stream both ways to the bulk server of scripts/soak, reached by its address through the tunnel.
Command soakload runs on the emulator during the soak test (scripts/soak-android.sh) and loads the VPN like an app: a download, an upload or a stream both ways to the bulk server of scripts/soak, reached by its address through the tunnel.
wincheck command
Command wincheck checks the installed Windows app's VPN service on a CI runner, as the app drives it: it adds a key of the test servers (scripts/soak, started with -outside on this computer), connects in the given mode, opens sites through the TUN, reads the traffic through the server, follows a restart of the service and disconnects.
Command wincheck checks the installed Windows app's VPN service on a CI runner, as the app drives it: it adds a key of the test servers (scripts/soak, started with -outside on this computer), connects in the given mode, opens sites through the TUN, reads the traffic through the server, follows a restart of the service and disconnects.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL