peach open
Resolve a port, dev-server URL, bundle URL, built bundle file, full shell URL, or app deep link. It also runs native apps: an Xcode project or workspace, a SwiftPM package or a Swift file compiles on this machine against the Swift toolchain and SDK Peach pins and installs on first use (beta), and an Android app module compiles its Kotlin and Compose sources with the pinned Kotlin toolchain, which needs a Java runtime (beta). A native open stays in the foreground, recompiles on each source edit and closes its preview on Ctrl+C; when an app imports modules Peach does not provide, it lists each one with the files importing it. A bundle file loads with no dev server running: the bridge serves a copy, and the build’s own __DEV__ prelude picks production or development React. The first browser sim uses an isolated Playwright Chrome for Testing profile. Later opens reuse the saved sim and navigate it in place. Custom-scheme URLs and leading-slash routes dispatch through the current app’s React Native Linking pipeline. Named profiles force a fresh desktop or Playwright sim because storage isolation is fixed at window/context construction time. A peach preview/build link (e.g. https://peachsim.com/preview/<id>) is a full player page, not a driveable sim; open recognizes it and launches it in your browser for viewing instead of mis-loading the HTML as a bundle.
Options
| flag | description |
|---|---|
--target <name> | select the native Xcode application target |
--scheme <name> | select the native Xcode application scheme |
--activity <name> | select the Android application activity |
--upload-source | compile a Swift app on Peach Cloud instead: consent to uploading the selected package and its watched edits; requires peach login or PEACH_API_KEY |
--swift-sdks-path <directory> | install and look up the pinned wasm SDK in this directory instead of PEACH_HOME/swift/sdks; also configurable with PEACH_SWIFT_SDKS_PATH |
--host-port <port> | pin the loopback port of a native app host; otherwise an available port is selected |
--no-open | keep a native app host running without opening a preview |
--new | open a genuinely concurrent sim instead of reusing the current one. each new sim creates another isolated browser tree |
--profile <id> | open with an isolated persistent storage profile |
--id <name> | name this agent. the sim’s agent indicator shows it while you drive the sim, and every later peach command from this session keeps using it. PEACH_AGENT_ID sets the same name from the environment, and —id wins |
--ephemeral | open with a temporary isolated storage profile. combined with --new --driver playwright this is the guaranteed-clean boot: a throwaway browser profile with no service worker registration and no preview-share IndexedDB, so nothing a previous sim left behind can steer this one |
--driver <id> | launch a fresh sim through playwright (default browser surface), desktop (native app), or electron (Windows) |
--headless | pass headless=true to the launch driver (useful with --driver playwright for CI runs); needs a signed-in account |
--headed | launch the driver with a visible window instead of headless; the default on a desktop outside agent sessions |
--chromium | render this open in plain Chromium without acquiring or attaching a native host (playwright only). Linux headless defaults to native; PEACH_DESKTOP_VERSION pins the native build |
--cdp-port <number> | expose Chrome remote debugging on this port so the sim can be cpu-profiled while still driveable over the bridge (playwright driver only) |
--device <model> | device profile for the opened sim (e.g. iphone-16, iphone-16-pro-max, pixel-8). stamped on the engine URL so every open path honors it; playwright sims also size their viewport to the device instead of a desktop-shaped default |
-t, --theme <light|dark|auto> | appearance scheme for the opened sim, stamped on the engine URL so it wins over the persisted scheme at boot |
--posture <closed|book|open|laptop|tent> | fold rest for the opened sim, stamped on the engine URL next to —device so it round-trips across reloads. the foldable iPhone Duo boots at that rest, so the app sees its hinge from the first frame; anything else boots closed |
--render-resolution <high|medium|low> | raster quality for the opened sim, stamped on the engine URL. the default is medium (density 2); high renders at the device’s native scale (3 on current iPhones), which native-parity captures need |
--predictive-text <on|off> | the keyboard’s QuickType suggestion lane for the opened sim, stamped on the engine URL over the persisted setting. native oracles captured by a test driver run with it off, so a keyboard capture compared against one passes off |
--orientation <portrait|landscape> | interface orientation the sim boots in, stamped on the engine URL like —posture. defaults to the device’s own: portrait, or landscape for an open iPhone Duo |
--viewport <WxH> | explicit page size for a driver-launched sim (e.g. 1920x1080 to frame the 3d stage in landscape for film capture). takes precedence over the device-derived window size (playwright driver only) |
--arg <value> | one launch argument, as a simctl launch argument is. a Swift app reads each in order, verbatim, as ProcessInfo.arguments[1…] after the executable path (e.g. —arg —showcaseScene —arg thread). repeatable |
--base-url <url> | base shell URL to wrap around bundle targets |
--bundle-origin <url> | manifest and asset origin supplied by a recorder proxy |
--project-root <directory> | local app checkout supplying native configuration when its packager runs on another machine; a missing project is an error |
--replace <module>=<file> | replace a Metro module with a local file for this run; useful for swapping in a deterministic fixture component during demos. repeatable |
--remap <host:port>=<host:port> | rewrite guest-app fetch/websocket traffic from one host:port to another for this run (e.g. a third-party e2e suite that hardcodes a port already taken on the host). repeatable |
--load-env | read the project’s env file the way react-native-config’s iOS build compiles it into the app (ENVFILE if set, else .env) and hand it to the app’s Config. without it Config is empty, as in a build that found no env file, and the app’s first read warns in the console. the values travel in the sim’s page URL; edit the file and open again to pick up changes |
--no-describe | skip the automatic describe snapshot that prints right after open finishes (useful when scripting and you only want open’s own output) |
--hot | force metro HMR on (sets hot=true on the bundle URL). default for interactive opens; edits hot-apply through peach’s HmrClient |
--no-hmr | force metro HMR off (sets hot=false on the bundle URL). default under --driver playwright so agent/CI runs stay deterministic with no in-bundle refresh wiring |
--port <number> | the WS BRIDGE port peach talks to (defaults to 7668). NOT the app port: the dev-server port is the positional argument, so it is peach open 4260, never peach open --port 4260 |
Examples
Run It From The App Root
Start Metro, Expo, React Native, or One with the app’s normal development command. peach does not own that process. Then run peach open from the app project root, where its Metro or Expo configuration lives. The command can run elsewhere, but this directory is the fallback for discovering custom native-linked fonts, the configured splash screen, and other file-based app configuration when the development server does not report its project root.
Resolution Rules
open accepts five inputs:
- +a raw dev-server port like
8081 - +a dev-server base URL like
http://localhost:8081 - +a full bundle URL
- +a built bundle file like
./dist/ios.js(.js,.bundleor.jsbundle) - +a full peach shell URL
For raw targets, open now hands the input to the shell instead of guessing a fallback bundle URL. Numeric targets open as /rn/<port>, while non-port inputs fall back to /rn?open=... so ConnectRN can resolve them inside the shell.
Production Bundles
A built bundle runs with no dev server, on production React and React Native. Build it with the app’s own tool, then open the file:
The bridge serves a copy of the file, so the sim keeps working after the command returns. The bundle’s own __DEV__ prelude decides production or development, so the sim boots the matching runtime first. Fonts, splash and identity come from the nearest app above the file, or from --project-root. Peach serves the bundle file only: images an app loads from a Metro assets folder beside it do not load this way yet.
Managed Surfaces
open uses an isolated Playwright browser by default. Pass --driver desktop for the native app on Mac and Linux, or --driver electron for Windows. Both register with the same bridge and reuse the current managed sim unless you explicitly request a new profile or sim.
Sim pages never fall through to the operating-system browser handler. Preview pages and external links still open in the user’s browser because they are viewing pages, not driveable sims.