Installation

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

Read the complete script before running it.

#What the installer does

1. +
   Detects macOS or Linux and downloads the matching standalone rnx 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 ~/.rnx/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 rnx 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 rnx shell integration. Set RNX_NO_MODIFY_PATH=1 to print those lines instead of writing them.

#Pin a version or installation directory

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

curl -fsSL https://rnxsim.com/install.sh | RNX_VERSION=0.1.377 sh
curl -fsSL https://rnxsim.com/install.sh | RNX_CLI_PREFIX="$HOME/tools" sh

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

#Remove the daemon, or everything

rnx 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 ~/.rnx stays, so installed engine runtimes, device profiles and their app storage, and simulators you still have open are untouched.

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

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

Then delete the # added by the rnx 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:

rnx 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 RNX_UPDATE_CHECK=off to disable the check and notice.

rnx version checks and shows available CLI and runtime updates. The terse rnx --version remains a two-line offline read for scripts. rnx 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:

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

Then open it:

rnx 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. rnx does not start, configure, or replace that development server.

rnx 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 rnx open from the app project root or monorepo root. rnx 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 rnx does not have to guess.

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

rnx

#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; rnx 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 rnx 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. This path never registers launchd or systemd:

curl -fsSL https://rnxsim.com/install.sh | RNX_NO_MODIFY_PATH=1 sh
bunx playwright install chromium
rnx open 8081 --driver playwright --headless --no-describe
rnx 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:

rnx setup
rnx setup --dry-run

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

rnx 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: [
  [
    'rnxsim/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 rnxsim/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. First-run onboarding offers it alongside the zero-download Browser option. It gives you a more simulator-like shell on top of the same rnx runtime and works on macOS, Windows, and Linux. The Apple Silicon download is about 108.6 MiB and the installed app takes about 267 MiB, so the browser remains the recommended first-run path. Install it when you want named, app-specific desktop windows:

rnx desktop install

On macOS the command downloads a DMG, mounts it, and installs rnx.app. On Windows it runs the signed NSIS installer and discovers the registered install even when you choose a custom directory. On Linux it installs the matching x64 or arm64 AppImage. The terminal shows a progress bar with percentage and transferred size while downloading.

The installer clears the macOS quarantine attribute. Opening a desktop window automatically from a bundler plugin stays opt-in, and RNX_NO_OPEN=1 disables it everywhere.

#Agentic use

The same rnx 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 rnx directly after the standalone install. Install the bundled setup, debugging, test, visual, and performance skills so the agent learns the supported workflow:

rnx skill install

For local agent work, enable the background service with rnx 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.