Develop

Port your Android app with AI

Updated: May 12, 2026

If you have an existing Android app, you can port it to Meta Horizon OS using AI-powered tooling combined with Meta Horizon Debug Bridge (hzdb). The hz-android-2d-porting agentic skill automates the porting process by analyzing your project structure, identifying required changes, generating code modifications, and validating that the result builds correctly.

Prerequisites

Before you begin, ensure you have the following:

An Android app that uses Gradle

Meta Horizon Debug Bridge (hzdb), installed and configured

An AI coding tool that supports MCP servers and skills (for example, Claude Code or Cursor)

A Meta Quest device or Meta Spatial Simulator (included with the Meta Horizon Android Studio plugin) for testing

Port your app

Step 1: Open your project

Open the existing Android project in your AI coding tool. The project must have a standard Gradle structure.

Step 2: Run the porting prompt

Enter the following prompt in your AI coding tool:

Port my Android app to Meta Horizon OS for Quest

The AI analyzes the project and walks you through each step, waiting for confirmation before making changes.

Step 3: Review the plan

The AI generates a porting plan that shows:

Every file that will be modified or created

The specific changes for each file

Any potential compatibility issues detected

Review and confirm the plan to proceed.

Step 4: Build and test

After changes are applied, the AI automatically builds the app. If a Quest device is connected, it deploys and launches the app on the device. To build and install manually, run the following commands:

./gradlew assembleDebug
hzdb app install <path to app-debug.apk>
hzdb app launch <your package name>

To learn more about about building manually, see Build your app from the command line ⁠.

What the AI changes

The porting skill⁠ modifies your project in three categories.

AndroidManifest.xml

Adds the com.oculus.intent.category.VR intent category

Configures required VR permissions

Sets appropriate screen orientation and display metadata

Adds Horizon OS feature declarations

Build configuration

Updates build.gradle with Meta Horizon OS SDK dependencies

Configures the correct minSdkVersion and targetSdkVersion

Adds the Meta Maven repository for SDK artifacts

Input and display

Adapts touch input handling for VR controller interaction

Adjusts layout and display settings for the VR panel environment

Handles orientation and window configuration for immersive display

Troubleshooting

Issue	Solution
Build fails after porting	Share the error with the AI. It diagnoses and fixes common causes such as SDK version mismatches and missing dependencies.
App launches but displays incorrectly	Ask the AI to adjust panel display settings. VR panel apps use a different rendering surface than mobile.
Touch input not working	The AI maps touch events to controller input by default. If custom gesture handling exists, inform the AI about the input architecture.
hzdb not found	If the Meta Horizon Android Studio Plugin is installed, hzdb is included. Otherwise, install it with `npx @meta-quest/hzdb` and verify with `hzdb --version`.