Quickstart — end to end

You shipped it. This walkthrough takes you from a fresh account to a real bug Opsis caught in your users' sessions, proved on video, fixed, and re-verified — before your users hit it. Each step links to the deeper reference page when you want more detail.

1. Create your account

   Sign up with email and password (at least 8 characters), or continue with Google or GitHub. Social sign-ins land you in the app immediately; email signups get a confirmation email — clicking the link signs you in and drops you straight on the connect screen.

2. Connect PostHog — or try the sample project first

   Choose PostHog and click Connect your project. You authorize Opsis on PostHog's side via OAuth with read-only scopes — there are no API keys, project IDs, or host URLs to copy, and Opsis never sees your PostHog password. If your PostHog account has several projects, pick the one to analyze.

   Not ready to connect? Choose Try a sample project on the connect screen — it runs the full loop on fixture data, including real Playwright proof, so you can see findings and evidence before wiring up your own app. Details: PostHog Integration.

3. If your app doesn't run PostHog yet: install posthog-js

   Opsis analyzes PostHog session replays, so your app needs posthog-js with session recording enabled:

   npm install posthog-js

   Copy

   import posthog from "posthog-js";
   
   posthog.init("phc_xxxxx", {              // your PostHog project API key
     api_host: "https://us.i.posthog.com",  // or your PostHog region/host
     session_recording: {
       maskAllInputs: true,                 // recommended: mask user input
     },
     enable_recording_console_log: true,    // console errors as bug evidence
     capture_exceptions: true,              // uncaught errors as bug evidence
   });

   Copy

   Then enable Record user sessions in PostHog (Settings → Session replay) and generate a few real visits — your own clicks around the deployed app are enough. Recordings can take a few minutes to show up in PostHog.

4. Run your first scan

   Opsis imports your recent replays automatically right after you connect; after that, Scan now on the project overview runs the same loop on demand. One scan does three things:

   • Import — session metadata and events (pageviews, rage clicks, dead clicks, exceptions) are pulled from PostHog, with all text redacted before storage.
   • Analysis — deterministic signal detection flags suspicious sessions (console errors, failed requests, rage/dead clicks, abandonment), then AI analyzes the suspicious ones and clusters them into findings. Every session is labeled honestly: AI analysis or Rule-based analysis, so you always know which engine produced it.
   • Automatic Playwright proof — the scan attempts to reproduce the top eligible findings in a real browser straight away, so high-severity bugs arrive with video evidence attached.

5. Read a finding

   Each finding shows its severity, category, and status, a plain-language summary with business impact, the affected routes, and the evidence: proof video, trace, screenshot, and redacted console/network logs when Playwright reproduced the bug. The suspected and verified statuses are strictly separated — verified always means Playwright evidence exists.

   Affected sessions are listed with pseudonymous user IDs by design: PostHog distinct_ids are hashed before storage, so the dashboard never shows end-user identities. See Privacy & Redaction.

6. Set your App URL in Settings

   Playwright proof runs interact with your app at the project's App URL (Settings → Project). Point it at a staging environment if you don't want synthetic interactions on production — verification fills forms with synthetic test data and clicks real elements.

7. Fix & verify loop

   Every finding ships a full report with a guard-railed fix. Click Copy report, paste it into Claude Code, Cursor, or Lovable, deploy the fix, then click Re-run verification on the finding.

8. Pre-deploy checks via MCP — for your next release

   Once the loop is running post-deploy, close it pre-deploy too: connect the Opsis MCP server to your coding agent and prove your critical flows before shipping the next release. Open your project's Before Ship tab, expand “Run the check on your machine with your coding agent”, and reveal your project's opk_… key — it authorizes only this project's launch-report API, never your PostHog data.

   Add the server to Claude Code in one command (the Before Ship tab shows the same snippet pre-filled with your project's values):

   claude mcp add opsis \
     -e OPSIS_APP_URL=https://<your-opsis-domain> \
     -e OPSIS_PROJECT_ID=prj_xxxxxxxx \
     -e OPSIS_MCP_KEY=opk_xxxxxxxx \
     -- npx -y opsis-mcp

   Copy

   Full setup and how the launch verdict works: Pre-deploy Checks (MCP).

9. Choose your scan cadence

   Manual Scan now always works — every scan is recorded in the project's history either way. The pipeline stage reads Monitoring · Scheduled only when the operator has genuinely enabled scheduled scans on the deployment; otherwise it honestly says On-demand scans · Manual.

   Email digests are controlled per project (Settings → Notifications): one digest per scan, and a finding is never emailed twice. Details: Scans & Retention.

Where to next

• Scans & Retention — manual vs scheduled scans, digests, and how long evidence is kept.
• Playwright Proof — what a verification run records and what each run status means.
• Privacy & Redaction — what is redacted, hashed, and when artifacts expire.