Docs

DocsGet started

Quick start

This guide shows how to run Checkend, connect an app with a Sentry SDK, and read the errors.

View as Markdown Ask Claude Ask ChatGPT

You need:

  • Node 22.18 or later
  • a clone of the Checkend repository, with npm ci done
  • for a deploy: a Cloudflare account and npx wrangler login

1Run Checkend on your computer#

  1. Create the local database tables:

    Terminal
    npx wrangler d1 migrations apply DB --local

  2. Make an admin token, and put it in .dev.vars (this file is git-ignored):

    Terminal
    echo "ADMIN_TOKEN=$(openssl rand -hex 32)" > .dev.vars

  3. Start the Worker:

    Terminal
    npm run dev

  4. Check that it runs:

    Terminal
    curl http://localhost:8787/health

    The response has "status": "ok". See Settings and health for the other fields.

2Or deploy it to your Cloudflare account#

To run Checkend without Cloudflare, in Docker, on Node, or on a server over SSH, see Run without Cloudflare.

The first path is ce server install cloudflare (see the ce CLI). It makes the Worker and the D1 database on your account, with a Cloudflare API token. It installs only a signed server release, shows the plan and asks first, and ends with the setup link of the web UI:

Terminal
ce server install cloudflare

Or do the steps below by hand.

Caution: a deploy uses resources in your Cloudflare account. On the Workers Free plan, also set D1_DAILY_ROW_LIMIT (see Budget mode).

  1. Create a D1 database. Wrangler prints its database_id.

    Terminal
    npx wrangler d1 create checkend

  2. Copy wrangler.jsonc to wrangler.<name>.jsonc, for example wrangler.mine.jsonc. In the copy, set your Worker name, and add the database_id to the DB entry. Files with the name wrangler.*.jsonc are git-ignored, so your resource IDs stay out of the repository.

  3. Apply the migrations and deploy:

    Terminal
    npx wrangler d1 migrations apply DB --remote --config wrangler.mine.jsonc
npx wrangler deploy --config wrangler.mine.jsonc

  4. Set the admin token as a Worker secret. Until the secret is set, the API answers 401.

    Terminal
    npx wrangler secret put ADMIN_TOKEN --config wrangler.mine.jsonc

For a project with many users, also add a rate limiting rule in front of ingest: see Protect the ingest path.

Apply the migrations before each deploy. Wrangler records each applied migration and skips it, so it is safe to run the command again.

3Create a project and get a DSN#

A project is one app. Each project has a DSN: the address that the Sentry SDK sends errors to.

Terminal
$ npm run project -- create --name "My App" --platform nodeCreated project 4821937065 (my-app).DSN: https://8c1f4d0e9b7a42f6a3e5d2c1b0f9e8d7@checkend.example.workers.dev/4821937065Put the DSN in your Sentry SDK: Sentry.init({ dsn: "..." }).
Create a project. The project CLI calls POST /v1/projects and prints the DSN.
Terminal
export CHECKEND_URL=https://<your-worker>      # or http://localhost:8787
export CHECKEND_ADMIN_TOKEN=<your ADMIN_TOKEN>

npm run project -- create --name "My App" --platform node

The command prints the project ID and the DSN. To see all projects and their DSNs later:

Terminal
npm run project -- list

Add --json to either command for JSON output.

https:// 8c1f4d0e9b7a42f6a3e5d2c1b0f9e8d7public key@ checkend.example.workers.devyour Worker host/ 4821937065project ID
The parts of a DSN. The public key identifies the project. It only lets a client send events, so it is not a secret.

4Connect your app#

Use any Sentry SDK. Put the Checkend DSN in Sentry.init. For example, in Node:

JavaScript
import * as Sentry from "@sentry/node";

Sentry.init({ dsn: "https://<key>@<your-worker>/<project-id>" });

Browser SDKs work too: the ingest endpoints allow requests from other origins (CORS).

Checkend keeps error events only (exceptions and captureMessage). It drops sessions, transactions, client reports and attachments. See Send errors.

5Read the errors#

Terminal
curl -H "Authorization: Bearer $CHECKEND_ADMIN_TOKEN" "$CHECKEND_URL/v1/issues"

Each issue is a group of events with the same cause. To see one issue and its events:

Terminal
curl -H "Authorization: Bearer $CHECKEND_ADMIN_TOKEN" "$CHECKEND_URL/v1/issues/1"
curl -H "Authorization: Bearer $CHECKEND_ADMIN_TOKEN" "$CHECKEND_URL/v1/issues/1/events"

See API for all endpoints.

Terminal
$ curl -s -H "Authorization: Bearer $CHECKEND_ADMIN_TOKEN" "$CHECKEND_URL/v1/issues?limit=1" | jq{  "data": [    {      "id": 1,      "project_id": 4821937065,      "title": "TypeError: Cannot read properties of undefined (reading 'id')",      "culprit": "loadUser (src/users.ts)",      "type": "TypeError",      "level": "error",      "platform": "node",      "status": "unresolved",      "times_seen": 42,      "stored_events": 42,      "events_24h": 42,      "events_7d": 42,      "users_affected": 2,      "priority": 198.462,      "first_seen": "2026-10-10T14:02:11.087Z",      "last_seen": "2026-10-10T15:47:03.412Z",      "first_release": "my-app@1.4.0",      "last_release": "my-app@1.4.0",      "fingerprint": "5d41402abc4b2a76b9719d911017c592",      "fingerprint_version": 1,      "merged_into": null,      "claim": null,      "trust": "high"    }  ],  "next_cursor": "WyIyMDI2LTEwLTEwVDE1OjQ3OjAzLjQxMloiLDFd",  "ingest": {    "mode": "full",    "rows_written_today": 509,    "daily_row_limit": null,    "events_received_today": 42,    "write_failures_today": 0,    "retry_after_seconds": 0  }}
Read the issues. An example response from GET /v1/issues. Each issue groups the events with the same cause.

6Give your coding agent a read-only token#

Do not give the admin token to an agent. Create a token that can only read issues:

Terminal
curl -X POST "$CHECKEND_URL/v1/tokens" \
  -H "Authorization: Bearer $CHECKEND_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "claude-code", "scopes": ["issues:read"]}'

The response has the token (ck_...). Copy it now: Checkend shows it only once. Give it to the agent as its bearer token. To revoke it later, use DELETE /v1/tokens/:id.

If the agent must also resolve, ignore or merge issues, create its token with "scopes": ["issues:read", "issues:write"].

7Connect your coding agent with MCP#

Add the Checkend MCP server to your agent with the read-only token. For Claude Code:

Terminal
claude mcp add --transport http checkend "$CHECKEND_URL/mcp" \
  --header "Authorization: Bearer <token>"

Then ask the agent, for example: "Fix the top unresolved error in Checkend." The agent calls list_issues, then get_issue_brief. See MCP server for the tools and the issue brief.

To let Checkend check in production that the fixes work, report your deploys. See Verify fixes.

Edit this page on GitHubSource: guides/quick-start.md

Esc