Installation

Peach installs as one standalone peach executable plus a separately versioned engine runtime. Nothing is added to your app, and nothing needs sudo.

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

Requirements

supported
CLI installermacOS or Linux, on arm64 or x64, with curl
Node.js, npm, Bunnot needed: the executable embeds its own JavaScript runtime
Background servicemacOS (launchd) and Linux (systemd user service)
Native desktop appApple silicon on macOS 26 or later, and Linux x64; Windows x64 uses the Electron desktop app
Windowsno shell installer; download the desktop app from the peachsim.com home page, which installs the peach command too

Your app keeps its own toolchain: the React Native, Expo or One dev server you already run. Swift and Compose previews have their own requirements, covered in Running Swift apps and Running Compose apps.

On Linux, the browser Peach drives links a set of system libraries that minimal servers and containers often lack. When any are missing, the first peach open downloads a verified bundle of them into ~/.peach and uses it, so you do not need a package manager or sudo.

What the installer does

  1. 1.
    Detects macOS or Linux and the processor, then downloads the matching peach executable. It checks the download against its published sha256 and confirms the executable reports the expected version before it replaces an existing copy in ~/.local/bin.
  2. 2.
    Appends one commented block to your shell profile (~/.zshrc, ~/.bashrc plus your bash login profile, or ~/.profile). The block adds ~/.local/bin to PATH when needed and, for zsh and bash, loads the Peach shell integration. Set PEACH_NO_MODIFY_PATH=1 to print those lines instead of writing them.
  3. 3.
    Hands off to peach setup, which downloads and verifies the engine runtime into ~/.peach/runtimes/, enables the background service, and installs the native desktop app on Apple silicon with macOS 26 or later and on Linux x64:
    • +
      In a fully interactive terminal, setup asks before each choice.
    • +
      With the usual curl ... | sh, stdin is the script, so setup takes the recommended defaults without prompting.
    • +
      From a coding agent’s shell, which has no terminal, setup takes the same defaults but leaves the background service off.
    • +
      In CI (CI is set), the installer stops and prints the setup command to run: peach setup --ci --yes --json.

The installer finishes in well under a minute. A shell that was open before the install does not see the new PATH yet; open a new terminal, or run the export PATH=... line the installer prints.

Run peach setup again at any time to make different choices, or peach setup --dry-run to see what it would do.

Pin a version or install directory

terminal
curl -fsSL https://peachsim.com/install.sh | PEACH_VERSION="<version>" sh
curl -fsSL https://peachsim.com/install.sh | PEACH_CLI_PREFIX="$HOME/tools" sh

PEACH_VERSION takes a published CLI version. PEACH_CLI_PREFIX installs to <prefix>/bin/peach instead of ~/.local/bin/peach.

Install in CI

CI needs no background service. Install without touching a shell profile, start your app’s dev server, and open it headless. A free Peach account is required for headless runs and tests: create a key with peach auth key create or Billing → API Keys, then set PEACH_API_KEY:

terminal
curl -fsSL https://peachsim.com/install.sh | PEACH_NO_MODIFY_PATH=1 sh
export PATH="$HOME/.local/bin:$PATH"
peach open 8081 --driver playwright --headless --no-describe
peach test .maestro/

peach open starts the bridge for the job, and it exits with the job. The browser comes from your app’s own playwright package when it has one; otherwise the first peach open installs a pinned playwright-core into ~/.peach and downloads the Chromium build it expects. Nothing registers with launchd or systemd.

For nested suites, add .maestro/config.yaml with flows: ["flows/**"] to select .maestro/flows/. Without a config, only top-level YAML flows run. See Tests in CI for a complete workflow.

Updates

The CLI and the engine runtime are versioned independently. Update both with:

terminal
peach upgrade

peach upgrade installs the latest stable runtime (or the runtimeVersion your repo pins), then downloads a newer verified CLI when one exists. It prints the old and new versions and the runtime’s release notes. If the CLI changed and the background service is running, it restarts the service onto the new CLI. A new runtime needs no restart: the next sim you open uses it, and sims already open keep the runtime they booted with.

terminal
peach upgrade --channel beta # latest runtime from the beta channel
peach upgrade --to <version> # an exact CLI release, newer or older

You rarely need to run it by hand. The background service checks for a new default runtime when it starts and every hour. Interactive commands check for a newer CLI at most once every 20 hours, in the background, and print one short line on stderr when there is one. The check never delays a command and stays silent for agents, CI, JSON output, and piped use.

Set PEACH_UPDATE_CHECK=off to turn off automatic CLI checks, runtime updates and their notices. A running bridge keeps the setting it started with, so for the background service persist it with PEACH_UPDATE_CHECK=off peach daemon install --force.

Versions and runtimes

terminal
peach version # CLI and runtime versions, available updates, changelog link
peach --version # two terse lines, no network check, for scripts
peach runtime list # installed and available runtimes
peach runtime use <version>

To keep one app on a fixed engine, set runtimeVersion in that repo’s optional peach.config.ts. Other apps are not affected. See peach runtime and the changelog.

The bridge and background service

Every local simulator talks to a lightweight HTTP and WebSocket bridge, on port 7668 by default. It discovers your local dev servers, serves the simulator page, and connects CLI commands to open sims. It also serves your app’s bundle and proxies its network traffic through one local origin, so requests that browser origin rules would block still reach your servers.

The bridge must run while a simulator is open. peach open starts one when none is running. The background service keeps a bridge and the runtime ready between commands, which makes inspection, interaction and test commands start much faster, so it is strongly recommended for local and agent work. Manage it with peach daemon:

terminal
peach daemon install # enable it, if you declined during setup
peach daemon status # registered and alive?
peach daemon restart
peach daemon logs -n 100

Uninstall

peach daemon uninstall removes the background service and nothing else: the launchd agent or systemd user service, its launcher, and its logs. Everything in ~/.peach stays, including installed runtimes, device profiles and their app storage.

To remove everything, purge ~/.peach too, then delete the executable:

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

Then delete the block that starts with # added by the peach installer from your shell profile. Left behind, it makes every new shell try to load a CLI that is gone. If you installed the desktop app, remove it with peach desktop uninstall before you delete the CLI.

Native desktop app

On Apple silicon with macOS 26 or later, and on Linux x64, Peach shows your app in its native desktop app, which is faster than the browser. On an older Mac it opens in a browser window. Setup installs it, and on a Mac the first peach open installs it if it is missing. The background service is a separate choice. To install or update it by hand:

terminal
peach desktop install

On macOS this installs the app in Applications. On Linux it downloads a .deb and runs sudo apt-get install for its system dependencies, and it needs a desktop session. Linux CI can fetch the standalone headless host instead with peach desktop install --native --yes. Intel Macs and Linux arm64 use the browser. Choose a browser window explicitly with peach open 8081 --driver playwright --headed.

Optional conveniences

Teach your coding agent

terminal
peach skill install

This installs the bundled Peach skills into the skill folders of Claude Code and Codex (pass claude or codex to pick one), so your agent learns the supported workflow. peach skill show lists them. Restart the agent session afterwards so it reloads its skill list. See Agents setup.

Add Peach to a repository

terminal
peach setup --app ./apps/mobile

Inside a Git repository, setup can add an exact peachsim dev dependency and a peach package script, so teammates get the same version.

Jump to source from inspect mode

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

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. Keep it before react-native-worklets/plugin when you list both. Apps using babel-preset-expo omit the explicit Worklets plugin because the preset configures it.

Next

Continue to the Quick Start to open your app, run a flow, and share a preview. Before you open a large app, run peach compat in its project root to see which of its packages Peach runs.