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 installer | macOS or Linux, on arm64 or x64, with curl |
| Node.js, npm, Bun | not needed: the executable embeds its own JavaScript runtime |
| Background service | macOS (launchd) and Linux (systemd user service) |
| Native desktop app | Apple silicon on macOS 26 or later, and Linux x64; Windows x64 uses the Electron desktop app |
| Windows | no 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.Detects macOS or Linux and the processor, then downloads the matching
peachexecutable. 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.Appends one commented block to your shell profile (
~/.zshrc,~/.bashrcplus your bash login profile, or~/.profile). The block adds~/.local/bintoPATHwhen needed and, for zsh and bash, loads the Peach shell integration. SetPEACH_NO_MODIFY_PATH=1to print those lines instead of writing them. - 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 (
CIis 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
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:
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:
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.
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
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:
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:
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:
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
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
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:
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.