Running Compose apps
peach open opens an Android app module in Peach. It runs in the
foreground: it compiles your module, cold-starts the launcher activity on a
simulated Android device, rebuilds when you save, and stops everything it
started when you press Ctrl+C.
Kotlin support is in beta. See the Android overview for what runs today.
Requirements
- +A Java runtime, version 17 or newer. The Kotlin compiler runs on the JVM, the same one an Android build uses. Peach finds it through
JAVA_HOME, thenPATH, as Gradle does. - +Network access on the first run. Peach downloads its pinned Kotlin compiler and Compose libraries once, verifies each against its checksum, and caches them in the Peach home directory for every later app.
You do not need Android Studio, the Android SDK, Gradle or an emulator. Everything compiles locally; no source leaves your machine.
What Peach reads
Pass the app module directory, the one that holds
src/main/AndroidManifest.xml (usually app/). Peach walks up from it to the
directory with settings.gradle.kts or settings.gradle, which is your
project root.
Gradle files
Peach reads your Gradle files as text and never runs Gradle, so the values it needs must be literals:
- +
namespace(or the manifest’spackage),applicationIdandtargetSdkin the module’sbuild.gradle.ktsorbuild.gradle. - +The
org.jetbrains.kotlin.androidplugin version, from the root build file, the module build file, orkotlin = "..."ingradle/libs.versions.toml.
A value computed in code is refused with its file and line, for example
targetSdk must be a literal for peach open.
Plugins. The module may apply com.android.application,
org.jetbrains.kotlin.android and org.jetbrains.kotlin.plugin.compose. Any
other plugin is refused.
Dependencies. Each dependency must be a literal "group:artifact:version"
inside Peach’s pinned closure:
| Group | Version Peach links |
|---|---|
androidx.compose.ui | 1.13.0-alpha02 |
androidx.compose.foundation | 1.13.0-alpha02 |
androidx.compose.runtime | 1.13.0-alpha02 |
androidx.compose.material3 | 1.5.0-alpha27 |
androidx.compose.material:material-icons-core | 1.7.6 |
androidx.navigation | 2.10.0 |
androidx.activity | 1.13.0 |
androidx.lifecycle, androidx.savedstate | any; Peach supplies them |
A pinned group at another version is refused with the version Peach expects. A dependency outside the closure is refused with its location. Test, Android test, debug and release dependencies are ignored.
Because each coordinate must be literal, a Compose BOM (platform(...)) or a
version catalog alias (libs.androidx...) in dependencies is refused. Write
the coordinates out with their versions.
The manifest
Peach reads src/main/AndroidManifest.xml for the application, its activities
and aliases, themes, and per-activity settings such as configChanges,
windowSoftInputMode and enableOnBackInvokedCallback. It refuses, with the
location:
- +
<provider>elements - +
android:processon the application or a component - +
android:appComponentFactory - +Gradle placeholders such as
${applicationId}in manifest attributes
Sources and resources
Every .kt file under src/main/kotlin and src/main/java compiles. A
.java file is refused; Java sources are not supported. Resources come from
src/main/res: themes and colors in values and values-night, and vector
and bitmap drawables, chosen by density then API level as Android chooses
them.
Which activity opens
Without a flag, Peach opens the enabled, exported activity or
activity-alias whose intent filter has android.intent.action.MAIN and
android.intent.category.LAUNCHER. If none matches, Peach says so. If more
than one matches, Peach lists them and asks you to pick one with --activity.
--activity <name> opens a specific activity or alias, as
adb shell am start -n does. Names resolve against your namespace, so
.SettingsActivity and com.example.app.SettingsActivity both work. Peach
answers with Android’s own errors: a missing class, a disabled activity, or an
activity that is not exported.
Lifecycle and saved state
Peach drives your app with Android’s lifecycle, in Android’s order:
- +Cold start. Your
Applicationruns first, then the activity is created, started and resumed in activity thread order, and its window attaches. The activity’s theme (or the application’s, or the platform default for your target SDK) styles the window. - +Leaving and returning. When the app leaves the foreground, for example with
peach shell home, the activity pauses and stops, then saves its instance state. Returning restarts it withonRestart,onStartandonResume. - +Dark theme. Switching appearance (
peach shell appearance dark) changes the configuration’s night mode. TheApplicationreceivesonConfigurationChangedfirst. An activity that listsuiModeinandroid:configChangesreceivesonConfigurationChangedtoo; any other activity relaunches from its saved state. A relaunch keeps the activity’sViewModels and restoresrememberSaveablevalues, and each launch picks the day or night theme. - +View models.
viewModels()and Compose’sviewModel()build yourViewModelandAndroidViewModelclasses with the constructors the default factory accepts, including aSavedStateHandle.
Window, insets and Back
- +Apps targeting SDK 35 and above are edge to edge. Below 35, windows fit system windows unless you call
enableEdgeToEdge(), which behaves asandroidx.activitydoes. - +Compose receives system bar, display cutout, system and mandatory gesture, and tappable element insets from the selected device, plus the keyboard’s visibility and animated height.
windowSoftInputModechooses pan, resize or nothing. - +Below SDK 35, the theme’s
statusBarColorandsetStatusBarColorpaint the status bar. From SDK 35 the status bar is transparent and ignores them, as on a device.setNavigationBarColorrepaints the navigation bar. - +Back follows Android’s dispatch by window, priority and registration order. Predictive Back gestures deliver
BackEventprogress when your manifest enablesenableOnBackInvokedCallbackor your target SDK is above 35. An unhandled Back moves the task behind home.
Editing
Peach watches your module. When you save, it rereads the module, recompiles,
prints Kotlin artifact: <hash>, and restarts the app in a new process, as
installing a rebuilt app does. State does not carry across an edit. If the
build fails, Peach prints the error and leaves the running app as it was.
The first compile must succeed before the preview opens.
Flags
| Flag | Effect |
|---|---|
--activity <name> | Open this activity or alias instead of the launcher, as adb shell am start -n does. |
--device <model> | Open on this Android device: pixel-10 (default), pixel-8, pixel-8-three-button, pixel-9-pro-xl, galaxy-s24 or galaxy-s24-ultra. An iOS model is refused. |
--headless | Open the preview without a visible browser window. |
--no-open | Keep compiling and serving the app without opening a preview. A running Peach lists it in the Kotlin app on an Android device’s dock. |
--host-port <port> | Pin the local port the Kotlin preview host listens on. Otherwise Peach picks a free one. |
--driver <playwright|desktop|electron> | Choose which browser driver opens the preview. |
--cdp-port <port> | Pin the Playwright debugging port. |
The preview host answers requests from your own machine only.
Once it is running
The app runs in a normal Peach simulator, so the other commands work on it:
peach screenshot, peach record, appearance and device changes, and tests.
See Testing, Device state
and Sharing.