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

中文文档

📱 Visual Preview

📥 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

Direct Install: Download APK and tap to install (requires permission to install from unknown sources)
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
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
│
├── Kkunbox/               # Sing-box core source and build scripts
│   └── buildScript/       # libbox compilation scripts
│
└── 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

Compile libbox Core (Optional)

If you need to modify the underlying core code, compile libbox:

# Compile from local source (requires Go 1.24+)
.\Kkunbox\buildScript\tasks\build_libbox.ps1 -UseLocalSource

# Compile from remote repository
.\Kkunbox\buildScript\tasks\build_libbox.ps1

After compilation, libbox.aar will be automatically placed in the app/libs/ directory.

Sync Upstream Kernel

KunBox uses a fixed branch kunbox-extensions to manage kernel extensions. This branch is based on an official sing-box tag, with KunBox extension commits stacked on top.

To sync to a new upstream version:

cd Kkunbox\singbox-core

# 1. Fetch latest upstream tags
git fetch upstream --tags

# 2. Rebase onto the new version tag (e.g. v1.13.0)
git rebase v1.13.0

# 3. Go back to project root and rebuild the kernel
cd ..\..
.\Kkunbox\buildScript\tasks\build_libbox.ps1 -UseLocalSource -AutoReplace

Note: KunBox extension commits are automatically preserved on top of the branch during rebase. If conflicts occur, resolve them manually and run git rebase --continue.

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:

Android SDK is configured
NDK is installed
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

Fork this repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push branch (git push origin feature/amazing-feature)
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:

Whether VPN permission is granted
Whether node configuration is correct
Try switching different DNS settings

Q: How to import subscriptions?

A: Multiple methods supported:

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

Q: What to do about high battery usage?

A: Suggestions:

Enable "Background Power Saving" feature
Reduce unnecessary rule sets
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.

💖 Sponsorship

Thanks to the following users for their generous support:

Sponsor	Amount
@WestWood	¥30

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

❤️ 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.}

Name		Name	Last commit message	Last commit date
Latest commit History 632 Commits
.agent/skills/debug		.agent/skills/debug
.github/workflows		.github/workflows
app		app
config/detekt		config/detekt
gradle/wrapper		gradle/wrapper
.gitattributes		.gitattributes
.gitignore		.gitignore
.release-please-manifest.json		.release-please-manifest.json
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
README_CN.md		README_CN.md
build.gradle.kts		build.gradle.kts
gradle.properties		gradle.properties
gradlew		gradlew
gradlew.bat		gradlew.bat
release-please-config.json		release-please-config.json
settings.gradle.kts		settings.gradle.kts

Folders and files

Latest commit

History

Repository files navigation

KunBox for Android

📱 Visual Preview

📥 Download and Installation

Download from GitHub Releases

System Requirements

Installation Methods

✨ Core Features

🎨 OLED Pure Black Aesthetics (Hyper-Minimalist UI)

🚀 High-Performance Core

🛡️ Smart Routing & RuleSet Hub

⚡ Quick Actions

🔄 Background Keepalive & Power Saving

🌐 Protocol Matrix

Core Proxy Protocols

Subscription Ecosystem Support

🏗️ Project Structure

Architecture Highlights

Multi-process Architecture

VPN Data Flow

🛠️ Tech Stack Details

🚀 Build Guide

Environment Requirements

Clone Project

Build Debug APK

Build Release APK

Compile libbox Core (Optional)

Sync Upstream Kernel

Run Tests

Clean Build

📝 URL Scheme Support

🧪 Testing

🤝 Contributing Guide

Submit Issues

Submit PRs

Code Standards

📋 FAQ

Q: Why can't I connect after installation?

Q: How to import subscriptions?

Q: What to do about high battery usage?

Q: Which Android versions are supported?

💖 Sponsorship

❤️ Acknowledgments

📝 License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 67

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages