rnx

The source owner for the standalone rnx executable and the public rnxsim integration library used to drive a browser-native React Native simulator.

Overview

The CLI and library are separate public artifacts. The recommended installer downloads one Bun-compiled rnx executable that needs no Node.js, npm, or Bun installation. The rnxsim npm package contains bundler plugins, testing drivers, and library exports, with no command-line binary.

The executable updates itself with rnx upgrade. Successful interactive human commands refresh a cached stable CLI version in a detached process at most once every 20 hours. A newer version produces one short notice on stderr, once per version and no more than weekly. CI, agents, JSON output, pipes, and noninteractive commands stay silent. Set RNX_UPDATE_CHECK=off to disable the check and notice; rnx version checks explicitly, while rnx --version remains offline.

Neither artifact contains rendering code. The canvas engine (CanvasKit renderer, Yoga layout, iOS/Android shell chrome, Electron shell) lives in the private sootsim-engine workspace package and is shipped at runtime as a versioned tarball, fetched from the contrast.dev CDN and unpacked into ~/.rnx.

What this workspace gives you:

• the standalone rnx CLI source and binary build, which provides the primary debugging and automation surface (inspect the UI tree, tap elements, capture flows, screenshot, record, run agents)
• rnxsim/vite and rnxsim/metro — bundler plugins that serve the installed engine runtime from your own dev server
• rnxsim/jump-to-source-babel — an optional Babel plugin that annotates JSX with source locations so inspect mode can open the selected element in your editor
• rnxsim/detox — a drop-in Detox driver + jest preset
• rnxsim/sdk — the inspect/interact verbs as a programmatic API
• rnxsim/bridge-contract-input — parsers turning untrusted JSON into bridge-contract arguments
• rnxsim/skills — a registry of Contrast-flavored automation skills

Platform status: iOS is the parity baseline. Android is bootstrapped and usable for focused conformance slices (bundle/runtime identity, device profiles, shell chrome, gesture + three-button nav, system UI/window metrics with cutout-safe insets) but is not full parity until the Android launch gates in the Contrast repo plan pass.

What's in each distribution

| standalone rnx executable | rnxsim npm package | private engine runtime | | --- | --- | --- | | CLI commands and bridge client | Vite and Metro plugins | CanvasKit renderer and Yoga layout | | bridge daemon host | SDK and bridge contracts | iOS/Android shell chrome, home grid, app switcher | | runtime, browser, and desktop launchers | Detox driver and Jest preset | Electron shell and wasm | | Maestro, screenshots, recording, skills | native-resolution helpers and skills registry | the actual pixels |

The engine is delivered at runtime, never bundled into this package. A committed-but-unbuilt engine fix has no effect on a running sim until the runtime tarball is rebuilt and re-fetched.

Architecture

The architecture is a three-tier relay: a short-lived CLI process, a single persistent bridge daemon, and the sim itself — a browser/Electron page that internally splits into shell, compositor, and tenant workers.

graph TD
  subgraph cli["rnx CLI process (short-lived, cli/)"]
    BIN["bin.ts (dispatcher + privacy choice)"]
    SETUP["commands/setup.ts (guided daemon setup)"]
    RUNTIMECMD["commands/runtime.ts (runtime install/use)"]
    INSPECT["commands/inspect/* (describe/find/do/get/wait)"]
    FLOW["bridge-flow-runner.ts (Maestro YAML)"]
    DETOXCMD["commands/detox.ts + detox/ driver"]
    SHOTS["commands/screenshot + record"]
    AGENTCMD["commands/agent.ts"]
    WSB["ws-bridge.ts (WsBridge client)"]
    DRIVERS["drivers/* (chromium/electron/playwright/system)"]
  end
  subgraph daemon["bridge daemon process (persistent :7668)"]
    HOST["SootSimBridgeHost (host/bridge-host.ts, HTTP+WS)"]
    AGENTHOST["AgentHost (host/agent-host.ts, FIFO fan-out)"]
    AGENTSESS["agent-sessions.ts + attached-projects.ts"]
    SCAN["/__server-scan (dev-server-scanner.ts)"]
    PROXY["fetch-proxy-handler + websocket-proxy"]
    RTHTTP["runtime HTTP + self-update (runtime-delivery.ts)"]
  end
  subgraph sim["sim page (browser / Electron, launched by a driver)"]
    SHELLW["shell worker (iOS chrome, home grid, app switcher)"]
    COMPOSITORW["compositor worker (app canvases + independent rAF)"]
    TENANTW["tenant worker (guest RN app tree)"]
  end
  subgraph build["build-time plugins (src/)"]
    VITEONE["rnxsim/vite = vite-plugin-one.ts (serve runtime at /__soot/)"]
    VITERN["sootsim() = vite-plugin.ts (RN resolver + native stubs)"]
    METRO["rnxsim/metro = metro-plugin.ts"]
    COMPAT["@sootsim/compat stub-manifest (native seams)"]
    ENGINESHIM["sootsim-engine react-native shim"]
  end
  SKILLS["rnxsim/skills registry.ts (builtin skills)"]
  subgraph fs["~/.rnx (home-paths.ts)"]
    RTDIR["runtimes/<version>/ (engine assets)"]
    LOCK["daemon.json lockfile"]
    CFG["config.json"]
  end
  CDN["contrast.dev CDN (runtimes/manifest.json + tarballs)"]
  BIN --> SETUP
  BIN --> RUNTIMECMD
  BIN --> INSPECT
  BIN --> FLOW
  BIN --> DETOXCMD
  BIN --> SHOTS
  BIN --> AGENTCMD
  SETUP --> LOCK
  SETUP -->|"register launchd/systemd"| HOST
  RUNTIMECMD --> RTDIR
  RUNTIMECMD -->|"fetch runtime"| CDN
  INSPECT --> WSB
  FLOW --> WSB
  SHOTS --> WSB
  AGENTCMD --> WSB
  DETOXCMD --> DRIVERS
  DETOXCMD --> WSB
  WSB -->|"JSON WS cmds"| HOST
  HOST -->|"forward to registered sim"| SHELLW
  SHELLW -->|"replies + pushes"| HOST
  HOST -->|"relayed results"| WSB
  HOST --> AGENTHOST
  AGENTHOST --> AGENTSESS
  AGENTCMD --> AGENTHOST
  HOST --> SCAN
  HOST --> PROXY
  HOST --> RTHTTP
  RTHTTP --> RTDIR
  RTHTTP -->|"manifest + tarball"| CDN
  DRIVERS -->|"open sim page URL"| SHELLW
  SHELLW -->|"NativeUIRequest"| TENANTW
  VITEONE -->|"serve /__soot/ from"| RTDIR
  METRO -->|"serve /__soot/ from"| RTDIR
  VITEONE -.->|"launch electron app"| SHELLW
  VITERN -->|"alias react-native"| ENGINESHIM
  VITERN -->|"alias native pkgs"| COMPAT
  VITERN -->|"dev server hosts"| HOST
  SKILLS --> INSPECT

The CLI process (cli/bin.ts routes, cli/main.ts parses argv) lazy-imports exactly one command module per run. Bare rnx opens ConnectRN, whose simulator UI discovers running React Native development servers. The first human run offers the recommended background service and optional Desktop app, then opens the simulator before asking about private diagnostics or an optional repository install. rnx open ensures the engine runtime exists and starts a local foreground bridge when no daemon is reachable, then opens a WsBridge (cli/ws-bridge.ts) on port 7668 and sends JSON commands. Inspection/interaction verbs live in cli/commands/inspect/* and are re-exported as the programmatic rnxsim/sdk; the Maestro runner is cli/bridge-flow-runner.ts; the Detox compat driver is in detox/. Test and screenshot paths additionally use cli/drivers/*. Browser sims launch in an isolated Playwright Chrome for Testing profile; Electron is the native desktop surface.

The daemon is one process — SootSimBridgeHost (src/host/bridge-host.ts). rnx serve runs it in the foreground; the background daemon is the same process wrapped with autostart and the ~/.rnx/daemon.json lockfile. It is an HTTP+WS hub: sims register over WS, CLI clients connect to drive them, and the host forwards each command to the targeted sim and relays the reply back. It also serves the engine runtime over HTTP (with a self-update route), exposes /__server-scan to discover local metro/expo/vxrn/one dev servers, and proxies guest-app fetch/WebSocket traffic so the cross-origin tenant worker can reach localhost. The AgentHost extension owns one FIFO reader per agent session and fans agent events out to every subscriber.

During source development, each Vite bridge owns one ~/.rnx/dev-bridges/<port>.json heartbeat record. CLI defaults select the current PORT_OFFSET, then the current checkout, then the canonical :7668 bridge, so concurrent worktrees cannot replace or delete one another's address. Each Vite shell also publishes its exact bridge at /__sootsim/bridge, so a launcher that reuses a shell from another isolated RNX_HOME stays in that shell's bridge world without reading the other process's lockfile directory.

The sim is a browser/Electron page launched by a CLI driver. Inside that page run three workers: the shell worker owns device and native state, the compositor worker paints every visible CanvasKit surface, and the tenant worker runs the guest RN tree and sends native-UI requests to the shell. The bridge always addresses the shell worker, never an undifferentiated sim.

Two distinct plugin families round it out, and they must not be conflated:

• The published rnxsim/vite (src/vite-plugin-one.ts, rnxPlugin) and rnxsim/metro plugins do one thing: serve the installed runtime at /__soot/ so an app's own dev server can host the sim shell. The Vite plugin accepts an opt-in open option that launches a named Electron window when the dev server starts (skipped when CI or RNX_NO_OPEN is set).
• The internal sootsim() plugin (src/vite-plugin.ts) is a separate, much larger RN-resolution / native-stub plugin: it aliases react-native to the engine shim and native packages to @sootsim/compat stubs, applies worklets transforms, and is the one that instantiates SootSimBridgeHost inside its own dev server. It is used to build the engine/shell and to load external RN apps — it is not the published rnxsim/vite export.

Key components

| component | role | key files | | --- | --- | --- | | rnx CLI (bin + dispatcher) | Short-lived terminal entry point. Parses argv, owns the private-by-default one-time choice, lazy-imports one command per run, and routes direct open/runtime/inspection flows. | cli/bin.ts, cli/main.ts, cli/privacy.ts, cli/parse-args.ts, cli/help.ts, cli/commands/setup.ts, cli/commands/control.ts | | WsBridge client | Client side of the CLI→daemon link. Resolves the daemon port from the lockfile, opens a WS to :7668, sends JSON commands and awaits {id,result}/{id,error}. Used by every interactive command. | cli/ws-bridge.ts, src/bridge-constants.ts, cli/current-sim.ts | | inspect / SDK command surface | Runtime inspection + interaction verbs (describe, find, do tap, get errors, wait, layout, settle). Re-exported as rnxsim/sdk so programmatic callers drive a sim the same way the CLI does. | cli/commands/inspect/core.ts, cli/commands/inspect/actions.ts, cli/commands/inspect.ts, src/sdk.ts | | bridge-contract input parsers | Turn untrusted JSON into typed bridge-contract arguments, so a transport in front of a sim validates request bodies once instead of writing a second reader. | src/bridge-contract-input.ts, src/bridge-contract.ts | | Maestro / Detox runners | Drop-in test compatibility. bridge-flow-runner.ts runs Maestro YAML and recorded flows over the bridge; detox/ provides a by/element/expect/device driver + jest preset so existing Detox suites run unchanged. | cli/bridge-flow-runner.ts, cli/commands/maestro.ts, cli/commands/detox.ts, detox/index.ts, detox/jest-preset.cjs | | sim drivers | Launch or attach the actual sim page. Playwright owns isolated browser profiles; Electron owns the native desktop surface. The current sim is reused unless --new, --profile, or --ephemeral requests a separate one. | cli/drivers/index.ts, cli/drivers/registry.ts, cli/drivers/electron.ts, cli/drivers/playwright.ts | | SootSimBridgeHost (serve/daemon) | The bridge process (rnx serve, or autostarted as the daemon via launchd/systemd). HTTP+WS hub on :7668: relays commands between CLI clients and registered sims; also serves runtime HTTP, /__server-scan, and fetch/WS proxies. | src/host/bridge-host.ts, cli/commands/serve.ts, cli/commands/daemon.ts, src/home-paths.ts | | AgentHost + sessions | Agent-routing extension of the host: owns the single FIFO reader per agent session and fans agent:event/session-status pushes to every WS subscriber. Backed by agent-sessions + attached-projects stores. | src/host/agent-host.ts, src/agent-sessions.ts, src/attached-projects.ts, src/agent-daemon-client.ts | | host proxies + dev-server scan | Host-side helpers so a cross-origin tenant worker can reach local dev servers and same-origin APIs: /__server-scan discovers running metro/expo/vxrn/one servers; fetch + websocket proxies relay guest-app network through the daemon. | src/host/fetch-proxy-handler.ts, src/host/websocket-proxy.ts, scripts/dev-server-scanner.ts, src/dev-bundle-resolution.ts | | runtime delivery + rnx home | Versioned engine runtime management. The shared machinery owns manifest fetch, sha256 verification, channels, and auto-update. rnx binds it to https://contrast.dev and ~/.rnx/runtimes/<version>. A repo can select runtimeVersion without changing the machine default. | src/runtime-delivery.ts, packages/contrast-runtime-delivery/, src/home-paths.ts, src/runtime-assets.ts | | standalone CLI delivery | Cached stable-version checks, bounded interactive notices, and verified atomic executable replacement. | cli/cli-update.ts, cli/commands/upgrade.ts, cli/commands/version.ts, src/cli-version.ts | | rnxsim/vite + rnxsim/metro (runtime serving) | Published bundler plugins. Both serve the installed engine runtime at /__soot/ from ~/.rnx/runtimes/<version> so an app's own dev server can host the sim shell; the Vite plugin can opt into a named Electron window. | src/vite-plugin-one.ts, src/metro-plugin.ts, src/runtime-assets.ts | | sootsim() vite resolver plugin (internal) | The large RN-resolution / native-stub vite plugin: aliases react-native to the engine shim, native packages to @sootsim/compat stubs, applies worklets/babel transforms, and instantiates SootSimBridgeHost in its dev server. Distinct from the published rnxsim/vite export. | src/vite-plugin.ts, src/worklets-babel.ts, packages/compat/src/stub-manifest.ts | | skills registry | rnx agent skills (rnx-setup, rnx-debug, rnx-test, rnx-visual, and the generated contrast index) installable with rnx skill. | skills/*.md, src/skills/registry.ts, src/skills/types.ts |

Getting started

curl -fsSL https://rnxsim.com/install.sh | sh
rnx                 # open ConnectRN and choose a running app in the simulator
rnx open /settings  # dispatch a React Native deep link into that app

Start Metro, Expo, One, or another supported React Native development server the way you normally do, then run rnx from any directory. The simulator opens ConnectRN, which shows the available local apps and lets you connect one. Pass a target to rnx open <port-or-url> when a script or agent needs an explicit selection.

The first rnx open launches an isolated Chrome for Testing sim. The CLI resolves Playwright from the app or CLI install, asks that exact package for its required browser executable, and runs that package's installer once when the executable is absent. It never substitutes another revision found in the shared Playwright cache. Later opens reuse that sim and reload it at the requested target. Use rnx do reload when the target has not changed. Reserve --new for a genuinely concurrent sim; repeated new browser trees consume memory and CPU on shared machines.

The public installer places one standalone rnx executable in ~/.local/bin. The rnxsim npm package contains bundler plugins and library exports, not a CLI binary. Start your Metro, Expo, or One dev server the way you already do, then open it from the CLI. There is no iOS native build in the inner loop; Metro alone is enough. The manifest bundle path and query remain authoritative. When both the discovery request and manifest target are loopback addresses, RNX keeps the loopback host that answered discovery so an IPv6-only listener is not reopened through an unreachable IPv4 address. rnx open starts a local bridge when no daemon is reachable. The background service is strongly recommended for local agent work because inspect, interaction, and test commands reuse one ready bridge and runtime. Enable it at any time with rnx daemon install; it is never required in CI. The packaged Desktop app is optional and available through first-run onboarding or rnx desktop install. A downloaded app starts its own bundled daemon on first launch, then offers Install the rnx command over the running simulator. That action installs ~/.local/bin/rnx, updates shell startup, and hands the daemon to launchd or systemd without reloading the window. Windows keeps the desktop-owned daemon because it has no daemon service yet. Native Electron windows created by rnx open belong to that CLI session and close when the session exits; rnx desktop keeps the persistent desktop-app lifecycle. In Electron, File > New Window duplicates the focused simulator, while File > New Simulator > opens a new window for a selected device (same device list as the Window > menu).

Privacy

rnx sends no analytics, crash report, command event, app data, project data, or identity by default. An unsigned-in interactive run may request the runtime it is about to execute and the stable standalone CLI version document. The latter runs after the command in a detached process at most once every 20 hours and can be disabled with RNX_UPDATE_CHECK=off. The first human run asks once about bounded diagnostics, defaults to no, and never prompts in a non-TTY shell, CI, or an agent. An automated first run is declined for that process without consuming the later human choice. Legacy browser and Electron telemetry senders are removed rather than being enabled by this consent.

Opt-in diagnostics are limited to package name/version/unsupported API or error class. rnx never sends source, file paths, project names, app content, commands, identity, screenshots, or recordings as diagnostics. Cloud commands such as login, upload, billing, issue reporting, generated flows, and screenshot decks contact their documented service only when explicitly invoked. The complete enforced network contract is in specs/rnx-privacy.md.

rnx daemon uninstall removes the machine daemon: it stops current and legacy launchd / systemd services and removes their logs, launcher, and generated .app wrapper. ~/.rnx/ survives, because runtimes, device profiles and their app storage, and live dev-bridge records belong to simulators the user may still be running. rnx daemon uninstall --purge deletes ~/.rnx/ as well. Neither form removes the optional /Applications/rnx.app desktop bundle or the macOS preference plist. To inspect existing disk usage first, run rnx cleanup; add --apply only after reviewing the preview.

Jump to source in inspect mode

Inspect mode can open a selected React Native element in your editor when the bundle includes source metadata. Add the optional Babel plugin to your app's Metro/Babel config:

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

The plugin adds an srcloc="/absolute/path/App.tsx:12:3" prop to JSX elements outside node_modules, dist, and build. Keep it before react-native-worklets/plugin in a custom Babel stack that lists both plugins. Apps using babel-preset-expo omit the explicit Worklets plugin because the preset configures it automatically.

For One's Rolldown native bundler, use the native transform in vite.config.ts:

import { jumpToSourceNativePlugin } from 'rnxsim/jump-to-source-native'

one({
  native: {
    bundler: 'vite',
    bundlerOptions: {
      plugins: [jumpToSourceNativePlugin({ include: [import.meta.dirname] })],
    },
  },
})

This transform uses the same source props and filters without running Babel. For One's nativeTransformModules, export createJumpToSourceNativeTransform(options) from a module and pass its module id.

CLI

The CLI is the primary debugging surface for rnx — use it first for runtime inspection, interaction, animation debugging, shell tracing, screenshots, and flow capture, not just as a test runner.

rnx list              # connected tabs
rnx open 8081         # load a running metro/expo dev server
rnx open /settings    # route via React Native Linking
rnx describe          # dump UI tree
rnx get errors 5      # recent runtime failures
rnx compat            # scan native package compatibility
rnx report-issue "…"  # preview an opt-in compatibility report
rnx find --testid cta # inspect one node deeply
rnx debug enable animated,layout
rnx debug trace shell on 240
rnx do tap-text "..." # interact
rnx do tap email --then type [email protected] --then tap submit
rnx debug snapshot before
rnx debug snapshot after
rnx debug diff before after
rnx maestro start     # begin a Maestro draft
rnx maestro keep      # persist the last action
rnx maestro end --output .maestro/login.yaml --validate
rnx detox             # run Detox/Jest suites against rnx

See the full command reference via rnx --help or at src/features/site/docs/rnx/cli/ in the Contrast repo.

Sim-scoped commands use the primary fallback only when one driveable sim is connected. With multiple driveable sims, the bridge lists their ids and refuses to choose. Run rnx use <id> to pin later commands, or pass --sim <id> to target one command.

Use an inline rnx do chain for a short action sequence that should execute as one engine batch. Repeat --then before each additional action. Each phrase uses the same positional grammar as its standalone do command. Touch timing stays inside the sim, the batch stops at the first failure, and --json prints the complete per-step result. Reusable file-based flows stay in Maestro YAML.

rnx do tap email --then type [email protected] --then tap submit

Bundler plugins (rnxsim/vite and rnxsim/metro)

The Vite plugin serves the installed RNX runtime from your existing dev server.

// vite.config.ts
import { rnxPlugin } from 'rnxsim/vite'

export default {
  plugins: [rnxPlugin({ open: { appName: 'My App' } })],
}

// metro.config.js
const { getDefaultConfig } = require('expo/metro-config')
const { withRNX } = require('rnxsim/metro')

const config = getDefaultConfig(__dirname)

module.exports = withRNX(config)

rnx works directly with regular, unannotated Metro production JavaScript bundles out of the box. It identifies modules by matching package graph fingerprints against a separately updated, integrity-checked registry. Hermes bytecode is not a supported input; pass rnx the JavaScript bundle produced before Hermes compilation.

If an app has unusual dependencies or fingerprint inference fails, you can optionally wrap your Metro configuration with withRNX(config). It takes no options and enables two integrations:

1. Deterministic module identity: appends Metro's exact module identity map as a trailing globalThis.__sootsimModulePaths = { ... } footer to every bundle. Resolution, transforms, minification, and source maps stay the app's own, so the annotated bundle is the exact bundle you ship: the footer assigns one unused global on a device, and Hermes drops it during bytecode compilation.
2. In-browser dev shell: serves the rnx simulator shell at /__soot/ on the Metro dev server.

The URL helpers request ordinary Metro graphs: dev=false&minify=true for production and dev=true&minify=false for development.

const {
  toRNXProductionBundleUrl,
  toRNXDevelopmentBundleUrl,
} = require('rnxsim/metro')

const productionUrl = toRNXProductionBundleUrl(
  'http://localhost:8081/index.bundle?platform=ios',
)
const developmentUrl = toRNXDevelopmentBundleUrl(
  'http://localhost:8081/index.bundle?platform=ios',
)

Coming from Detox

rnx ships a drop-in Detox driver. Existing Detox test files (import { by, element, expect, device } from 'detox') run against rnx with no code changes — just add one line to your jest config:

// jest config
{ preset: 'rnxsim/detox/jest-preset' }

Or use the CLI directly:

rnx detox            # auto-discovers e2e/ tests and launches a shell
rnx detox init       # scaffold a config + sample test

See ../../docs/migrating-from-detox.md for details.

Coming from Maestro

Maestro is rnx's single YAML test surface. Point it at your existing .maestro/ directory, generate a test, or author one from live actions:

rnx maestro                      # discover .maestro/ and run all flows
rnx maestro test .maestro/       # explicit
rnx maestro generate "verify login"
rnx maestro --list-compat        # see the verb support matrix

Most Maestro verbs work out of the box (tapOn, assertVisible, inputText, scrollUntilVisible, launchApp, when:, repeat, runFlow, …). Verbs that need real device hardware (GPS, radio, photo library) throw a clear error. See ../../docs/migrating-from-maestro.md for the full compat matrix.

Screenshots and recordings

For animation-heavy debugging, the useful path is usually:

rnx debug enable animated
rnx debug trace shell on 240
rnx debug snapshot before
# reproduce the transition
rnx debug snapshot after
rnx debug diff before after
rnx screenshot --with-frame --output /tmp/rnx-framed.png
rnx record --duration 5 --output /tmp/rnx-anim.mp4

rnx screenshot --with-frame composes the real rnx shell device chrome around the raw screen bitmap (reusing the shell bezel/button geometry, excluding the Electron top bar, rail gutter, and other window chrome). Flows can request the framed export inline without changing Maestro syntax:

rnx wait ready and the screenshot readiness guard accept inspectable native content, a populated node tree, or a live-frame channel whose publish count advances across probes. Canvas-only GL, WebGPU, and video surfaces can therefore prove that they are painting without weakening the boot-card guard.

- takeScreenshot: hero
- takeScreenshot:
    path: marketing/hero
    withFrame: true

For plan-driven app-store exports, use rnx screenshot appstore:

app: 8081
device: iphone-16

capture:
  flow: .maestro/capture-app-store-screenshots.yaml
  mode: raw+framed

compose:
  canvases: [iphone-6-9, iphone-6-1]
  background: cyan
  text:
    preset: bold-top
  slides:
    - id: splash-hero
      screenshot: apple/iphone/en/01-splash.png
      headline: First punch.
      subheadline: Every pick in one place.

rnx screenshot appstore --plan .rnx/app-store.yaml

The plan runner can reuse a visible sim for capture (--sim a9), stop after raw/framed intermediates (--capture-only), or rerender final marketing canvases from an existing raw directory (--compose-only). If your flow already writes screenshots to explicit project paths, set from: + pathMode: flow so rnx screenshot appstore respects the flow's own takeScreenshot paths instead of prepending --screenshots <rawDir>:

capture:
  flow: .maestro/capture-app-store-screenshots.yaml
  from: ./apps/app-store-screenshots/public/screenshots/apple/iphone/en
  pathMode: flow

In the browser shell, Screenshot Mode turns the live shell into a simple DOM composition surface: the rail + mac menu bar disappear, the device shifts down with a short transition, and editable title/subtitle fields appear above the frame for quick art-direction passes.

Skills registry

rnx skill install installs rnx agent skills in the standard <skill-name>/SKILL.md layout used by Codex and Claude Code. The bundled skills cover setup, debugging/perf/accessibility, testing, visual review, and the generated contrast command index. The published CLI registry and generated website docs both come from packages/rnx-skills/:

• packages/sootsim/skills/contrast/SKILL.md is generated from that registry
• src/features/site/docs/rnx/cli/* is generated output, not hand-edited

When command docs or examples drift, update packages/rnx-skills/ and run:

bun run generate:sootsim-docs

Runtime delivery (the rnx home and CDN)

The engine never ships inside this package. runtime-delivery.ts names rnx's CDN origin (default https://contrast.dev, overridable in config.json), its SOOTSIM_* env overrides, and its hosted paths, then hands them to the shared delivery machinery in @contrast/runtime-delivery — an internal workspace package the CLI bundles, so a published install has it inlined. That machinery fetches runtimes/manifest.json + the runtime tarball, verifies its sha256, and unpacks it under ~/.rnx:

~/.rnx/
├── runtimes/
│   ├── <active>/         unpacked engine assets (served at /__soot/)
│   └── <rollback>/       previous version for rollback
├── cache/                legacy downloads; empty after cleanup
├── profiles/             persistent named app storage, without browser caches
├── electron/userData/    desktop app storage, with bounded browser caches
├── daemon.json           lockfile: pid, ports, active runtime, heartbeat
├── cli-update.json       cached standalone CLI version and notice state
├── automatic-cleanup-v1.json  completed legacy cleanup generation
└── config.json           user prefs: update channel, cdn origin override

The bridge daemon serves these assets over HTTP and exposes a self-update route; rnx upgrade / rnx runtime drive explicit version changes from the CLI side. Installation retains the active runtime plus one rollback and removes the downloaded archive after extraction. Disposable Playwright caches live in a bounded per-session temporary directory; Electron's persistent HTTP cache is disabled for simulator profiles and globally capped for app chrome. Cookies, localStorage, IndexedDB, service workers, recordings, and captured frames are user-owned data and are not removed by the default cleanup command.

Per-repo configuration is optional. Every installed-runtime rnx open serves its selected version from a version-specific localhost origin, so a background activation cannot mix an already loaded shell with chunks from the next runtime. Without config, each new open selects the active stable version. When rnx.config.ts sets runtimeVersion, rnx open installs that version without changing the machine default. App config, native-linked fonts, and splash assets all resolve from the project root advertised by the selected development server. Bare Metro, which has no Expo manifest project root, uses the listening development process's cwd inside that same resolver. The invoking CLI's cwd is never an asset/config fallback. Asset wires stay on each opened project URL, so one daemon can serve several attached projects without sharing font or splash state between them.

The first interactive CLI command after this cleanup generation finishes its requested work, then launches the same safe default plan in a detached maintenance process. The app and terminal command are usable before the legacy filesystem scan begins. The worker prints the reclaimed size to stderr, records completion, and does not run the scan again. Open browser profiles and a runtime served by a live daemon or development bridge are left untouched. The automatic pass retries on a later command after they close. The explicit rnx cleanup --aggressive command remains the only path that removes the rollback runtime or user-created recordings.

Development and building

This package is part of the Contrast monorepo. To build the standalone executable for the current platform:

bun run build:cli-binary

The output is dist-bin/rnx-<platform>-<arch>. dist-cli/bin.js remains a repository build artifact for tests and internal tooling and is not published as an npm executable. Library exports build to dist-lib/ (consumed via the exports map: ., ./vite, ./metro, ./sdk, ./skills, ./detox, and the host/agent helpers). bun run pack:smoke validates the publishable tarball.