OpenPalm

OpenPalm is an ambient, Android-native personal agent Gateway. The north star is Jarvis for Android: always locally aware, deeply personal, able to operate the phone like a human, and governed by explicit user authority.

OpenPalm is not a chatbot app and not an Android companion node for a server agent. The phone is the Gateway, memory home, policy authority, permission boundary, and action environment. Remote frontier models can provide reasoning, perception help, and verification, but they do not directly own tools, memory, or execution.

OpenPalm's control architecture is split across Android layers. The OpenPalm Gateway remains an updatable app or privileged app for the agent runtime, user controls, memory, policy, approvals, skills, and model routing. A smaller OpenPalm Platform Service lives at the Android application-framework boundary as a typed Binder/AIDL action broker for privileged observation and semantic phone actions. The full agent brain must not live inside system_server.

Status

This repository has the native Android Gateway foundation plus the first platform-control scaffold:

• Pure Kotlin runtime, model, memory, policy, provider, and skill contracts.
• Local capability-token authority with active-token validation, revocation, risk, budget, approval, and recipient/provider checks.
• Semantic PhoneAction and PhoneState contracts, ModelProposalValidator, PlatformCapabilityProvider, and production Android Binder client wiring for the OpenPalm Platform Service.
• Command-center agent runner with OpenAI-compatible BYOK HTTP transport: user commands become model proposals, then local validation, scoped token issuance, provider execution, verification, and audit.
• Gateway diagnostics for install mode, privileged permissions, platform-service registration, action-mode readiness, and kill-switch state.
• Canonical AIDL contracts under platform/aidl.
• Patch-ready AOSP service, manager, permission XML, product packaging, SELinux stubs, and platform action Cuttlefish smoke gate under platform/aosp.

Real Android Accessibility control execution is wired for stock/degraded installs. On an OpenPalm privileged image, the Gateway observes UI targets through the local Accessibility control service and executes typed actions through the AOSP Platform Service executor. Platform signing and AOSP/Cuttlefish integration still require the target build environment and hardware.

Start Here

• Vision
• Architecture
• Platform Control Stack
• Bootloader-Unlocked Device Install
• Device Compatibility Matrix
• Device Demo Completion Audit
• Glossary
• Capability Matrix
• Model Provider Contract
• Ambient Runtime Policy
• Prompt Injection Rules
• Skill And Plugin Trust
• Security Threat Model
• Data Lifecycle
• Kill Switch
• Testing Strategy
• CI/CD Policy
• Roadmap
• ADRs
• Contributing
• Security

Core Rule

OpenPalm is ambient, but all authority is explicit, scoped, revocable, and auditable.

Development

The project uses the Gradle wrapper:

./gradlew test
./gradlew spotlessCheck detekt
./gradlew assembleNormalDebug
./gradlew assemblePrivilegedDebug
bash scripts/openpalm-host-readiness.sh --full

Local Android builds require an Android SDK with API 36 installed. CI installs the SDK packages on GitHub Actions.

Install On An Android Phone

The normalDebug APK is the sideloadable build for stock Android phones running Android 8.0 or newer. It runs in degraded normal-app mode; privileged/system capabilities still require the AOSP integration path in platform/aosp.

Enable Developer options and USB debugging on the phone, authorize the computer from the phone prompt, then run:

bash scripts/install-normal-debug.sh

The script builds :app:assembleNormalDebug and installs:

app/build/outputs/apk/normal/debug/app-normal-debug.apk

If more than one Android device is attached, set ANDROID_SERIAL to the target device serial before running the script.

For a fully manual install:

./gradlew :app:assembleNormalDebug
adb install -r app/build/outputs/apk/normal/debug/app-normal-debug.apk

Install On A Bootloader-Unlocked Test Device

The full-control OpenPalm path targets dedicated bootloader-unlocked Android test devices. Start the desktop installer from a workstation with Android platform tools available:

bash scripts/openpalm-installer.sh

The installer probes ADB/Fastboot state, requires a booted authorized ADB preflight before full-image flashing, checks the GSI compatibility floor, verifies full image bundle manifests and checksums.sha256, requires full image bundles to include apks/OpenPalm.apk for the no-fake-runtime artifact audit, supports full image bundles with flash-openpalm.sh or flash-all.sh, updates existing OpenPalm userdebug images through adb remount, builds and installs the bundled third-party demo APK, launches OpenPalm with bundled demo targets prefilled, and can run the bundled demo setup plus Gateway diagnostics as one guided flow. Bundle validation and update/flash commands run the production artifact audit against the selected privileged APK before any device probe, remount, push, or flash work. Use scripts/openpalm-aosp-integration.sh to sync OpenPalm into a real AOSP/Cuttlefish checkout, use scripts/openpalm-aosp-build-bundle.sh to build and package an OpenPalm AOSP image bundle, use scripts/openpalm-cuttlefish-smoke.sh --launch --product-out <dir> to launch and smoke-test a built Cuttlefish product output before physical hardware, and use scripts/package-openpalm-image-bundle.sh to assemble an installer-selectable bundle from an externally built AOSP/GSI output directory plus a reviewed device-specific flash script. The installed desktop command also supports --validate-image-bundle <dir>, --host-readiness --log-file <log>, --production-artifact-audit [--apk <apk>], --demo-readiness-report --host-readiness-log <log> --device-evidence-dir <dir>, --unlock-bootloader --serial <serial> --confirm-wipe-risk, --cuttlefish-demo-evidence ..., --update-image-and-verify --serial <serial> --evidence-dir <dir> --confirm-system-change, --update-image-and-run-demo-evidence ..., --flash-image-bundle-and-verify --serial <serial> --image-bundle <dir> --evidence-dir <dir> --confirm-wipe-risk, --flash-image-bundle-and-run-demo-evidence ..., --device-demo-evidence ..., and --production-readiness-audit --host-readiness-log <log> --device-evidence-dir <dir> for headless installation, validation, and evidence capture before and after device smoke.

Before connecting a device, run bash scripts/openpalm-host-readiness.sh --full --log-file build/openpalm-host-readiness.log to verify platform tools, static AOSP gates, unit tests, privileged APK build, normal and privileged app lint, bundled demo APK build, desktop installer distribution, the no-device image-bundle fixture packaging path, the no-device ADB smoke-script fixture, the AOSP integration fixture, the AOSP build-bundle fixture, the Cuttlefish smoke fixture, and the production readiness audit fixture.

Use the installed desktop command's --workstation-readiness [--product-out <dir>] when you need a quick local report for platform tools, local Cuttlefish/KVM blockers, product images, and connected targets. Use --demo-readiness-report --host-readiness-log <log> --device-evidence-dir <dir> [--serial <serial>] [--normal-apk-evidence-dir <dir>] to review what is currently proven, including no-fake-runtime artifact status and dev-only normal APK evidence, while still returning incomplete unless the strict production audit passes; when --image-bundle is provided, the artifact status is for that bundle's apks/OpenPalm.apk. A normal OpenPalm app launch does not hardcode a target app or command; bundled and real-app demo targets are used only when the installer or smoke script explicitly passes them. Use --prepare-control-target --serial <serial> --target-package <package> --agent-command <command> to optionally install a real third-party APK file, split-APK directory, or split APK archive passed by --target-apk, require the package to be user-installed and launcher-available, require a concrete agent command, require healthy OpenPalm diagnostics, and pass app hints before launching OpenPalm against a real app such as Yelp. For the real external-agent path, run desktop-installer --external-agent-smoke --serial <serial> --target-package com.yelp.android --display-name Yelp --agent-command "Make a restaurant reservation in Yelp for Coast Table at 7 PM for 2 guests, then add it to my calendar." --evidence-dir build/openpalm-device-evidence or scripts/openpalm-external-agent-smoke.sh --device --target-package com.yelp.android --display-name Yelp --agent-command "Make a restaurant reservation in Yelp for Coast Table at 7 PM for 2 guests, then add it to my calendar." --evidence-dir build/openpalm-device-evidence; add --target-apk /path/to/yelp.apk, --target-apk /path/to/yelp-splits/, or --target-apk /path/to/yelp.apks when the real target app should be sideloaded first, and add --run-agent --expect-final-text "Coast Table" only on a dedicated unlocked smoke device when you intentionally want OpenPalm to start driving the real app and verify the expected final text inside an accepted OpenPalm confirm step after any required approvals. For multi-app commitment demos, repeat --expect-submit-package <package> to require consumed submit approvals for additional generic app UI packages such as an installed calendar app. The external target must be a user-installed, non-OpenPalm third-party package listed by pm list packages -3, with package identity evidence recorded from pm path and dumpsys package. Add --enable-accessibility only when that dedicated device should let the smoke lane enable OpenPalm Accessibility control, and add --auto-approve-demo-approvals only when the smoke script should tap real visible OpenPalm approval buttons on that device. For one-command evidence on a connected unlocked device, use the desktop GUI's Run device demo evidence button or run desktop-installer --device-demo-evidence --serial <serial> --host-readiness-log build/openpalm-host-readiness.log --evidence-dir build/openpalm-device-evidence --target-package com.yelp.android --display-name Yelp --agent-command "Make a restaurant reservation in Yelp for Coast Table at 7 PM for 2 guests, then add it to my calendar." --run-agent --expect-final-text "Coast Table". To install or flash and then run that same real generic app-control evidence lane only after verification passes, use the GUI's Update image and run demo evidence or Flash image and run demo evidence buttons, desktop-installer --update-image-and-run-demo-evidence ... --confirm-system-change for an existing OpenPalm userdebug image, or desktop-installer --flash-image-bundle-and-run-demo-evidence ... --confirm-wipe-risk for a full image bundle. The terminal equivalent is scripts/openpalm-device-demo-evidence.sh --device --serial <serial> --host-readiness-log build/openpalm-host-readiness.log --evidence-dir build/openpalm-device-evidence --target-package com.yelp.android --display-name Yelp --agent-command "Make a restaurant reservation in Yelp for Coast Table at 7 PM for 2 guests, then add it to my calendar." --run-agent --expect-final-text "Coast Table". After a real Cuttlefish or unlocked-device smoke run, use scripts/openpalm-post-install-verify.sh --device --evidence-dir <dir> or scripts/openpalm-cuttlefish-smoke.sh --device --evidence-dir <dir> to write production evidence, then run scripts/openpalm-production-readiness-audit.sh --run --host-readiness-log <log> --device-evidence-dir <dir> to prove both host readiness and real device evidence are present. The audit intentionally fails if only host fixtures have run.

For Cuttlefish as the production-demo rehearsal before physical hardware, run desktop-installer --cuttlefish-demo-evidence --product-out <dir> --host-readiness-log build/openpalm-host-readiness.log --evidence-dir build/openpalm-device-evidence --target-package com.yelp.android --agent-command "Make a restaurant reservation in Yelp for Coast Table at 7 PM for 2 guests, then add it to my calendar." --run-agent --expect-final-text "Coast Table" or the equivalent scripts/openpalm-cuttlefish-smoke.sh --launch --product-out <dir> --evidence-dir build/openpalm-device-evidence --demo-evidence --host-readiness-log build/openpalm-host-readiness.log --target-package com.yelp.android --display-name Yelp --agent-command "Make a restaurant reservation in Yelp for Coast Table at 7 PM for 2 guests, then add it to my calendar." --run-agent --expect-final-text "Coast Table" on a Linux CVD host with launch_cvd, stop_cvd, and KVM. That wrapper still hands off to the real device-demo evidence lane, so it requires a user-installed third-party target app, consumed approvals, and final text verified by an accepted OpenPalm confirm step before the final audit can pass.

See Bootloader-Unlocked Device Install and Device Compatibility Matrix.