Installation

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

Read the complete script before running it.

#What the installer does

1. Installs the sootsim CLI from npm into the user-owned ~/.local prefix. It never uses sudo and never changes the current project.
2. Downloads and verifies the engine runtime (the simulator UI, ~20MB) into ~/.sootsim/runtimes/. The CLI on npm is a thin client; the runtime is versioned and updated separately so fixes reach you without reinstalling the CLI.
3. Registers the background daemon through launchd on macOS or systemd on Linux. It keeps the lightweight local bridge ready between commands and keeps the engine runtime current. The daemon registration is recommended for local development, but it is optional. sootsim open starts the same bridge when one is not already running.
4. Adds ~/.local/bin to your shell PATH when necessary. Set SOOTSIM_NO_MODIFY_PATH=1 to skip that change.

#Prefer explicit steps or another package manager?

The installer is only a convenience layer over the supported CLI commands:

npm install --global sootsim
# or: bun add --global sootsim
# or: pnpm add --global sootsim

sootsim setup

To remove the daemon, cached runtimes, and an installer-managed CLI:

sootsim daemon uninstall
npm uninstall --global --prefix "$HOME/.local" sootsim

#Updates

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

sootsim upgrade

sootsim version shows the CLI, default engine runtime, and any repo-selected runtime. sootsim 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:

sootsim open 8081

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

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

If you omit the port, SootSim scans for local React Native dev servers and lets you pick one:

sootsim open

#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; sootsim 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. Registering it as an operating-system daemon is optional. Local development benefits from the always-ready daemon; 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:

npm install --global sootsim
npx playwright install chromium
sootsim open 8081 --driver playwright --headless --no-describe
sootsim maestro test .maestro/

See Tests in CI for a complete workflow.

#Setup

You can re-run guided setup any time:

sootsim setup
sootsim setup --dry-run

Use --app <dir> when you want setup to inspect a specific repo for package manager and Node-version guidance:

sootsim 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: [
  [
    'sootsim/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 sootsim/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. It gives you a more simulator-like shell on top of the same SootSim runtime and works on macOS, Windows, and Linux.

#Agentic use

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

sootsim skill install

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.