Quick Start

#Install SootSim

The public script installs the CLI, engine runtime, and background daemon without sudo or changes to your app. The daemon keeps the bridge running so every later CLI command is much faster.

See Installation to read the script and for the manual npm, bun, or pnpm install followed by sootsim setup.

#Open the simulator

From your app project root, start its Metro, Expo, React Native, or One server with the command you already use. SootSim does not start or replace that server. Then, from the same directory, open it in SootSim:

sootsim open 8081

If you omit the port, sootsim open scans for available React Native dev servers and lets you pick one.

No per-app install is needed, and no iOS native build is needed. Metro, Expo, or One running locally is enough. Running open from the project root is recommended because the directory is SootSim’s fallback for discovering custom fonts, splash screens, and other app configuration. The command can still load the bundle when you run it elsewhere, but those project details may be missing.

If no bridge is running, sootsim open starts the lightweight local HTTP and WebSocket bridge as needed. The installer registers the same bridge as a background daemon for faster local reuse. It serves the simulator at http://localhost:7668/ by default, and you can load that URL in any browser. The registered daemon is optional and is not needed in CI.

The desktop app is optional. If it is installed, open prefers it; otherwise SootSim opens in your default browser.

Run sootsim --help to get an overview of common commands.

Install the bundled agent skills with sootsim skill install, then restart the agent session so it discovers them. The copied setup prompt also scans package compatibility and, when it finds a concrete gap, offers to send an explicitly approved sootsim report-issue with the scan attached.

#Run a Maestro test

Create .maestro/smoke.yaml:

- launchApp: {}
- waitFor:
    text: 'Welcome'
    timeout: 10000
- tapOn: 'Get Started'
- assertVisible: 'Home'
- takeScreenshot: home

Run it with:

sootsim maestro test .maestro/smoke.yaml

Want a shareable cloud preview? Sign in once, then run the flow with --preview. It records the run, uploads it, and prints a shareable /preview/<id> link (--preview-open also opens it in your browser):

sootsim login
sootsim maestro test .maestro/smoke.yaml --preview --preview-open

#Next

• Your First Test covers Maestro and Detox side by side.
• Testing takes the same flow through CI and hosted results.
• Contrast quick start shows the browser workspace that uses SootSim for every native preview.