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.
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.
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.Check the setup
Terminal docker compose exec sypnia sypnia doctor --skip aiYou should seeText 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 passedA line that says
FAILnames 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.Create a project and a token
Terminal docker compose exec sypnia sypnia project create --name ShopYou should seeText 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,replayThe 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,replayYou should seeA line that starts withsps_. It is shown once: copy it now. It is a secret.Add the SDK to your app
npm
npm install @sypnia/browserimport { init } from '@sypnia/browser'; init({ project: 'YOUR_PROJECT_KEY' });pnpm
pnpm add @sypnia/browserimport { init } from '@sypnia/browser'; init({ project: 'YOUR_PROJECT_KEY' });yarn
yarn add @sypnia/browserimport { init } from '@sypnia/browser'; init({ project: 'YOUR_PROJECT_KEY' });bun
bun add @sypnia/browserimport { init } from '@sypnia/browser'; init({ project: 'YOUR_PROJECT_KEY' });script tag
<script async src="https://ingest.sypnia.com/v1/sdk.js" data-project="YOUR_PROJECT_KEY"></script>No build step and no
initcall: paste it before</head>. The tag starts Sypnia with the key indata-project.Put the
initcall where your app starts, before it renders. Use your own ingest key, and point the SDK at your engine withendpoint: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"anddata-endpoint="http://localhost:8080".endpointis the only difference from Sypnia Cloud. The SDK is the same package.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
ingestin the filter.You should seeWithin 10 seconds, aPOSTtohttp://localhost:8080/v1/ingest/eventswith status200and an answer like{"accepted": 5, "dropped": 0}.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 environmentdevelopment.You should seeWithin 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
| Sypnia engineOpen source, self-hosted | Sypnia CloudPaid service, with a free tier | |
|---|---|---|
| Receiving, storing, grouping into problems, sessions, replays | Running on your machine. | The same engine, run by us. |
| Where you read it | The Console (problems and replays), the API, the CLI and the MCP server. | The full app. |
| The sentence in plain words and the prompt | After you set your own model key. | Included. |
| Alerts | Recorded, and sent to a webhook if you set one. No e-mail in the default deployment. | E-mail and in the app. |
| Pull requests | Not 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 get | Do |
|---|---|
| A deployment that others can reach, with HTTPS | Deploy with Docker or Deploy on AWS |
| The sentence in plain words | Set a model key: Models and what is sent |
| An e-mail when something breaks | Alert e-mails from a self-hosted engine |
| Your coding agent reading problems | Install with your coding agent |
| The whole loop once, with a rage click and a replay | Your first problem |
| Your own file names in stacks | Source maps in CI |
To stop the trial: docker compose down. Add -v to delete its data too.