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.

terminal
peach open ./app
peach open ./app --activity .SettingsActivity

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, then PATH, 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’s package), applicationId and targetSdk in the module’s build.gradle.kts or build.gradle.
  • +
    The org.jetbrains.kotlin.android plugin version, from the root build file, the module build file, or kotlin = "..." in gradle/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:

GroupVersion Peach links
androidx.compose.ui1.13.0-alpha02
androidx.compose.foundation1.13.0-alpha02
androidx.compose.runtime1.13.0-alpha02
androidx.compose.material31.5.0-alpha27
androidx.compose.material:material-icons-core1.7.6
androidx.navigation2.10.0
androidx.activity1.13.0
androidx.lifecycle, androidx.savedstateany; 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:process on 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 Application runs 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 with onRestart, onStart and onResume.
  • +
    Dark theme. Switching appearance (peach shell appearance dark) changes the configuration’s night mode. The Application receives onConfigurationChanged first. An activity that lists uiMode in android:configChanges receives onConfigurationChanged too; any other activity relaunches from its saved state. A relaunch keeps the activity’s ViewModels and restores rememberSaveable values, and each launch picks the day or night theme.
  • +
    View models. viewModels() and Compose’s viewModel() build your ViewModel and AndroidViewModel classes with the constructors the default factory accepts, including a SavedStateHandle.

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 as androidx.activity does.
  • +
    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. windowSoftInputMode chooses pan, resize or nothing.
  • +
    Below SDK 35, the theme’s statusBarColor and setStatusBarColor paint the status bar. From SDK 35 the status bar is transparent and ignores them, as on a device. setNavigationBarColor repaints the navigation bar.
  • +
    Back follows Android’s dispatch by window, priority and registration order. Predictive Back gestures deliver BackEvent progress when your manifest enables enableOnBackInvokedCallback or 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

FlagEffect
--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.
--headlessOpen the preview without a visible browser window.
--no-openKeep 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.