Skip to content

Install

TouchPilot ships as a signed Android APK. The 1.0 release is published on the GitHub Releases page. Until Google Play distribution is set up, you install it by sideloading.

Requirements

  • An Android device or emulator running Android 8.0 (API 26) or newer.
  • About 80 MB of free storage.
  • Permission to install apps from unknown sources (you will be prompted).
  • The Accessibility service enabled for TouchPilot (you will be prompted).

Download

  1. Open the latest release: https://github.com/touchpilot/touchpilot/releases/latest.
  2. Under Assets, download app-release.apk (the file name may vary; pick the largest .apk).
  3. Verify the file size matches the value shown on the release page. If you want to be paranoid, also check the SHA-256 against the .sha256 file attached to the release.

Sideload on a physical device

  1. Connect the phone to your computer with a USB cable.
  2. Copy app-release.apk to the phone's Download/ folder.
  3. On the phone, open the Files app and tap the APK.
  4. When prompted, allow your file manager to install unknown apps.
  5. Tap Install, then Open.
  1. On the phone, open the GitHub release link in your browser.
  2. Download app-release.apk.
  3. Pull down the notification shade and tap the downloaded file.
  4. Allow your browser to install unknown apps if prompted.
  5. Tap Install, then Open.
  1. Start your emulator (Android Studio AVD, LDPlayer, BlueStacks, etc.).

  2. Drag app-release.apk onto the emulator window, or run:

    bash adb install -r app-release.apk

  3. Launch TouchPilot from the app drawer.

First-run setup

The first time you open TouchPilot, you will be asked to:

  1. Grant Accessibility access. This is how the agent reads the screen and performs taps. TouchPilot only requests the permissions it needs to operate its own UI and the apps you point it at. See Safety for the full permissions model.
  2. Allow notifications (optional but recommended). The agent posts a persistent notification while it is running so you always know it is active.

That is it. There is no account, no signup, and no telemetry by default.

Build from source

If you prefer to build the APK yourself:

```bash git clone https://github.com/touchpilot/touchpilot.git cd touchpilot ./gradlew assembleDebug # debug APK, signed with the local debug key

or

./gradlew assembleRelease # release APK ```

Outputs:

  • app/build/outputs/apk/debug/app-debug.apk
  • app/build/outputs/apk/release/app-release.apk

Release signing

Until a real release signing key is configured, the assembleRelease task falls back to the Android debug key so the APK is installable on emulators and personal devices. See CONTRIBUTING.md for how to set up a proper release key.

You will also need an Android SDK with platform-tools, android-35, and build-tools;35.0.0. Either set ANDROID_HOME or write sdk.dir=/path/to/Sdk into local.properties.

Updating

To update an existing install, download the newer APK and install it over the current version. Your settings, logs, and skills are preserved.

To uninstall, long-press the app icon and choose Uninstall. Local logs live inside the app's private storage and are removed automatically.

Troubleshooting

Install blocked: 'For your security, your phone is not allowed to install unknown apps from this source'

Open Settings → Apps → Special app access → Install unknown apps, find the app you used to download the APK (browser or file manager), and toggle Allow.

Accessibility service keeps disabling itself

Some OEM ROMs aggressively kill accessibility services to save battery. Add TouchPilot to the OEM's "protected apps" or "background app lock" list, then re-enable Accessibility for TouchPilot.

The agent seems stuck on the first step

Make sure the Accessibility service is actually enabled (Settings → Accessibility → TouchPilot → On). The agent will refuse to run tools until it can observe the screen.

I can't find the Accessibility toggle

The exact path varies by Android version and OEM. Search Settings for "Accessibility" and look for Downloaded services or Installed services.

If none of the above resolves your issue, file a Bug report with your device model, Android version, and TouchPilot commit.