Installation

Peach’s recommended bootstrap path is its public, inspectable shell installer.

Read the complete script before running it. With Node.js installed, npx peachsim runs the same script, shipped inside the peachsim npm package.

Run peach project-report from your repository to print its apps, dependency versions and toolchains; use peach project-report --json for JSON, then peach support report "<description>" to preview and send the report after you explicitly confirm.

#What the installer does

1. +
   Detects macOS or Linux and downloads the matching standalone peach executable into the user-owned ~/.local/bin directory. The executable is compiled with Bun and embeds the JavaScript runtime needed to execute the CLI, so Bun itself is not an installation prerequisite.
2. +
   Verifies the executable against its published sha256 before replacing an existing install. It never uses sudo, npm, or a preinstalled JavaScript runtime, and it never changes the current project.
3. +
   Starts guided setup in an interactive terminal. Setup downloads and verifies the separately versioned engine runtime into ~/.peach/runtimes/ and can register the background service through launchd on macOS or systemd on Linux. It keeps the lightweight local bridge and engine runtime ready between commands. This is strongly recommended for local agent work because inspect, interaction, and test commands avoid repeated bridge startup. It remains optional, and peach open starts the same bridge when one is not running.
4. +
   Appends one commented block to your shell profile (~/.zshrc, ~/.bashrc, or ~/.profile). The block adds ~/.local/bin to PATH when necessary and loads the Peach shell integration. Set PEACH_NO_MODIFY_PATH=1 to print those lines instead of writing them.

#Linux system libraries

On Linux the simulator runs in Playwright’s Chromium headless shell, which links system libraries a minimal server or container image may not have. If any are missing, peach open stops before launching and prints the exact apt-get install line for them. On Debian 12 the full set is:

sudo apt-get install --no-install-recommends libglib2.0-0 libnspr4 libnss3 \
  libatk1.0-0 libatk-bridge2.0-0 libatspi2.0-0 libdbus-1-3 libx11-6 libxcb1 \
  libxcomposite1 libxdamage1 libxext6 libxfixes3 libxrandr2 libgbm1 libexpat1 \
  libxkbcommon0 libudev1 libasound2

Ubuntu 24.04 and Debian 13 name five of these with a t64 suffix: libglib2.0-0t64, libatk1.0-0t64, libatk-bridge2.0-0t64, libatspi2.0-0t64 and libasound2t64.

#Pin a version or installation directory

The same installer accepts an exact CLI version and a user-writable prefix:

curl -fsSL https://peachsim.com/install.sh | PEACH_VERSION=0.1.377 sh
curl -fsSL https://peachsim.com/install.sh | PEACH_CLI_PREFIX="$HOME/tools" sh

The first human run explains and offers the background service. If you decline, enable it later with peach daemon install.

#Remove the daemon, or everything

peach daemon uninstall removes the background service and nothing else: the launchd agent or systemd user service, the generated launcher, and the daemon’s logs. Everything in ~/.peach stays, so installed engine runtimes, device profiles and their app storage, and simulators you still have open are untouched.

Add --purge to delete ~/.peach as well, then remove an installer-managed CLI:

peach daemon uninstall --purge
rm "$HOME/.local/bin/peach"

Then delete the # added by the peach installer block from your shell profile. Left behind, it makes every new shell try to load a CLI that is gone.

#Updates

The CLI and the engine runtime version independently. The daemon keeps the runtime current automatically; to update both halves on demand:

peach upgrade

Successful interactive CLI commands refresh a cached stable CLI version in the background at most once every 20 hours. A newer CLI produces one short update line on stderr, with a machine-wide cooldown so frequent releases do not nag. The check never delays the command and stays silent for agents, CI, JSON, piped, and noninteractive use. Set PEACH_UPDATE_CHECK=off to disable automatic CLI checks, runtime updates, and their notices. Start the bridge with this setting. For a background service, persist it with PEACH_UPDATE_CHECK=off peach daemon install --force. Setting it on a later CLI command does not change a bridge that is already running.

peach version checks and shows available CLI and runtime updates. The terse peach --version remains a two-line offline read for scripts. peach runtime manages installed versions. See the changelog for what’s new.

#Open an app

In the app project root, start the same Metro, Expo, React Native, or One dev server command you already use:

npx expo start --port 8081
# or: npx react-native start --port 8081
# or: npm run dev / pnpm run dev / bun run dev for One

Then open it:

peach open 8081

No per-app package install is needed. No iOS or Android native build is needed. Metro, Expo, or One serving the bundle is enough. Peach does not start, configure, or replace that development server.

Peach supports iOS and Android device profiles. Pass --device pixel-8 to open an Android profile, or use an iPhone profile such as iphone-17-pro.

Run peach open from the app project root or monorepo root. Peach prefers the project root advertised by Expo. From a monorepo root it inspects declared package workspaces and automatically selects the only React Native app. This is the directory that contains the Metro or Expo configuration and where you would normally start the development server. The command works from elsewhere when the server advertises its project root, but the current directory is the fallback used to discover file-based configuration. When multiple React Native apps match, start from the intended app directory so Peach does not have to guess.

Use bare peach to open ConnectRN and choose from the local development servers shown inside the simulator:

peach

#The bridge and daemon

Every local simulator uses a lightweight HTTP and WebSocket bridge. It serves the browser simulator at http://localhost:7668/ by default, discovers local development servers, and connects CLI commands to open simulator tabs. You can open that URL in any browser like any other local page; peach open does this for you.

The bridge also presents the simulator runtime and Metro bundle through one local origin. Its bundle proxy deliberately does not forward the app server’s Content Security Policy (CSP) header, because that policy describes the app server’s own page rather than the CanvasKit simulator and its worker runtime. It also proxies guest fetch and WebSocket traffic that would otherwise be blocked by browser origin rules.

The bridge process is required while a simulator is open. The recommended background service keeps the bridge and runtime ready, which makes agent inspection, interaction, and test commands start much faster. Enable it later with peach daemon install if you decline during onboarding. CI can start the bridge for the job and let it exit with the job.

#CI without a daemon

Install the CLI directly in CI, start your app’s normal development server, and use the Playwright driver. Run peach open from your app directory. The driver uses the app’s own playwright package when it has one; otherwise the first peach open installs a pinned playwright-core into ~/.peach. Either way it downloads the Chromium build that package expects. This path never registers launchd or systemd:

curl -fsSL https://peachsim.com/install.sh | PEACH_NO_MODIFY_PATH=1 sh
peach open 8081 --driver playwright --headless --no-describe
peach maestro test .maestro/

See Tests in CI for a complete workflow.

#Optional conveniences

No project setup is required. You can re-run the optional guided choices at any time:

peach setup
peach setup --dry-run

Use --app <dir> when you want to offer an exact peachsim development dependency and peach package script to teammates in a specific Git repository:

peach setup --app ./apps/mobile

#Optional: source jumps in inspect mode

Inspect mode can open the selected React Native element in your editor when the app bundle includes source locations. Add the optional Babel plugin to your app source transform:

plugins: [
  [
    'peachsim/jump-to-source-babel',
    {
      include: [__dirname],
    },
  ],
  'react-native-worklets/plugin',
]

The plugin adds an srcloc prop to JSX elements outside node_modules, dist, and build. In a custom Babel stack that lists both plugins, keep peachsim/jump-to-source-babel before react-native-worklets/plugin. Apps using babel-preset-expo omit the explicit Worklets plugin because the preset configures it automatically.

#Desktop app

The desktop app is optional. Native installers are available for Apple Silicon macOS and Linux x64. Windows x64 uses the published Electron installer. Intel Mac and Linux arm64 can use the browser.

peach desktop install
peach desktop

On Apple Silicon macOS the command verifies the versioned native host and installs the native app in Applications. On Linux it downloads the native .deb and runs sudo apt-get install to install its system dependencies. Linux CI can acquire the standalone headless host with peach desktop install --native --yes.

Electron is retired on Mac and Linux. Existing CLI users with an Electron install receive one notice to run peach desktop install. --electron and --driver electron select the native app on those platforms.

Opening a desktop window automatically from a bundler plugin stays opt-in, and PEACH_NO_OPEN=1 disables it everywhere.

#Agentic use

The same peach CLI is how AI coding agents drive the sim. There is no separate agent runtime and no MCP server to configure. Any agent that can run shell commands uses peach directly after the standalone install. Install the bundled setup, debugging, test, visual, and performance skills so the agent learns the supported workflow:

peach skill install

For local agent work, enable the background service with peach daemon install. The CLI still works without it, but every command otherwise relies on an on-demand bridge instead of one already running.

Restart the agent session after installation so it reloads the skill list.

See Agents → Setup to verify the bridge, Agents → CLI Use for day-to-day commands, and MCP & Agent Tools for why the CLI is the integration surface instead of MCP.

#Next

Continue to the Quick Start to open your app, run a test, and upload a shareable preview.