Skip to content

Welcome to Surf Shield

Surf Shield is a next-generation VPN orchestration panel and SDK ecosystem, powered by the Rust-based Leaf core.

Designed for environments with heavy network filtering, Surf Shield uses advanced routing, Deep Packet Inspection (DPI) bypass techniques, and connection multiplexing to ensure uninterrupted access.

Ecosystem Overview

  1. Panel & Orchestration — central hub that manages multi-tenant billing, crypto payments (via NOWPayments), user bandwidth limits, and dynamically distributes connection settings to remote nodes.
  2. Node Agents — Linux servers running the Surf Shield Core that accept user traffic and report telemetry (bandwidth, CPU, RAM) back to the panel.
  3. Client SDKs — drop-in libraries for your custom frontend applications (Android, Windows, macOS, Linux) to fetch dynamic, geo-optimized routing rules directly from the panel and run the Leaf core locally.
  4. Leaf Core & leaf-util — the shared Rust runtime that performs subscription fetching, configuration generation, asset updates (GeoIP/Geosite), integrity verification, and proxy routing.

SDK Matrix

SDK Language Target Platforms Registry / Package Repository
leaf-sdk-android Java / JNI Android 5.0+ (API 21+) com.github.shiroedev2024:leaf-sdk-android → maven-public samples: leaf-android, sample-android-java
leaf_sdk_desktop Rust Windows, macOS, Linux leaf_sdk_desktop → cargo.surfshield.org (Kellnr, token) sample: leaf-desktop
FFI C ABI any language with C-FFI libleaf.{so,dll,dylib} + leaf.h → static-public
leaf-sdk-java Java (JNI) Windows, macOS, Linux com.github.shiroedev2024:leaf-java-sdk → maven-public sample: kotlin-multiplatform-desktop

See the full Distribution & Registries page for URLs, tokens, and platform triples.

All SDKs share the same Rust leaf-util back-end for:

  • subscription fetching (update_subs, import_offline_subscription)
  • asset updates (try_update_assets → geoip.dat, geosite.dat)
  • preferences persistence (see Preferences Reference)
  • file integrity verification (verify_file_integrity)

Key Features

  • MPTP (Multi-Path Transport Protocol) — native multiplexing over multiple concurrent TCP/UDP streams to bypass bandwidth throttling.
  • TLS Fragmentation — dynamically fragment TLS Client Hello packets to evade SNI-based filtering.
  • FakeTCP & Stealth — advanced obfuscation protocols designed to look like standard web traffic or native OS connections.
  • Speed-test & Try-All selection — optional per-subscription flags that select the fastest working endpoint automatically.
  • GeoIP / Geosite routing — bypass or reject entire countries or content categories without restarting the core.
  • Fake-IP DNS — prevent DNS leaks by resolving domains to pool IPs inside the core.
  • Local runtime API — every platform exposes a 127.0.0.1:<port> HTTP API for live stats, logs, outbound selection, and health checks.
  • Hands-off auto-routing — desktop core owns the system route table, pins OUTBOUND_INTERFACE to the physical uplink, tracks Wi-Fi ↔ cellular switches, and triggers failover health checks on every change. See Leaf Core — Auto-Routing.
  • Android kill-switch & network-switch survivability — SUPPORTS_ALWAYS_ON=true merges automatically; setUnderlyingNetworks + notifyNetworkChanges keep the tunnel alive when the user roams. See Android SDK — Always-on VPN & Kill Switch.

⚡ The "Always-On" Engine: Smart Routing & Zero IP Leaks

Our SDK is fundamentally designed for continuous, uninterrupted operation. Unlike traditional VPNs that require users to manually guess the best protocol and physically reconnect when networks change, Surf Shield provides an intelligent, "activate once and forget" experience that runs for days or weeks without a single process restart.

  • Smart Protocol Selection & Load Balancing: The SDK features a professional, background load-balancing engine. If a user transitions from a 5G cellular network (where Protocol A might be optimal) to a restrictive Wi-Fi network, the system detects the network flap and automatically triggers a background health re-evaluation. It seamlessly shifts traffic to Protocol B or a better-performing node without dropping the active tunnel or requiring user intervention.
  • Real-Time Country & Node Switching: Changing VPN countries or selecting a specific node (e.g., jumping from Node A to Node B in the US) is handled in real-time through our local Runtime API. The core hot-swaps the routing targets instantly—there is no process restart and no downtime.
  • 100% Leak Prevention: Because the underlying TUN device and OS routing tables are never torn down during network flaps, SIM card switches, or API-driven node changes, both our Android and Desktop SDKs guarantee absolute data security. Not a single IP packet leaks outside the encrypted tunnel during a transition.
  • Frictionless UX: Eliminates the need for users to manually experiment with protocols or servers, which traditionally results in connection drops and frustration. The SDK handles the complexity of censorship evasion silently.

Where to go next?

Licensing & support

  • The Leaf core is closed source and distributed as prebuilt binaries. Redistribution inside your app is permitted under your customer agreement.
  • Every SDK, helper crate, and sample client is open source under Apache 2.0 — fork and rebrand freely.
  • Questions, licensing, or a Kellnr token for cargo.surfshield.org → support@surfshield.org (see Support).