Quickstart
Three ways in, smallest first
Add the SDK to your app with npm alone. Prove the whole loop offline with Node and Python. Or run the full host and watch a submitted trace become a Playwright repro and a confirmed fix. Each path states its real prerequisites, and every command works in the order shown.
Add the SDK to your app
Needs Node and npm. Nothing else.
The zero-dependency tracker goes into the app whose bugs you want reproduced. Capture is off until a user consents.
- 1
Install the tracker
One package, no transitive dependencies, works from both ESM and CommonJS. Consent is off by default: until your app calls grantConsent(), nothing is observed and nothing is sent.
npm install @stepstitch/tracker
Prove the loop offline
Needs Git, Node 20+, and Python 3.10+. Nothing leaves your machine.
The demo imports the real service modules for scrubbing, scoring, compiling, and verdicts. Python and the service package are therefore genuine prerequisites, and installing them is part of the sequence.
- 2
Clone, install the service, run the demo
Runs the real pipeline end to end (report → scrub → score → Playwright → verdict) with no database, no network and no credentials, then asserts no forbidden field or value survived the scrub. The venv keeps the service install disposable.
git clone https://github.com/CyKiller/stepstitch.git cd stepstitch python3 -m venv .venv source .venv/bin/activate pip install ./service npm run demo npm run smokeWindows (PowerShell): activate with .venv\Scripts\Activate.ps1. Deterministic: re-running writes an identical demo/evidence-bundle.json.
Run the full host
Needs Docker. (Prefer no Docker? The manual path below needs Python 3.10+ and a Postgres you provide.)
One command brings up Postgres and the ingest host with throwaway dev tokens. From there you seed a trace, check the install, point reproductions at your app, and close the loop from CI.
- 3
Bring up Postgres and the host
-d returns your terminal once the containers are up (follow logs with docker compose logs -f stepstitch). Then open http://localhost:8000/dashboard and paste dev-admin when the console asks for a token. These are throwaway development credentials and must never be used in production.
docker compose up --build -d - 4
Seed a demo trace
Submits one realistic, already-structural trace (transfer → 500). The script needs both variables: it refuses to guess where your host is or what its ingest token might be.
STEPSTITCH_BASE_URL=http://localhost:8000 STEPSTITCH_INGEST_TOKEN=dev-ingest \ node scripts/seed-demo-trace.mjs - 5
Check the install where the configuration lives
doctor walks the whole chain, including the environment, host, database, both tokens, capture policy, and reproduction settings, and names the fix for anything broken. It reads configuration from its own environment, so with Compose it must run inside the container; on your host shell it would truthfully report the variables missing. It never prints a secret value. (-T skips TTY allocation, so this exact line also works from scripts and CI.)
docker compose exec -T stepstitch stepstitch doctor - 6
No Docker? Terminal 1: run the host
macOS/Linux; on Windows use the Docker path above. Install the service and the host's requirements before uvicorn ever starts, and export the configuration first. STEPSTITCH_APP_BASE_URL is where generated reproductions will point: set it to your staging app now, or every repro targets localhost:3000 until you configure it. uvicorn runs in the foreground: leave this terminal open.
python3 -m venv .venv && source .venv/bin/activate pip install ./service pip install -r server/requirements.txt export DATABASE_URL=postgres://localhost/stepstitch export STEPSTITCH_INGEST_TOKEN=dev-ingest export STEPSTITCH_ADMIN_TOKEN=dev-admin export STEPSTITCH_APP_BASE_URL=https://staging.your-app.example uvicorn server.app:app --port 8000 - 7
Terminal 2: check it with doctor
A second terminal, because uvicorn owns the first. A fresh shell has neither the venv nor your exports, and doctor reads configuration only from its own environment, so activate and export again before running it.
source .venv/bin/activate export DATABASE_URL=postgres://localhost/stepstitch export STEPSTITCH_INGEST_TOKEN=dev-ingest export STEPSTITCH_ADMIN_TOKEN=dev-admin export STEPSTITCH_APP_BASE_URL=https://staging.your-app.example stepstitch doctor - 8
Point reproductions at your app, then generate one
A trace knows the route template, not your hostname, and never recorded what was typed. Supply the rest once and every generated test carries a READY / NEEDS-CONFIG checklist naming anything still missing. Configuration stores env var names, never credentials.
curl -X PUT -H "Authorization: Bearer $STEPSTITCH_ADMIN_TOKEN" \ -H 'Content-Type: application/json' \ -d '{"config":{"base_url":"https://staging.your-app.example","route_params":{"id":"1001"}}}' \ http://localhost:8000/admin/config/repro curl -H "Authorization: Bearer $STEPSTITCH_ADMIN_TOKEN" \ http://localhost:8000/api/stepstitch/v1/session/<trace_id>/playwright - 9
Close the loop from CI
Your CI runs the reproduction on the buggy commit and again on the fix, then posts both measured outcomes. confirmed_fixed means StepStitch actually observed the test fail and then pass: if either run does not complete, nothing is recorded. Issue CI a verify-scoped token from the console's Agents tab; it never needs your admin token.
# the shipped workflow does this for you: .github/workflows/stepstitch-repro.yml # red -> checkout the pre-fix ref, run the repro, expect FAIL # green -> checkout the fix, run the repro, expect PASS curl -X POST -H "Authorization: Bearer $STEPSTITCH_VERIFY_TOKEN" \ -H 'Content-Type: application/json' \ -d '{"pre_passed": false, "post_passed": true, "fix_ref": "PR #482"}' \ http://localhost:8000/api/stepstitch/v1/session/<trace_id>/verify # -> confirmed_fixed