Surfing

Magisk, Kernelsu, APatch

English | 简体中文

---

This project is a Magisk, Kernelsu, APatch module for Clash/mihomo, sing-box, v2ray, xray, hysteria. It supports REDIRECT (TCP only), TPROXY (TCP + UDP) transparent proxy, TUN (TCP + UDP), and hybrid mode REDIRECT (TCP) + TUN (UDP) proxy.

Based on upstream integration for one-stop service, ready to use. Suitable for:

• Lazy people
• Beginners

The project's theme and configuration focus on Clash/mihomo.Meta.

This module needs to be used in a Magisk/Kernelsu environment. If you don't know how to configure the required environment, you might need applications like ClashForAndroid, v2rayNG, surfboard, SagerNet, AnXray.

Surfing User Declaration and Disclaimer

Welcome to use Surfing. Before using this project, please carefully read and understand the following statements and disclaimers. By using this project, you agree to accept the following terms and conditions. Hereinafter referred to as Surfing.

Disclaimer

1. This project is an open-source project for learning and research purposes only and does not provide any form of guarantee. Users must bear full responsibility for the risks and consequences of using this project.

2. This project is only for the convenience of simplifying the installation and configuration of Surfing for Clash services in the Android Magisk environment. It does not make any guarantees about the functionality and performance of Surfing. The developer of this project is not responsible for any problems or losses.

3. The use of this projects Surfing module may violate the laws and regulations of your region or the terms of service of service providers. You need to bear the risks of using this project on your own. The developer of this project is not responsible for your actions or the consequences of use.

4. The developer of this project is not responsible for any direct or indirect losses or damages resulting from the use of this project, including but not limited to data loss, device damage, service interruption, personal privacy leaks, etc.

Instructions for Use

1. Before using the Surfing module, please make sure you have carefully read and understood the usage instructions and related documents of Clash and Magisk and comply with their rules and terms.

2. Before using this project, back up your device data and related settings to prevent unexpected situations. The developer of this project is not responsible for your data loss or damage.

3. Please comply with local laws and regulations and respect the legitimate rights and interests of other users when using this project. It is forbidden to use this project for illegal, abusive, or infringing activities.

4. If you encounter any problems or have any suggestions when using this project, you are welcome to provide feedback to the developer of this project, but the developer is not obligated to resolve issues or respond to feedback.

Please decide whether to use the Surfing module only after clearly understanding and accepting the above statements and disclaimers. If you do not agree or cannot accept the above terms, please stop using this project immediately.

Applicable Law

During the use of this project, you must comply with the laws and regulations of your region. In case of any disputes, interpretation and resolution should be carried out in accordance with local laws and regulations.

Installation

• Download the module zip file from the Release page and install it via Magisk Manager, KernelSU Manager, or APatch.
• Version changes: 📲log

Uninstall

• Uninstall this module directly from Magisk Manager / KernelSU Manager / APatch
  👉🏻 Force Remove Script

Uninstalling this module via the manager will remove all related service data, including Web and SurfingTile tile app data.

Wiki

1. FirstTime Use

• After the module is installed for the first time, please first add your subscription URL in
  /data/adb/box_bll/clash/config.yaml, or do it via the Web Desktop App
  (Note: SurfingTile must be invoked and Root permission is required), then manually reboot your device once.

• After rebooting, toggle the module switch once, open the Web App on your desktop, and you can start using it.

• Due to network issues, not all rules/subscriptions may download automatically; please manually refresh them in the panel.

• If subscriptions fail to load, try switching the Ua in the configuration file.

• If the above fails, ensure your network environment is normal.

• Web App:

  • Can be used via Menu → Config Override → Fill in subscription
  • Used for portable browsing and managing backend routing data
  • Automatically updates core files on startup

If the panel content is displayed abnormally or cannot be displayed,
please update the com.google.android.webview component via Google Play Store.

2. Controlling Operation

• You can control start/stop via WiFi SSID.
• You can control service using the module toggle switch
  Changes take effect in real time, no reboot required
• You can add the module's control tile to the system status bar
  If SurfingTile is already installed

3. Routing Rules

• GitHub Actions builds automatically
  All routing rules use online subscriptions to ensure they are always up-to-date

Automatically updates every 24 hours

4. Future Updates

• If you are using all default configurations, updates will be seamless.
• Supports online updates from the client; reboot is not required, but still recommended.
• During updates, configuration files will be backed up to:
  • config.yaml.bak
• User configuration files will be backed up to:
  • box.config.bak
• Subscription URLs will be automatically extracted and backed up to:
  • proxies/subscribe_urls_backup.txt
  • The backup will be automatically restored into the new configuration, suitable for default configuration usage.

Ps: Mainly follows upstream updates and pushes some configuration adjustments.

5. Usage Issues

Proxy Specific Apps (Blacklist / Whitelist)

• To proxy all apps except certain ones, open /data/adb/box_bll/scripts/box.config,
  set proxy_mode to blacklist (default), and add elements to the user_packages_list array.
  The element format is id:package_name, separated by spaces.
  These apps will not be proxied.
  Example: user_packages_list=("id:package_name" "id:package_name")

• To proxy only specific apps, open /data/adb/box_bll/scripts/box.config,
  set proxy_mode to whitelist, and add elements to the user_packages_list array.
  The element format is id:package_name, separated by spaces.
  Only these apps will be proxied.
  Example: user_packages_list=("id:package_name" "id:package_name")

Android user group IDs:

User Type	ID
Owner	0
Phone Clone	10
Multiple Apps	999

You can usually find all user group IDs and app package names under /data/user/.

Tun Mode

• Disabled by default
• When using blacklist/whitelist, exclude the corresponding package names

Can be enabled or disabled manually via configuration if needed.

Routing Rules

• Optimized for Mainland China
• Meets most daily usage requirements

With increasingly robust routing rules, blacklist/whitelist is becoming less necessary.

Panel Management

• Magisk font modules

May affect proper display of panel fonts.

LAN Sharing

• Enable hotspot to allow other devices to connect
• Tun Gateway: 172.20.0.1

To access the backend console from other devices:
http://<CurrentWiFi>/<TunGateway>:9090/ui

Host File

• No need to mount: just delete the file
• To remount: create a new one in the etc folder
• All changes take effect immediately
• During update/installation, you can use volume keys Up(Mount) / Down(Unmount) to choose

Local IP redirection for domains, forced binding

6. SurfingTile App

Quick Settings Tile Service

📱 Device Requirements

Supports Android 8+, recommended to run on Android 10+

• Must run in system space and require Root permission
• For KSU users, you need to install the "Meta Module" to obtain mount permissions
• The tile works entirely based on the Clash API, please check if the API settings are correct
  • Path: → Web App → Menu → Tile Settings

Features

• Supports app filtering, network filtering, and partial config override via UI
• Supports managing and clearing redundant useless data in the core connection pool

Permission Declaration

• GPS Location → Used to obtain Saved WiFi Network List
• App List → Used to obtain Installed App Package List

All network requests of this app are initiated via HttpURLConnection,
and are strictly used to communicate with the local Clash core service.

Detailed usage:

API Address

• Default: http://127.0.0.1:9090
• Can be modified in the app's API settings

Functions

1. Check Service Status

• Uses the /version endpoint to determine whether Clash is running
• Method: isApiAliveHttp

2. Get and Switch Proxies

• Uses GET and PUT requests to /proxies/total_mode
• Used to get the current selected proxy
• Double-tap the tile to switch to the next proxy
• Method: cycleTotalModeProxy

3. Manage Connections

• Uses GET and DELETE requests to /connections
• Fetch current network connections
• Clean up useless or stale connections
• Methods:
  • clearAllConnections
  • probeAndCleanStaleConnections

---

Two Different Network Usage Scenarios in This Project

1. Communicating with Local Proxy Service (Core Function)

• Path: SurfingTileService.java
• Address: http://127.0.0.1:9090
  (or other address specified in settings)
• Purpose:
  Core functionality of the app, using HTTP (GET, PUT, DELETE) to communicate with the local Clash backend service for:
  • Checking service status
  • Getting / switching proxies
  • Managing and cleaning connections

2. Fetching Quotes from the Internet (UI Function)

• Path: AppFilterActivity.java
• Purpose:
  In the app filter UI (AppFilterActivity), the app fetches data from the project's GitHub repository and randomly displays a quote.
  This is a non-core UI feature.

The necessity of the INTERNET permission is reflected in two aspects:

1. Interacting with the local proxy core (required)
2. Fetching remote text content for display

These are the only network-related behaviors in this project.

---

3. FAQ

• App filter cannot display app list:
  You can first disable the mount of the SurfingTile sub-module, reboot the device, then re-enter permission management and grant App List permission / GPS permission (for WiFi SSID).

• Tile status shows No Sys | No Root:
  Not running as a system app / Root permission not granted.

• Partial workflow diagrams
  

---

Acknowledgements

CHIZI-0618

MetaCubeX

Loyalsoldier

> Thanks for providing valuable foundation for the implementation of this project. <