License: MIT Build Status Android Build iOS Build React Native Expo TypeScript Platform PRs Welcome

English documentation — Vietnamese version available at README.vi.md.

CB Pro Proxy is an Expo-managed React Native application that provisions a local VPN interface and forwards traffic through SOCKS5 or HTTP proxies. The Android implementation ships with a fully native VpnService pipeline while the iOS Network Extension layer is under active development.

CB Pro Proxy revolutionizes proxy management on mobile devices by enabling seamless remote control through Android Debug Bridge (ADB). Tailored for developers, QA engineers, and automation specialists, this app allows you to create, start, and stop proxy profiles directly from your command line or scripts, making it perfect for device farming, automated testing, and CI/CD pipelines.

• Automation-First Design: Integrate proxy switching into your test suites and deployment scripts without touching the device.
• Device Farm Ready: Manage proxies across multiple Android devices simultaneously via ADB broadcasts.
• No Manual Intervention: Start VPN tunnels, add profiles, and monitor status remotely – ideal for headless environments.
• Secure & Efficient: Credentials are stored securely, and connections are handled natively for optimal performance.

Whether you're running Selenium tests, Appium scripts, or custom automation workflows, CB Pro Proxy bridges the gap between your development tools and mobile proxy needs.

Main Screen Settings Screen

• Multi-profile proxy manager — Create, update, and delete SOCKS5 or HTTP proxy profiles.
• Native VPN tunnel — Android foreground service with status bar notification and connection telemetry.
• Credential security — Metadata in AsyncStorage, secrets in SecureStore (Keychain on iOS).
• Remote automation — Full control via adb broadcast intents; designed for STF/device-farm workflows.
• React Native UI — Zustand-powered state management, modern screens, realtime connection stats.

• High-Performance SQLite Storage 🚀

  • 15-40x faster bulk operations compared to AsyncStorage
  • Efficient database queries with indexing
  • Automatic migration from AsyncStorage
  • Transaction-based operations for data integrity
  • Handles thousands of profiles effortlessly
  • Secure credential storage (passwords in SecureStore)
  • User Guide → | Testing Guide →

• Comprehensive Logging System 🔍

  • Multi-level logging (debug, info, warn, error, critical)
  • Real-time log viewer with filtering and search
  • 30-day retention with automatic rotation
  • Export logs for debugging and support
  • Categorized logging (VPN, network, storage, UI, app)
  • Learn more →

• Dark Mode 🌙

  • Full theme system with light and dark modes
  • System theme detection (follows device settings)
  • WCAG AA compliant color contrast
  • AMOLED-optimized (true black backgrounds)
  • Smooth theme switching across all screens
  • Learn more →

• Node.js 18+
• npm or Yarn Classic (Yarn Berry ≥2 requires yarn add -D metro-minify-terser)
• Expo CLI (npx expo)
• Android Studio (emulator, SDK platforms)
• Xcode (for upcoming iOS Network Extension work)

# Clone & install
git clone <repository-url>
cd cbv-vpn-app
npm install
# Start Expo dev server
npm start
# Launch on Android (development build required)
npm run android
# Launch on iOS simulator (development build required)
npm run ios

Tip: Use npx expo run:android / npx expo run:ios to generate native projects on demand.

cbv-vpn-app/
├── src/
│ ├── components/ # Shared UI components (alerts, notifications, loaders, ...)
│ ├── screens/ # React Navigation screens (profiles, settings, logs)
│ ├── navigation/ # AppNavigator & stack/tab config
│ ├── services/ # Business logic (StorageService, CryptoService, ErrorHandler)
│ ├── store/ # Zustand store (`vpnStore.ts`)
│ ├── hooks/ # Hooks (`useVPNEvents`)
│ ├── native/ # JS bridge to native module (`VPNModule.ts`)
│ └── types/ # Shared TypeScript definitions
├── android/ # Native Android module & VpnService implementation
├── ios/ # Placeholder for Network Extension (coming soon)
├── assets/ # Icons & splash artwork
└── app.json / package.json # Expo & dependency configuration

Android exposes a broadcast receiver (VPNIntentReceiver.kt) with explicit intent actions:

• com.cbv.vpn.ADD_PROFILE
• com.cbv.vpn.ADD_AND_START
• com.cbv.vpn.START_VPN_BY_NAME
• com.cbv.vpn.START_VPN_BY_ID
• com.cbv.vpn.STOP_VPN
• com.cbv.vpn.GET_STATUS

Example intent sequence:

# Add or update a profile
adb shell am broadcast -n com.cbv.vpn/.VPNIntentReceiver \
 -a com.cbv.vpn.ADD_PROFILE \
 --es profile_name "My Proxy" \
 --es profile_host "203.0.113.10" \
 --ei profile_port 1080 \
 --es profile_type "socks5" \
 --es profile_username "user" \
 --es profile_password "secret"
# Start VPN by name (auto-stops previous session)
adb shell am broadcast -n com.cbv.vpn/.VPNIntentReceiver \
 -a com.cbv.vpn.START_VPN_BY_NAME \
 --es profile_name "My Proxy"
# Stop VPN
adb shell am broadcast -n com.cbv.vpn/.VPNIntentReceiver \
 -a com.cbv.vpn.STOP_VPN

See ADB_INTENT_COMMANDS.md for the full catalogue, automation tips, and troubleshooting notes.

npx expo prebuild --platform android
cd android
./gradlew assembleRelease # Generate APK
./gradlew bundleRelease # Generate AAB for Play Store

npx expo prebuild --platform ios
cd ios
open CBVVPN.xcworkspace # Configure Network Extension in Xcode

• React Native layer — UI, profile management workflow, Zustand store, event-driven updates through useVPNEvents.
• Storage & security — Profile metadata synced via StorageService, credentials isolated in secure storage.
• Native Android — VPNConnectionService (derives from VpnService), packet routing, proxy clients, explicit broadcast receiver for automation, foreground notification for compliance.
• Native iOS — Network Extension packet tunnel provider under construction; shares JS bridge contracts for parity.

• Android: production-ready (VpnService, SOCKS5/HTTP tunnelling, broadcast automation, telemetry).
• iOS: Network Extension + go-tun2socks integration scheduled.
• Roadmap: enhanced error analytics, multi-proxy rotation, UI polish.

Track ongoing work in tasks.md inside .kiro/specs/ (private project planning).

Comprehensive documentation is available for all features:

• Quick Start Guide - Get up and running quickly
  • Installation steps
  • First launch guide
  • Feature overview
  • Troubleshooting

• Implementation Guide - Technical documentation

  • Logging System API
  • Dark Mode API
  • Code examples
  • Best practices

• Feature Design Document - Architecture & design

  • System architecture
  • Data flow diagrams
  • Storage strategies
  • Performance considerations

• SQLite User Guide - High-performance storage

  • Feature overview and benefits
  • How to enable SQLite storage
  • Migration process explained
  • Performance expectations (15-40x faster)
  • Troubleshooting and FAQ

• SQLite Testing Guide - Testing procedures

  • Comprehensive test scenarios
  • Performance benchmarking
  • Migration testing
  • Data integrity verification

• Testing Guide - Comprehensive test scenarios
  • Manual testing checklists
  • Feature validation
  • Performance testing
  • Known issues

• ADB Intent Commands - Remote automation guide
• Contributing Guide - How to contribute

• VPN permission dialog — Android prompts the first time VpnService.prepare() returns an intent; automation flow opens the app if approval is pending.
• Expo Go limitation — Requires development client or production build due to custom native modules.
• No traffic after connect — Verify upstream proxy availability and credentials; inspect logcat with adb logcat | grep VPN.
• Build issues — Refer to TROUBLESHOOTING.md for common Gradle/Xcode remedies.

MIT