# Selfchecks

> Selfchecks is a source-available, self-hosted synthetic monitoring service for
> API and browser checks defined as code. It runs checks on the user's own
> infrastructure and keeps run evidence in an operational dashboard.

Canonical site: https://selfchecks.github.io/
Language: English
Last updated: 2026-08-14

## Primary documentation

- [Selfchecks landing page](https://selfchecks.github.io/): Product overview,
  workflow, dashboard, CLI, stack, license boundary, and frequently asked
  questions.
- [Getting started](https://selfchecks.github.io/getting-started.html): Canonical
  guide for creating a project, writing checks, using the HTTP API, configuring
  GitLab or GitHub CI/CD, migrating supported Checkly constructs, and deploying
  a Selfchecks server.
- [Main source repository](https://github.com/selfchecks/selfchecks): Application,
  worker, packages, installation scripts, issue tracker, and releases.
- [Elastic License 2.0](https://github.com/selfchecks/selfchecks/blob/stable/LICENSE):
  Canonical license terms.

## Quick facts

- Product category: self-hosted synthetic monitoring and checks as code.
- Check types: API checks and Playwright browser checks.
- Deployment: a Linux server running the Docker Compose stack.
- Project CI requirements: Node.js and the Selfchecks CLI; Docker is not required
  in project CI jobs.
- Server components: Next.js dashboard, PostgreSQL, BullMQ, Redis, Playwright,
  native fetch / Undici, and Caddy.
- Run evidence: request and response data, logs, screenshots, Playwright traces,
  videos, timing metrics, performance data, and result JSON.
- Notifications: generic webhooks for failure and recovery events, with
  Rocket.Chat as the first concrete adapter.
- License: source available under Elastic License 2.0; not OSI-approved open
  source.

## npm packages

- [`create-selfchecks`](https://www.npmjs.com/package/create-selfchecks): Project
  generator, invoked as `npx create-selfchecks my-checks`.
- [`@selfchecks/selfchecks-cli`](https://www.npmjs.com/package/@selfchecks/selfchecks-cli):
  Remote `selfchecks` CLI for deploy, test, and trigger workflows.
- [`@selfchecks/selfchecks`](https://www.npmjs.com/package/@selfchecks/selfchecks):
  Supported checks-as-code constructs.

## Core workflow

1. Define API or browser checks next to application code.
2. Upload definitions with `selfchecks deploy`, or upload and run a test bundle
   with `selfchecks test`.
3. Queue runs from schedules, manual triggers, or CI jobs.
4. Execute checks on the self-hosted worker.
5. Inspect status, latency, availability, logs, traces, screenshots, videos, and
   responses in the dashboard.
6. Send failure and recovery notifications through webhook adapters.

## Useful commands

- `npx create-selfchecks my-checks`
- `selfchecks deploy --project my-project --root .`
- `selfchecks test --project my-project --root . --record --reporter github`
- `selfchecks trigger --project my-project --record --retries 1`

## Checkly compatibility boundary

Selfchecks provides a deliberately narrow migration subset, not complete Checkly
compatibility. Projects can alias the supported package with
`"checkly": "npm:@selfchecks/selfchecks@latest"` to preserve common import
specifiers.

Supported from `checkly`: `defineConfig`.

Supported from `checkly/constructs`: `ApiCheck`, `BrowserCheck`, `CheckGroup`,
`CheckGroupV2`, documented `Frequency` constants, `AssertionBuilder`,
`RetryStrategyBuilder`, `AlertEscalationBuilder.runBasedEscalation`,
`WebhookAlertChannel`, and related props and request types.

The CLI executes project TypeScript locally and sends DeploymentManifest v1 to the
server, so imported helpers, loops, and computed constructs work without
project-specific parsing. API requests support headers, query parameters, bodies,
body types, Basic Auth, redirect control, environment placeholders, response-time
limits, and assertions over status, time, headers, text, and JSON. Webhook alert
channels attached through groups are deployed.

Unsupported construct properties fail compilation explicitly. Locations, Checkly
runtimes, secrets, environment-variable constructs, status pages, maintenance
windows, alert escalation policies, Checkly APIs, cloud services, CLI commands,
and cloud runtime behavior are unsupported.

## Remote CI flow

Set `SELFCHECKS_URL` to the dashboard URL and `SELFCHECKS_API_TOKEN` to a valid
project API token. The CLI uploads source bundles through the authenticated HTTP
API. Bundles exclude dependencies, local secrets, reports, and previous artifacts
and are limited to 10,000 files and 40 MB.

Recorded CI sessions store repository, ref, commit SHA, pipeline URL, and job URL
as separate fields. GitLab variables provide defaults; GitHub Actions values are
passed with the corresponding CLI flags.

## Licensing boundary

Selfchecks is source available under the Elastic License 2.0. The license permits
use, modification, and redistribution under its terms, but it does not permit
providing substantial Selfchecks functionality to third parties as a hosted or
managed service. Refer to the canonical license link above for legal terms.