Docs

Quickstart: Sypnia Cloud

From nothing to your first session and your first problem on Sypnia Cloud, in five steps and about ten minutes.

Applies to Cloud At launch

View as Markdown
On this page
  1. Create a project
  2. Add the SDK to your app
  3. Open your app and check that it sends
  4. See your first session
  5. Cause your first problem
  6. What you have now
  7. Do these next

Cloud This page is for anyone with a web app and no Sypnia yet. It uses Sypnia Cloud, where we run the engine for you: there is nothing to deploy. To run the engine yourself, use the self-host quickstart instead; the snippet in your app is the same.

At the end you will have: your app sending to Sypnia, your own visit listed as a session, and one problem that you caused on purpose.

You need: a web app you can edit and run, and about ten minutes. The free tier is enough.

  1. Create a project

    Open https://app.sypnia.com, create an account, and create a project. Name it after your app; the examples here use Shop.

    You should see
    The project’s page shows its ingest key, which starts with spk_, and says it is waiting for the first event. Keep the page open.

    The ingest key is public. It can only send data to this project, so it is safe in your app’s code.

  2. Add the SDK to your app

    npm

    npm install @sypnia/browser
    import { init } from '@sypnia/browser';
    
    init({ project: 'YOUR_PROJECT_KEY' });

    Put the init call where your app starts, before it renders: src/main.ts, src/main.tsx, src/index.js. Then replace it with this fuller version, with your own key:

    src/main.ts
    import { init } from '@sypnia/browser';
    
    init({
      project: 'spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e',
      environment: location.hostname === 'localhost' ? 'development' : 'production',
    });

    The environment line keeps your own testing apart from your customers: on your machine the app reports as development, everywhere else as production. Alerts are only sent for production.

    Using Next.js? Follow Next.js for this step and come back. Using an AI app builder? See Lovable, Bolt, v0 and Replit.

    You should see
    Your app builds and runs as before. Nothing looks different.
  3. Open your app and check that it sends

    Run your app, open it in a browser, and click on a few things. Open the browser’s developer tools, tab Network, and type ingest in the filter.

    You should see
    Within 10 seconds, a POST request to https://ingest.sypnia.com/v1/ingest/events with status 200. Its answer looks like {"accepted": 5, "dropped": 0}.

    If there is no request, or it is red, go to Troubleshooting.

  4. See your first session

    Go back to Sypnia and open Sessions. Choose the environment development.

    You should see
    Within 10 minutes, one session: yours. It lists the pages you opened and what you clicked, in words: «Clicked Add to cart».

    The session is anonymous: Sypnia does not know who you are until your app says so. That is one more line, in Identifying people.

  5. Cause your first problem

    Add one line after init, save, and reload your app once:

    src/main.ts
    import { init, reportError } from '@sypnia/browser';
    
    init({
      project: 'spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e',
      environment: location.hostname === 'localhost' ? 'development' : 'production',
    });
    
    reportError(new Error('Sypnia test: the cart total is missing'));

    Then open Problems in Sypnia, in the environment development.

    You should see
    Within 2 minutes, one new problem. Its first title is the technical one, Error: Sypnia test: the cart total is missing. A moment later the agent replaces it with a sentence in plain words and says who it hit (1 person), since when, and where in your code.

    Remove the line again. In real use you never call reportError for this: errors nobody caught are reported by themselves.

What you have now

  • Every visit to your app is a session, with its pages and clicks.
  • Errors, slow pages, slow and failing API calls, and rage and dead clicks are captured without more code.
  • Sessions where something goes wrong are recorded, with everything a person types masked.
  • Problems arrive as sentences, with the prompt for your coding agent.

Do these next

To getDo
The whole loop once, with a rage click, a replay and the fixYour first problem
«Since yesterday’s change», and your own file names in stacksSet release and upload source maps: Source maps in CI
«3 people», with their namesIdentifying people
The request followed into your backendNode, Next.js or OpenTelemetry
Your coding agent reading problems by itselfInstall with your coding agent
To know what is sent and what never isPrivacy and masking

When you deploy, your app reports as production and Sypnia starts sending alerts and the daily summary by e-mail.

Sections

Start hereWhat Sypnia is, how it works, what is open source and what is the paid cloud, and the two ways to get your first problem in plain words.ConceptsThe ten ideas Sypnia is made of, each defined precisely, from a project and its keys to problems, traces and alerts.SDKsHow your app sends data to Sypnia. One SDK for the browser, one for Node, one for Next.js, and the OpenTelemetry intake for every other backend.The agentHow Sypnia analyses a problem, what it writes, what it sends to a model and what it never does.MCP and skillsConnect your coding agent to Sypnia so it can ask what is failing in production, read what it needs to fix it, and set Sypnia up for you.API referenceThe Sypnia HTTP API: one API for the open-source engine and for Sypnia Cloud, with every endpoint, parameter, response and error.CLI referenceThe sypnia command: how to install it, the variables it reads, what its exit codes mean, and where each command is documented.Self-hostingWhat you run when you host the Sypnia engine yourself, what you need, what it costs, and what you do not get compared with Sypnia Cloud.How the engine is builtThe whole Sypnia engine on one page, from a click in your app to the sentence your coding agent reads, with the design rules and the code that holds them.Sypnia CloudHow the paid service works, from organizations and roles to plans, limits, billing, where your data lives, the GitHub App and support.Privacy and securityWhat Sypnia collects from your app and its users, what it never collects, how masking works, how to delete data, and how the service is protected.LicensingWhich licence covers each part of Sypnia, what you may do with it, how the name may be used, and the terms of a contribution.GuidesStep-by-step recipes for the common ways to use Sypnia, from apps made with AI builders and Next.js on Vercel to Supabase, source maps in CI, alert e-mails from your own engine, and moving from Sentry.ReferenceThe pages you look things up in, from the event schema and the glossary to what is planned, the changelog and the common questions.
↑↓ to move↵ to openEsc to close