# 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: the Sypnia engine (open source, self-hosted). Status: at launch.  
Source: https://docs.sypnia.com/start/quickstart-self-host/

**\[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](https://docs.sypnia.com/start/quickstart-cloud); 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.

> **Note: This is a trial setup**
>
> It runs on `localhost`, without HTTPS, with passwords written in a file. It is right for trying Sypnia and wrong for production. For a real deployment follow [Deploy with Docker](https://docs.sypnia.com/self-hosting/deploy-docker) or the AWS template in [Deploy on AWS](https://docs.sypnia.com/self-hosting/deploy-aws), then the [security checklist](https://docs.sypnia.com/self-hosting/security-checklist).

### 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`

```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](https://docs.sypnia.com/self-hosting/configuration). The engine needs nothing else: no queue, no cache, no search server.

### 2. Start it

```bash
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

```bash
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](https://docs.sypnia.com/agent/models-and-what-is-sent).

### 4. Create a project and a token

```bash
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:

```bash
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**

```bash
npm install @sypnia/browser
```

```js
import { init } from '@sypnia/browser';

init({ project: 'YOUR_PROJECT_KEY' });
```

**pnpm**

```bash
pnpm add @sypnia/browser
```

```js
import { init } from '@sypnia/browser';

init({ project: 'YOUR_PROJECT_KEY' });
```

**yarn**

```bash
yarn add @sypnia/browser
```

```js
import { init } from '@sypnia/browser';

init({ project: 'YOUR_PROJECT_KEY' });
```

**bun**

```bash
bun add @sypnia/browser
```

```js
import { init } from '@sypnia/browser';

init({ project: 'YOUR_PROJECT_KEY' });
```

**script tag**

```html
<script async
  src="https://ingest.sypnia.com/v1/sdk.js"
  data-project="YOUR_PROJECT_KEY"></script>
```

No build step and no `init` call: paste it before `</head>`. The tag starts Sypnia with the key in `data-project`.

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`

```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`

```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:

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

## What you have, and what you do not

|                                                               | Sypnia engine (open source, self-hosted)                                             | Sypnia Cloud (paid 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](https://docs.sypnia.com/start/open-source-and-cloud).

## Do these next

| To get                                              | Do                                                                                                                                           |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| A deployment that others can reach, with HTTPS      | [Deploy with Docker](https://docs.sypnia.com/self-hosting/deploy-docker) or [Deploy on AWS](https://docs.sypnia.com/self-hosting/deploy-aws) |
| The sentence in plain words                         | Set a model key: [Models and what is sent](https://docs.sypnia.com/agent/models-and-what-is-sent)                                            |
| An e-mail when something breaks                     | [Alert e-mails from a self-hosted engine](https://docs.sypnia.com/guides/alert-emails-self-hosted)                                           |
| Your coding agent reading problems                  | [Install with your coding agent](https://docs.sypnia.com/start/install-with-your-agent)                                                      |
| The whole loop once, with a rage click and a replay | [Your first problem](https://docs.sypnia.com/start/your-first-problem)                                                                       |
| Your own file names in stacks                       | [Source maps in CI](https://docs.sypnia.com/guides/source-maps-in-ci)                                                                        |

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