KunBox for Android

OLED Hyper-Minimalist

A next-generation Android proxy client designed for those who pursue ultimate performance and visual purity.
Cut the clutter, return to the essence of networking.

Download • Features • Protocols • Architecture • Quick Start • Community

中文文档

---

💖 Sponsorship

Thanks to the following users for their generous support:

Thanks to ForZTN for supporting KunBox.

Sponsor	Amount
@WestWood	¥30

Your support is our motivation for continuous development! If you wish to sponsor, please contact us via Telegram.

---

📥 Download and Installation

Download from GitHub Releases

Visit the Releases page to download the latest APK file.

Note: Release assets include arm64-v8a and armeabi-v7a builds.

System Requirements

Item	Minimum Requirement
Android Version	Android 7.0 (API 24)
Architecture	arm64-v8a / armeabi-v7a
Storage	~15MB

Installation Methods

1. Direct Install: Download APK and tap to install (requires permission to install from unknown sources)
2. ADB Install: adb install KunBox-x.x.x.apk

---

✨ Core Features

🎨 OLED Pure Black Aesthetics (Hyper-Minimalist UI)

Unlike traditional Material Design, we've adopted a deeply customized True Black interface. Not only does it achieve pixel-level power saving on OLED screens, but it also brings a deep, immersive visual experience. The distraction-free UI design makes key information (latency, traffic, nodes) clear at a glance.

• Gengar Dynamic Effect: Unique Gengar character on the home page switches with VPN status
• Smooth Animations: Silky transition animations based on Jetpack Compose
• Adaptive Icons: Support for Android 13+ themed adaptive icons

🚀 High-Performance Core

Based on the Sing-box (libbox) next-generation universal proxy core written in Golang.

• Memory Usage: 30%+ lower than traditional cores
• Startup Speed: Millisecond-level cold start
• Connection Stability: Excellent connection reuse and keepalive mechanisms
• Hot Reload Support: Configuration changes without restarting VPN service

🛡️ Smart Routing & RuleSet Hub

Built-in powerful routing engine supporting complex rule set matching.

• RuleSet Hub: Online download and management of massive rule sets (GeoSite/GeoIP/AdGuard, etc.), supporting both Source and Binary formats.
• Precise App Routing: Uses UID + Package Name dual matching mechanism, effectively solving app routing issues in some system environments.
• Flexible Policies: Supports GeoSite, GeoIP, domain suffix, keyword, process name, and other matching dimensions.
• Auto Update: Rule sets support scheduled automatic updates

⚡ Quick Actions

• Quick Settings Tile: Support system dropdown quick toggle, no need to enter the app to start/stop VPN.
• Desktop Shortcuts: Support node selection and VPN toggle shortcuts
• Real Latency Test: URL-Test based real connection testing, accurately reflecting actual loading speed of YouTube/Google and other target websites.
• Real-time Traffic Monitoring: Notification bar displays real-time upload/download speed

🔄 Background Keepalive & Power Saving

• Smart Keepalive: Multi-level screen-off keepalive mechanism
• Background Power Saving: Configurable auto-sleep in background, balancing battery life and availability
• Quick Recovery: Optimized reconnection speed when returning from background

---

🌐 Protocol Matrix

We've built a comprehensive protocol support network, compatible with most proxy protocols and advanced features on the market.

Core Proxy Protocols

Protocol	Identifier	Link Format	Core Feature Support
Shadowsocks	SS	ss://	SIP002, SIP008, AEAD (AES-128/256-GCM, Chacha20-Poly1305)
VMess	VMess	vmess://	WS, gRPC, HTTP/2, Auto Secure, Packet Encoding
VLESS	VLESS	vless://	Reality, Vision, XTLS Flow, uTLS
Trojan	Trojan	trojan://	Trojan-Go compatible, Mux
Hysteria 2	Hy2	hysteria2://	Latest QUIC protocol, Port Hopping, Congestion Control
TUIC v5	TUIC	tuic://	0-RTT, BBR congestion control, QUIC transport
WireGuard	WG	wireguard://	Kernel-level VPN tunnel, Pre-shared Key (PSK)
SSH	SSH	ssh://	Secure tunnel proxy, Private Key authentication
HTTP(S)	HTTP(S)	http(s)://	HTTP/HTTPS proxy support
SOCKS5	SOCKS5	socks5://	SOCKS5 proxy support
AnyTLS	AnyTLS	anytls://	Universal TLS wrapper, Traffic obfuscation
Naive	Naive	naive+https://	Native sing-box Naive protocol support

Subscription Ecosystem Support

• Sing-box JSON: Native support with full features.
• Clash YAML: Perfect compatibility with Clash / Clash Meta (Mihomo) configurations, automatic policy group conversion.
• Standard Base64: Compatible with V2RayN / Shadowrocket subscription formats.
• Import Methods: Supports clipboard import, URL subscription import, QR code scanning, local file import.

---

🏗️ Project Structure

This project follows best practices of modern Android architecture, adopting MVVM pattern and Clean Architecture design principles.

KunBox-Android/
├── app/src/main/java/com/kunk/singbox/
│   ├── core/              # libbox JNI wrapper (BoxWrapperManager, SingBoxCore)
│   ├── database/          # Room database (dao/, entity/)
│   ├── ipc/               # VPN inter-process communication (SingBoxIpcHub, VpnStateStore)
│   ├── model/             # Data models (SingBoxConfig, RoutingModels, Settings)
│   ├── repository/        # Data repository layer
│   │   ├── config/        # Configuration builders (InboundBuilder, OutboundFixer)
│   │   ├── store/         # Settings storage
│   │   └── subscription/  # Subscription fetcher
│   ├── service/           # Android services
│   │   ├── manager/       # VPN lifecycle management (CoreManager, ConnectManager)
│   │   ├── network/       # Network monitoring
│   │   └── tun/           # TUN device management
│   ├── ui/                # Jetpack Compose UI
│   │   ├── components/    # Reusable components
│   │   ├── screens/       # Screen-level Composables
│   │   └── navigation/    # Navigation configuration
│   ├── utils/parser/      # Protocol parsers (NodeLinkParser, ClashYamlParser)
│   └── viewmodel/         # ViewModel layer
│
├── .kernel-sync-local/    # Local-only sing-box sync workspace and one-click script
│   ├── sync-kernel.ps1    # Re-sync the latest official stable upstream, build and replace libbox.aar
│   └── patches/           # Exact-version minimal KunBox patches
│
└── config/detekt/         # Code quality check configuration

Architecture Highlights

Multi-process Architecture

• VPN service runs in a separate process (:vpn_service)
• UI communicates across processes via SingBoxIpcHub
• Uses VpnStateStore (MMKV) for cross-process state synchronization

VPN Data Flow

SingBoxService -> CoreManager -> BoxWrapperManager -> libbox.aar

---

🛠️ Tech Stack Details

Dimension	Technology	Description
Language	Kotlin 1.9	100% pure Kotlin code, using Coroutines and Flow for async streams
UI Framework	Jetpack Compose	Declarative UI, Material 3 design specification
Architecture	MVVM	Separation of concerns with ViewModel and Repository
Core Engine	Sing-box (Go)	Communicates with Go core library via JNI
Database	Room	Local data persistence
KV Storage	MMKV	High-performance cross-process key-value storage
Network	OkHttp 4	For subscription updates, latency tests, and other network requests
Serialization	Gson & SnakeYAML	High-performance JSON and YAML parsing
Build System	Gradle 8.x	Hybrid build system support
Code Quality	Detekt	Static code analysis and formatting

---

🚀 Build Guide

Environment Requirements

• JDK: 17 or higher
• Android Studio: Hedgehog (2023.1.1) or higher
• Go: 1.24+ (only needed when compiling libbox core)
• NDK: r29 or higher

Clone Project

git clone https://github.com/roseforljh/KunBox.git
cd KunBox

Build Debug APK

# Windows
.\gradlew assembleDebug

# macOS/Linux
./gradlew assembleDebug

Build Release APK

Release builds require signing configuration. Create a signing.properties file:

STORE_FILE=release.keystore
KEYSTORE_PASSWORD=your_keystore_password
KEY_ALIAS=your_key_alias
KEY_PASSWORD=your_key_password

Then execute:

.\gradlew assembleRelease

Sync libbox Core (Local-only)

KunBox uses the local workspace .kernel-sync-local/ for kernel sync. This directory is not committed to git. By default, the script resolves the latest official stable SagerNet/sing-box tag and skips GitHub prerelease entries plus tags with alpha, beta, or rc suffixes.

Each sync shallow-clones the exact official tag into a controlled temporary directory. Patched sources and build artifacts are never reused from an old upstream worktree. The script removes only its own temporary directory when it exits and keeps the newest 3 libbox.aar.backup-before-replace.* files.

Run the one-click script from the repository root:

.\.kernel-sync-local\sync-kernel.ps1

If you need to pin a specific official tag manually, pass it explicitly:

.\.kernel-sync-local\sync-kernel.ps1 -Tag v1.13.14

At the time of writing, the latest official stable release is v1.13.14; the script still trusts the live official release API by default.

The script performs these stages in order:

1. Check Git, Go, Java 17, Android SDK, Android NDK, gomobile, and gobind, then resolve the target official tag
2. Shallow-clone that exact tag into the controlled temporary directory and verify its origin, HEAD tag, and clean state
3. Build the untouched official AAR as the API and ABI baseline
4. Apply only patches/kunbox-<tag>.patch, then run go test, race tests, and go vet for the affected VLESS package
5. Build the patched AAR
6. Compare the official and patched Java class sets, public APIs, and non-empty JNI entry sets; require the public API to match official sing-box exactly and reject the six removed private recovery methods
7. Backup and replace app/libs/libbox.aar
8. Run assembleDebug, testDebugUnitTest, and detekt; restore the backup on failure and keep only the newest 3 backups on success

The script removes only .kernel-sync-local/tmp-sync-kernel-current, so unrelated local kernel worktrees are never deleted.

The script stops when it cannot resolve a stable tag, the exact-version patch is missing, the fresh official tree becomes dirty, or git apply --check, Go tests, AAR method validation, or Gradle validation fails. Fix the reported version coupling and rerun it.

Run Tests

# Run all unit tests
.\gradlew testDebugUnitTest

# Run specific test class
.\gradlew testDebugUnitTest --tests "com.kunk.singbox.utils.parser.NodeLinkParserTest"

# Run specific test method
.\gradlew testDebugUnitTest --tests "com.kunk.singbox.utils.parser.NodeLinkParserTest.testVmessLink"

# Run Detekt code check
.\gradlew detekt

Clean Build

.\gradlew clean

---

📝 URL Scheme Support

KunBox supports quick configuration import via URL Scheme:

kunbox://import?url=<subscription_url>

Example:

kunbox://import?url=https%3A%2F%2Fexample.com%2Fsubscription

---

🧪 Testing

The project includes complete unit test coverage:

Test Class	Description
NodeLinkParserTest	Protocol link parsing tests
ClashConfigParserTest	Clash configuration parsing tests
ConfigRepositoryTest	Configuration generation tests
ModelSerializationTest	Model serialization tests
VpnStateStoreTest	IPC state storage tests

Before running tests, ensure:

1. Android SDK is configured
2. NDK is installed
3. Test database directory is writable

---

🤝 Contributing Guide

We welcome all forms of contributions!

Submit Issues

• Use a clear title to describe the problem
• Provide device model, Android version, app version
• Include reproduction steps and relevant logs

Submit PRs

1. Fork this repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push branch (git push origin feature/amazing-feature)
5. Create a Pull Request

Code Standards

• Use 4-space indentation (no tabs)
• Maximum line length 120 characters
• Class names use PascalCase, functions and variables use camelCase
• Run ./gradlew detekt before committing to ensure code check passes
• No empty catch blocks, use Log.e() instead of printStackTrace()

---

📋 FAQ

Q: Why can't I connect after installation?

A: Please check:

1. Whether VPN permission is granted
2. Whether node configuration is correct
3. Try switching different DNS settings

Q: How to import subscriptions?

A: Multiple methods supported:

1. Click "+" in the top right corner and select "Import from Clipboard"
2. Long press subscription link and select "Open with KunBox"
3. Use URL Scheme: kunbox://import?url=<url>

Q: What to do about high battery usage?

A: Suggestions:

1. Enable "Background Power Saving" feature
2. Reduce unnecessary rule sets
3. Turn off unused features (like detailed logs)

Q: Which Android versions are supported?

A: Minimum support is Android 7.0 (API 24), Android 10+ recommended for best experience.

❤️ Acknowledgments

This project stands on the shoulders of giants, special thanks to the following open source projects:

• SagerNet/sing-box: Next-generation universal proxy platform core
• MatsuriDayo/NekoBoxForAndroid: Excellent Android proxy client reference
• v2ray/v2ray-core: V2Ray team's pioneering contribution to the proxy ecosystem
• Jetpack Compose: Modern Android UI toolkit

---

📝 License

Copyright © 2024-2025 KunK.

Licensed under the MIT License.
You may obtain a copy of the License at

    https://opensource.org/licenses/MIT

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

---

⬆ Back to Top

_{This project is for learning and researching network technology only. Please comply with local laws and regulations.}