fleet/android

Fleet Android agent

• Requirements
• Building the project
• Deploying via Android MDM
• How the app starts
• Running tests
• Code quality
• Troubleshooting

Requirements

• JDK 17 or later - Set JAVA_HOME environment variable
• Android SDK - Gradle finds it via:
  • local.properties file with sdk.dir (auto-created by Android Studio) ✅ Recommended
  • OR ANDROID_HOME / ANDROID_SDK_ROOT environment variables
  • Install via Android Studio (easiest)
  • Or install command-line tools
  • Requires SDK Platform API 33+ and Build Tools 34.0.0+

Building the project

Debug build

./gradlew assembleDebug

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

Release build

./gradlew assembleRelease

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

Note: By default (without signing configuration), this creates an unsigned APK not suitable for distribution.

Signing release builds

Signing configuration is already set up in build.gradle.kts. You just need to provide the keystore and credentials.

One-time setup per developer/machine:

1. Create a keystore:

keytool -genkeypair \
  -alias fleet-android \
  -keyalg RSA \
  -keysize 4096 \
  -validity 10000 \
  -keystore keystore.jks \
  -storepass YOUR_PASSWORD \
  -dname "CN=Your Name, O=Your Org, L=City, ST=State, C=US"

2. Create keystore.properties file in the android/ directory:

storeFile=/path/to/keystore.jks
storePassword=YOUR_PASSWORD
keyAlias=fleet-android
keyPassword=YOUR_PASSWORD

3. Build signed release:

# APK (for direct distribution)
./gradlew assembleRelease

# AAB (for Google Play Store)
./gradlew bundleRelease

Output:

• APK: app/build/outputs/apk/release/app-release.apk
• AAB: app/build/outputs/bundle/release/app-release.aab

Verify signing:

# APK - use apksigner (in SDK build-tools)
# Find your SDK and build-tools version:
grep sdk.dir local.properties
ls "$(grep sdk.dir local.properties | cut -d= -f2)/build-tools/"
# Then verify:
<sdk-path>/build-tools/<version>/apksigner verify --verbose app/build/outputs/apk/release/app-release.apk

# AAB - use jarsigner (included with JDK)
jarsigner -verify app/build/outputs/bundle/release/app-release.aab

Getting the SHA256 fingerprint

The SHA256 fingerprint is required for MDM deployment. You can get it from your keystore.

keytool -list -v -keystore keystore.jks -alias fleet-android
# Grab SHA256 (remove colons and convert to base64)
echo <SHA256> | tr -d ':' | xxd -r -p | base64

Copy the fingerprint for use in the mdm.android_agent.signing_sha256 config option.

Deploying via Android MDM (development)

For development, each developer publishes a private build of the agent under a unique package name (e.g. com.fleetdm.agent.private.<yourname>) via the Google Play Console and distributes it to the target Fleet Android enterprise by Organization ID.

Who owns the app: Ask a Fleet admin to create the Play Console app com.fleetdm.agent.private.<yourname> and grant you the Admin role on it. That gives you upload + release access without needing your own paid developer account.

1. Configure Fleet with your agent package and signing fingerprint:

   Environment variables:

   export FLEET_MDM_ANDROID_AGENT_PACKAGE=com.fleetdm.agent.private.<yourname>
   export FLEET_MDM_ANDROID_AGENT_SIGNING_SHA256=<SHA256 fingerprint>
   

   Or in your Fleet config file:

   mdm:
     android_agent:
       package: com.fleetdm.agent.private.<yourname>
       signing_sha256: <SHA256 fingerprint>
   

   Use the SHA-256 of your upload keystore (see "Getting the SHA256 fingerprint" above for the keytool + base64 conversion).

2. Set applicationId in app/build.gradle.kts:

   defaultConfig {
       applicationId = "com.fleetdm.agent.private.<yourname>"
       // ...
   }
   

3. Build a signed release (AAB) using the instructions above.

4. Find the Organization ID for your target Fleet Android enterprise:

   This is the same as the Android Enterprise ID that Fleet uses for AMAPI calls (format like LCxxxxxxxx). You can find it in the Fleet UI under MDM Android settings, or in the enterprise_id column of the android_enterprises table in Fleet's DB.

5. Upload the AAB in Play Console:

   • Open https://play.google.com/console and pick the developer account that owns com.fleetdm.agent.private.<yourname> (the one the Fleet admin granted you Admin on).
   • Go to the app → Test and release → pick a track (Internal/Closed/Production) → create a release → upload your AAB → save and review.

6. Distribute to your Fleet enterprise:

   • In the same app, go to Test and release → Advanced settings → Managed Google Play.
   • Add the Organization ID you copied in step 4 to the list of organizations allowed to install the app.
   • Save.

7. Roll out the release (publish it on the chosen track). Wait ~10 minutes for Play to propagate.

8. Enroll your Android device in Fleet. The agent should appear in your Work profile shortly after. If it's stuck pending, restart the device or check the device's nonComplianceDetails via tools/android/android.go -command devices.list ....

Re-using an existing private app

If your Play Console app already exists and you only need to grant access to a new Fleet enterprise, repeat steps 4 and 6 for the new Organization ID. No new upload is required.

How the app starts

The Fleet Android agent is designed to run automatically without user interaction. The app starts in three scenarios:

1. On installation (COMPANION_APP role)

When the app is installed via MDM, Android Device Policy assigns it the COMPANION_APP role. This triggers RoleNotificationReceiverService, which starts the app process and runs AgentApplication.onCreate().

2. On device boot

When the device boots, BootReceiver receives the ACTION_BOOT_COMPLETED broadcast and starts the app process, triggering AgentApplication.onCreate().

3. Periodically every 15 minutes

AgentApplication.onCreate() schedules a ConfigCheckWorker to run every 15 minutes using WorkManager. This ensures the app wakes up periodically even if the process is killed.

Note: WorkManager ensures reliable background execution. The work persists across device reboots and process death.

Why not ACTION_APPLICATION_RESTRICTIONS_CHANGED?

We don't use ACTION_APPLICATION_RESTRICTIONS_CHANGED to detect MDM config changes because:

1. This broadcast can only be registered dynamically (not in the manifest)
2. On Android 14+, context-registered broadcasts are queued when the app is in cached state

This means the broadcast won't wake the app immediately when configs change if the app is in the background. WorkManager polling every 15 minutes is the reliable solution for detecting config changes.

Full build with tests

./gradlew build

This runs:

• Compilation (debug + release)
• Unit tests
• Android Lint
• Spotless formatting checks (automatic)

Running tests

Unit tests (JVM)

./gradlew test

Integration tests (with real SCEP server)

Integration tests are skipped by default. To run them:

./gradlew test -PrunIntegrationTests=true \
  -Pscep.url=https://your-scep-server.com/scep \
  -Pscep.challenge=your-challenge-password

Setting Up a Test SCEP Server

Integration tests require a real SCEP server. Options:

1. Production-grade SCEP servers:

   • Microsoft NDES (Network Device Enrollment Service)
   • OpenXPKI
   • Ejbca

2. Lightweight test servers:

   • micromdm/scep (Docker)
   • jscep test server

Docker SCEP Server (Easiest)

docker run -p 8080:8080 \
  -e SCEP_CHALLENGE=test-challenge-123 \
  micromdm/scep:latest

Running Integration Tests

./gradlew test -PrunIntegrationTests=true \
  -Pscep.url=http://localhost:8080/scep \
  -Pscep.challenge=test-challenge-123

Instrumented tests (requires emulator/device)

./gradlew connectedDebugAndroidTest

Code quality

Formatting with Spotless (ktlint)

Check formatting:

./gradlew spotlessCheck

Auto-fix formatting issues:

./gradlew spotlessApply

Note: Spotless checks run automatically during ./gradlew build. Run spotlessApply to fix issues before committing.

Static analysis with Detekt

Run manually:

./gradlew detekt

Note: Detekt does NOT run automatically in local builds (only in CI). Run manually when needed.

Dependencies

See gradle/libs.versions.toml for complete list.

Development workflow

1. Before committing: Run ./gradlew spotlessApply to fix formatting
2. Local verification: Run ./gradlew build to ensure everything passes
3. Optional: Run ./gradlew detekt for static analysis
4. Push: CI will run all checks automatically

Troubleshooting

Clean build:

./gradlew clean build

Delete device from Android MDM:

• Delete Work profile on Android device
• Using tools/android/android.go, delete the device and delete the associated policy (as of 2025/11/21, Fleet server does not do this)