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 sample: leaf-android
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

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.

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 → [email protected] (see Support).