Checks as code, on your infrastructure

Selfchecks Self-hosted synthetic monitoring from checks as code

Selfchecks is a source-available monitoring service for API and browser checks. Define checks in your repository, run them on your own server, and inspect failures with traces, screenshots, videos, logs, and CI-ready reports.

npx create-selfchecks
View source Getting started

Source available under the Elastic License 2.0.

Existing checks
import repository definitions
Local runner
execute API and browser checks
Run evidence
keep traces, screenshots, logs
Alerts
notify on failure and recovery

Operational shape

A compact control plane for teams that already own their checks

Selfchecks is not a full cloud clone. It keeps the familiar repository workflow and gives you a self-hosted alternative to a hosted control plane, with a small runner, dashboard, and notification loop.

Compatibility import

Execute supported Checkly-style TypeScript constructs locally and compile helpers, loops, API assertions, groups, schedules, and Playwright entrypoints into a versioned manifest.

Local execution

Run checks on your own server through a queue-backed worker, with browser isolation and predictable concurrency controls.

Artifacts first

Keep the evidence attached to every run: response data, logs, screenshots, traces, videos, timing metrics, and result JSON.

Failure loop

Trigger checks from CI, show GitHub-style reports, and route failure or recovery events through generic webhooks and Rocket.Chat.

Documentation

From an empty folder to scheduled checks

Create a project, add browser and API checks, connect GitLab or GitHub CI/CD, use the HTTP API, and deploy Selfchecks on your own server.

Read the guide

Control loop

From code to recovery signal

Deploy

Upload definitions

CI uploads fresh check manifests through the authenticated HTTP API.

Queue

Schedule or trigger

Runs enter the worker queue from cron-like schedules, manual triggers, or PR jobs.

Execute

Run API and browser checks

Undici powers API checks, while Playwright captures browser evidence.

Inspect

Open run evidence

The dashboard links status, stats, logs, traces, screenshots, and responses.

Notify

Send failure and recovery events

Webhook adapters keep the incident channel aligned with the latest run state.

Dashboard

Run evidence dashboard

The primary UI is an operational dashboard: grouped checks, filters, latest run state, p95 latency, availability, run history bars, artifacts, and settings for environments and notification targets.

  • Compact group and check rows for daily scanning.
  • Run detail pages with request, response, logs, trace, video, and screenshots.
  • Admin settings for project secrets and runtime environment variables.
Selfchecks home dashboard showing passing and failing checks, project filters, availability, and recent result bars.
The live dashboard groups checks by project and keeps current state, availability, latency, and recent results in one scan.

Product tour

Follow health from volume to one check

Start with fleet-wide usage, then narrow the view to a single check and its run history without leaving the same operational context.

Selfchecks usage dashboard showing completed API and browser tests over 30 days with daily and source charts.
Understand test volume Separate API and browser traffic, then compare scheduled runs with CI test sessions.
Selfchecks browser check detail with schedule, tags, availability, run history, duration, and performance metrics.
Inspect one check over time See availability, retries, duration percentiles, performance metrics, and the latest runs together.

HTTP API

Connect CI with one API token

Set the service URL and token once. Deploys and test bundles are uploaded through the authenticated API, while triggers queue the latest successful deployment. Project CI does not need SSH or rsync access to the Selfchecks host.

CI trigger 
npm install --save-dev @selfchecks/selfchecks-cli

export SELFCHECKS_URL=https://checks.example.com
export SELFCHECKS_API_TOKEN="$CI_SELFCHECKS_API_TOKEN"

npx selfchecks deploy --force
npx selfchecks test \
  --tags app,smoke,pr \
  -e ENVIRONMENT_URL=https://preview.example.com \
  --reporter=github \
  --record
npx selfchecks trigger \
  --reporter=github \
  --retries=1 \
  --record
Check definition 
import { BrowserCheck, Frequency } from "@selfchecks/selfchecks/constructs";

new BrowserCheck("Signin", {
  name: "Signin",
  activated: true,
  frequency: Frequency.EVERY_10M,
  tags: ["app", "smoke"],
  code: {
    entrypoint: "./signin.spec.ts"
  }
});

Structured CI metadata

Recorded test sessions keep CI context as separate fields instead of encoding it in a delimiter-based source string. GitLab variables provide the defaults, and every value can be overridden with a CLI flag.

CI metadata fields, CLI overrides, and GitLab defaults
Field CLI flag GitLab default Stored value
repository --repository CI_PROJECT_PATH Repository path, for example sendsay-ru/frontend/account.
ref --ref CI_COMMIT_TAG or CI_COMMIT_REF_NAME Branch or tag, for example release/3.192.42.
commitSha --commit-sha CI_COMMIT_SHA Full commit SHA.
pipelineUrl --pipeline-url CI_PIPELINE_URL Link to the CI pipeline.
jobUrl --job-url CI_JOB_URL Link to the CI job.

MVP stack

Small, boring, and inspectable

Next.js dashboard

React UI, auth, API routes, settings, run history, and artifact views.

PostgreSQL

Projects, deployments, groups, checks, runs, artifacts, secrets, and notifications.

BullMQ + Redis

Predictable scheduling, retries, concurrency limits, and background execution.

Playwright

Browser checks with traces, screenshots, videos, console errors, and timing metrics.

Undici fetch

API checks with request/response capture and assertion results.

Webhooks

Generic failure and recovery notifications, with Rocket.Chat first.

Quick answers

Selfchecks FAQ

The short version of what Selfchecks is, how it runs, and where its compatibility and license boundaries are.

What is Selfchecks?

Selfchecks is a source-available, self-hosted synthetic monitoring service for API and browser checks defined as code. It combines a runner, dashboard, schedules, CI integration, run artifacts, and webhook notifications.

How do I start a Selfchecks project?

Run npx create-selfchecks my-checks. The generator creates a minimal Node.js project with a Playwright browser check, configuration, scripts, and supported Selfchecks packages.

Does Selfchecks require Docker in CI?

No. Project CI needs Node.js and the Selfchecks CLI, while Docker is required only on the Linux server that hosts the Selfchecks application and worker.

Is Selfchecks fully compatible with Checkly?

No. Selfchecks provides a deliberately narrow source-compatible subset for API and browser checks, assertions, groups, retries, schedules, and webhooks. Unsupported properties fail compilation; Checkly APIs and cloud runtime behavior are not compatibility targets.

What evidence does Selfchecks keep for failed checks?

Runs can retain request and response data, logs, screenshots, Playwright traces, videos, timing metrics, performance data, and result JSON for investigation.

Is Selfchecks open source?

Selfchecks is source available under the Elastic License 2.0. The license is not OSI-approved and restricts offering substantial Selfchecks functionality to third parties as a hosted or managed service.