Nexus-Guard-Suite/.tests/android-build.md

Android Agent Build & Deploy

Prerequisites

• Android SDK installed (compileSdk 34, minSdk 26)
• Device connected via USB with USB debugging enabled
• adb devices shows device

Device

9b2adc22        device

Build Commands

Build Debug APK

cd D:\www-project\NexusGuard\apps\android-agent
.\gradlew assembleDebug

Output: app/build/outputs/apk/debug/app-debug.apk

Install on Device

adb install -r app\build\outputs\apk\debug\app-debug.apk

Launch App

adb shell am start -n com.datadunia.nexusguard/.MainActivity

View Logs

adb logcat -s AgentService GrpcClient Heartbeat TunnelManager Provisioning LogBuffer

Check Device Connection

adb devices

One-Shot Build + Install + Launch

cd D:\www-project\NexusGuard\apps\android-agent
.\gradlew assembleDebug && adb install -r app\build\outputs\apk\debug\app-debug.apk && adb shell am start -n com.datadunia.nexusguard/.MainActivity

Architecture (matches device-agent)

• gRPC signaling: GrpcClient.kt — bidirectional streaming with fallback (HTTPS domain → WG IP → plaintext)
• HTTP heartbeat: Heartbeat.kt — POST /api/v1/heartbeat every 30s (fallback when gRPC down)
• Background service: AgentService.kt — foreground service with notification (START_STICKY)
• Tunnel: TunnelManager.kt — WireGuard via VPNService + GoBackend
• HWID: SHA-256(ANDROID_ID + manufacturer + model + device), persisted in EncryptedSharedPreferences
• Provisioning: Provisioning.kt — HTTP POST /api/v1/provisioning
• Auto-start: BootReceiver.kt — starts agent on device boot

Commands (Agent)

• gRPC: HelloMessage → ConfigUpdate (full tunnel config + port forwards)
• gRPC: HeartbeatRequest every 30s → HeartbeatResponse (config_hash + forwards_changed)
• gRPC: Suspend/Resume/Reconnect/Disconnect from server
• HTTP heartbeat: fallback when gRPC disconnected

.gitignore (Android artifacts)

*.aar
*.apk
*.aab
android-agent/app/build/
android-agent/build/
android-agent/.gradle/
android-agent/local.properties

Commit Workflow

# 1. Build
cd D:\www-project\NexusGuard\apps\android-agent
.\gradlew assembleDebug

# 2. Install + test
adb install -r app\build\outputs\apk\debug\app-debug.apk
adb shell am start -n com.datadunia.nexusguard/.MainActivity

# 3. Commit submodule
cd D:\www-project\NexusGuard\apps\android-agent
git add -A
git commit -m "feat: message"
git push origin main

# 4. Commit parent repo
cd D:\www-project\NexusGuard
git add apps/android-agent
git commit -m "chore: update android-agent submodule"
git push origin main