Preview uploads & sharing

sootsim maestro test --preview, sootsim record --mode combined, and sootsim record upload publish the bundle running in your sim to a shareable /preview/<id> link. Anyone with the URL can open a live interactive copy of the app in their browser, alongside an inline <video> of whatever sim run you recorded.

Use cases:

• PRs: attach a playable demo to every pull request
• Designers / PMs / clients: hand someone a link; no TestFlight, no dev build, no Xcode
• Sales demos, bug repros, onboarding walkthroughs: embed the same link anywhere an iframe fits
• Support: ask a user to record their flow; get back a link that replays the exact state

#One-off: upload the current sim

sootsim login                           # first time only
sootsim record upload --open

--open launches the resulting /preview/<id> URL in your browser after upload.

#The three one-shot flows

#1. Record + share in one command

sootsim record --mode combined --duration 8 --open

Captures video and the event stream simultaneously, uploads to a /preview/<id> link, copies the URL to your clipboard, and animates the Dynamic Island while uploading.

#2. Record a flow file + share

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

--preview implies --record, captures the event stream, and chains into upload automatically. Prints the /preview/<id> URL when done. Add --preview-open to open it.

#3. Upload an existing recording

sootsim record upload --video /tmp/demo.mp4 --events /tmp/demo-events.jsonl.gz --open

Attach an existing mp4 or gif recording and a gzipped event stream. Useful when you already have assets from a CI run or scripted harness.

#Auth

Uploads require a signed-in desktop session:

sootsim login            # sign in to the upload host
sootsim auth             # print which auth source is active
sootsim logout           # clear the local session

By default, uploads target localhost:3000 if available, otherwise sootbean.com. Override with --origin or SOOTSIM_UPLOAD_ORIGIN.

#What the preview page does

• Live interactive app: the real bundle boots clientside on the visitor’s GPU via WebAssembly CanvasKit. No server-rendered frames, no streaming latency.
• Inline video: the recording plays overlaid on the app surface; scrub the timeline to watch the recorded flow, then tap anywhere to take control.
• Forward scrub: drag the scrubber forward to jump to any point in the recorded session; the live app catches up.
• Resume live: at any point, tap the app to exit playback and drive it live from the current state.
• URL params: device, theme, network condition, language, and region all controlled by query string.

#GitHub integration

sootsim record upload is the manual upload path behind sticky PR comments:

• A CI job runs the flow, captures video + events, and calls sootsim record upload --video ... --events ...
• The upload endpoint posts back a sticky comment on the PR with a two-state <video> (generating → ready) and a /preview/<id> link.
• Reviewers play the video inline in the PR, click through to the live app, and drive it themselves.

This is the integration surface sootsim maestro test --preview is built for.

For the managed SootSim GitHub App, the repo uses the generated Soot workflow instead of storing SOOTSIM_API_KEY. That pipeline creates recorded PR previews and separate live branch builds. Pipeline failures fail the workflow; after it is green, verify the sticky comment and open the linked preview before treating the rendered result as ready. See GitHub PR Previews.

#Flags you’ll want to know

#Related

• sootsim record: recording and upload modes
• sootsim maestro: Maestro runner + --preview
• GitHub PR Previews: managed PR preview and branch build lane
• Agents › CLI Use: agent-driven previews