Installation

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

curl -fsSL https://sootsim.com/install.sh | sh

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. Installs the background daemon through launchd on macOS or systemd on Linux. The daemon keeps the bridge alive so open, describe, do, flows, screenshots, and agent commands do not need to spin up a server each time, and it keeps the engine runtime up to date in the background.
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 what you are running, and sootsim runtime manages installed runtime versions (list, pin, switch). See the changelog for what’s new.

#Open an app

Start your app’s dev server normally:

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.

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

sootsim open

#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-reanimated/plugin',
]

The plugin adds an srcloc prop to JSX elements outside node_modules, dist, and build. If your app uses Reanimated, keep sootsim/jump-to-source-babel before react-native-reanimated/plugin.

#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 install and no MCP server to configure. Any agent that can run shell commands uses sootsim directly after the global install, with multi-agent claim leases and the bridge daemon installed by guided setup.

sootsim
npx skills add tamagui/soot --skill sootsim-debug   # optional: teach the agent

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.