Docs

Quickstart: self-host

Run the open-source Sypnia engine on your own machine with Docker, create a project, and see your first session and your first problem.

Applies to Engine At launch

View as Markdown
On this page
  1. Write the Compose file
  2. Start it
  3. Check the setup
  4. Create a project and a token
  5. Add the SDK to your app
  6. Open your app and check that it sends
  7. Cause your first problem, and see it
  8. What you have, and what you do not
  9. Do these next

Engine This page is for anyone who wants to run Sypnia themselves. It starts the open-source engine on your own machine with Docker, next to its database and its storage, so you can try the whole thing before you choose where it will live. If you would rather not run servers, use the Sypnia Cloud quickstart; the snippet in your app is the same.

At the end you will have: the engine running at http://localhost:8080, a project with its keys, your app sending to it, and your first session and problem in the Console.

You need: Docker with Compose, a web app you can edit and run on the same machine, and about fifteen minutes.

  1. Write the Compose file

    In an empty folder, create this file. It starts three things: the engine, a Postgres for the numbers, and MinIO as the S3-compatible bucket for raw events and recordings.

    compose.yaml
    services:
      sypnia:
        image: ghcr.io/sypnia/sypnia:1
        ports: ["8080:8080"]
        environment:
          SYPNIA_BASE_URL: http://localhost:8080
          SYPNIA_ROOT_TOKEN: change-me-to-a-long-random-string
          SYPNIA_AUTO_MIGRATE: "true"
          SYPNIA_DATABASE_URL: postgres://sypnia:sypnia@db:5432/sypnia
          SYPNIA_STORAGE_BUCKET: sypnia
          SYPNIA_STORAGE_ENDPOINT: http://minio:9000
          SYPNIA_STORAGE_PUBLIC_ENDPOINT: http://localhost:9000
          SYPNIA_STORAGE_PATH_STYLE: "true"
          SYPNIA_STORAGE_ACCESS_KEY_ID: sypnia
          SYPNIA_STORAGE_SECRET_ACCESS_KEY: sypnia-secret
        depends_on:
          db: { condition: service_healthy }
          bucket: { condition: service_completed_successfully }
    
      db:
        image: postgres:16
        environment:
          POSTGRES_USER: sypnia
          POSTGRES_PASSWORD: sypnia
          POSTGRES_DB: sypnia
        volumes: ["db:/var/lib/postgresql/data"]
        healthcheck:
          test: ["CMD-SHELL", "pg_isready -U sypnia"]
          interval: 2s
          retries: 30
    
      minio:
        image: minio/minio
        command: server /data
        ports: ["9000:9000"]
        environment:
          MINIO_ROOT_USER: sypnia
          MINIO_ROOT_PASSWORD: sypnia-secret
        volumes: ["bucket:/data"]
    
      bucket:
        image: minio/mc
        depends_on: [minio]
        entrypoint: >
          sh -c "until mc alias set local http://minio:9000 sypnia sypnia-secret; do sleep 1; done;
                 mc mb --ignore-existing local/sypnia"
    
    volumes:
      db:
      bucket:

    Every SYPNIA_… line is a setting of the engine, explained in the configuration reference. The engine needs nothing else: no queue, no cache, no search server.

  2. Start it

    Terminal
    docker compose up -d
    curl -i http://localhost:8080/healthz
    You should see
    HTTP/1.1 200 OK. The first start takes up to a minute while the images download and the engine creates its tables.
  3. Check the setup

    Terminal
    docker compose exec sypnia sypnia doctor --skip ai
    You should see
    Text
    config    ok    10 settings read, 0 unknown
    database  ok    postgres 16.4, schema 12 (up to date), 2 ms
    storage   ok    s3://sypnia: put, get, delete, presign
    address   ok    http://localhost:8080/healthz answered 200
    webhook   skip  SYPNIA_ALERT_WEBHOOK_URL is not set (alerts are recorded only)
    clock     ok    0.1 s from the database's clock
    all checks passed

    A line that says FAIL names the setting to change. The AI check is skipped because no model key is set yet: the engine works without one, and problems then keep their technical title. Connecting a model is in Models and what is sent.

  4. Create a project and a token

    Terminal
    docker compose exec sypnia sypnia project create --name Shop
    You should see
    Text
    project     shop (prj_5k2m9x4q7w1z)
    ingest key  spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e
    
    Put the ingest key in your app. It is public: it can only send.
    Next: sypnia token create --project shop --name "My laptop" --scopes read,replay

    The ingest key goes into your app. To read what arrives you need an API token:

    Terminal
    docker compose exec sypnia sypnia token create --project shop --name "My laptop" --scopes read,replay
    You should see
    A line that starts with sps_. It is shown once: copy it now. It is a secret.
  5. 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. Use your own ingest key, and point the SDK at your engine with endpoint:

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

    With the script tag instead, load it from your engine: src="http://localhost:8080/v1/sdk.js" and data-endpoint="http://localhost:8080".

    endpoint is the only difference from Sypnia Cloud. The SDK is the same package.

  6. Open your app and check that it sends

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

    You should see
    Within 10 seconds, a POST to http://localhost:8080/v1/ingest/events with status 200 and an answer like {"accepted": 5, "dropped": 0}.
  7. Cause your first problem, and see it

    Add one line after init, save, and reload your app once. Then remove it.

    src/main.ts
    import { init, reportError } from '@sypnia/browser';
    
    // after init({ … })
    reportError(new Error('Sypnia test: the cart total is missing'));

    Open the Console at http://localhost:8080/console, paste your API token, and choose the environment development.

    You should see
    Within 2 minutes, one problem: Error: Sypnia test: the cart total is missing, 1 person, 1 occurrence. Within 10 minutes, your session, with the pages you opened and what you clicked. Once the session has been idle for 2 minutes, its replay plays in the Console: the error started the recording.

    The same from the command line:

    Terminal
    docker compose exec -e SYPNIA_API_TOKEN=<your sps_ token> sypnia sypnia problems --environment development

What you have, and what you do not

The Sypnia engine and Sypnia Cloud compared
Sypnia engineOpen source, self-hostedSypnia CloudPaid service, with a free tier
Receiving, storing, grouping into problems, sessions, replaysRunning on your machine.The same engine, run by us.
Where you read itThe Console (problems and replays), the API, the CLI and the MCP server.The full app.
The sentence in plain words and the promptAfter you set your own model key.Included.
AlertsRecorded, and sent to a webhook if you set one. No e-mail in the default deployment.E-mail and in the app.
Pull requestsNot in the engine. Use the prompt or MCP with your own coding agent.Opened by the Sypnia GitHub App.

The whole comparison is in Open source and Sypnia Cloud.

Do these next

To getDo
A deployment that others can reach, with HTTPSDeploy with Docker or Deploy on AWS
The sentence in plain wordsSet a model key: Models and what is sent
An e-mail when something breaksAlert e-mails from a self-hosted engine
Your coding agent reading problemsInstall with your coding agent
The whole loop once, with a rage click and a replayYour first problem
Your own file names in stacksSource maps in CI

To stop the trial: docker compose down. Add -v to delete its data too.

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