Docs/Reference

Settings and health

The settings that you can change, budget mode for the Workers Free plan, and the health endpoint.

Settings#

All settings are optional. Set them as Workers secrets or variables (in your wrangler.<name>.jsonc or in the Cloudflare dashboard).

Set the secret with Wrangler:

npx wrangler secret put ADMIN_TOKEN --config wrangler.<name>.jsonc

For local development, put ADMIN_TOKEN=... in .dev.vars. This file is git-ignored.

On Node (Docker), there are more settings, for example DATABASE_PATH. See Run without Cloudflare.

PUBLIC_URL#

When PUBLIC_URL is set, Checkend uses it, and never the Host of the request, for:

• the passkey relying party (its ID is the host name of PUBLIC_URL)
• the CSRF origin check of the web UI
• each URL that the web UI shows (the setup prompt, the DSN)
• /llms.txt, /skill.md, /v1/openapi.json, /agent/install, /agent/setup.md and /agent/tasks/*.md
• the DSNs of /v1/projects and of POST /v1/setup/apps

When it is not set, Checkend uses the origin of the request.

The value must be an http or https origin. A / at the end is accepted. Checkend keeps only the scheme, the host and the port, in lower case. Checkend ignores a value with no scheme, another scheme, a path (https://x/checkend), a query, a fragment, or a user and password. Then it writes one console.error line that names PUBLIC_URL. Checkend cannot run under a path.

On Workers, the host name is fixed, so PUBLIC_URL is optional. On Node behind a proxy, set it (see Behind a reverse proxy).

Optional Cloudflare bindings#

The root wrangler.jsonc has only what a new Workers Free account can deploy: D1 and one Cron Trigger. Checkend finds the other bindings at runtime and works without them. To add one, add its block to your Worker config (wrangler.<name>.jsonc), then deploy.

A rate limit for each DSN key:

"ratelimits": [
  { "name": "INGEST_RATE_LIMITER", "namespace_id": "1001", "simple": { "limit": 1000, "period": 60 } }
]

R2 for source maps and large raw payloads (see Source maps):

"r2_buckets": [{ "binding": "BLOBS", "bucket_name": "checkend-blobs" }]

The overflow queue (see Bursts and overload):

"queues": {
  "producers": [{ "binding": "INGEST_QUEUE", "queue": "checkend-ingest" }],
  "consumers": [{ "queue": "checkend-ingest" }]
}

Workers AI for AI triage:

"ai": { "binding": "AI" }

A Vectorize index for similar issues (make it with npx wrangler vectorize create checkend-issues --dimensions=1024 --metric=cosine):

"vectorize": [{ "binding": "VECTORIZE", "index_name": "checkend-issues" }]

Email alerts (see Alerts), with the variable EMAIL_FROM:

"send_email": [{ "name": "EMAIL" }]

Budget mode (Workers Free plan)#

The Workers Free plan limits how many rows D1 can write each day. If Checkend writes too many rows, D1 stops all writes until the next day.

To prevent this, set:

D1_DAILY_ROW_LIMIT=100000

Checkend estimates the rows that it writes: 10 rows for a stored event, 6 rows for a counted event, 2 more rows for an event with a user, and 1 row for each new tag key. This is an estimate, not the real count from D1. Each Worker instance reads the count again at most every 30 seconds.

When the estimate reaches 80% of this limit, it goes into budget mode until 00:00 UTC. In budget mode, Checkend still counts events, but it does not store them. /health and the API show the mode as counters_only.

Data retention#

Every 5 minutes, the cron deletes data that is older than RETENTION_DAYS (90 by default):

• stored events, with their raw payloads (also the ones in BLOBS)
• hourly counts
• the records of pushed commits
• finished webhook deliveries (delivered or failed), after 30 days. Pending deliveries stay.

Checkend keeps the issues (with their total times_seen), the activity timeline (the audit record), and the user hashes behind users_affected.

Hourly counts stay for at least 8 days, also when RETENTION_DAYS is shorter, because events_7d and the priority score use them.

To keep each run small in D1 row writes, Checkend deletes in chunks: 500 rows, at most 4 chunks in each run. A large backlog, for example after you lower RETENTION_DAYS, goes away over several runs. After it deletes events, Checkend updates the stored-event counts of the issues.

Health#

GET /health needs no token. It returns the state of the install:

{
  "status": "ok",
  "version": "0.8.0",
  "migrations": { "level": 3, "latest": "0003_tokens_activity_public_ids.sql", "applied": 3 },
  "ingest": { "mode": "full", "write_failures_today": 0, "retry_after_seconds": 0 },
  "setup_open": false,
  "time": "2026-10-10T12:00:00.000Z"
}

When the database cannot be read, /health returns 503. The response has no error details, because /health is public.

Ingest state#

GET /v1/issues also returns the ingest state in the ingest field. It has more fields than /health:

Edit this page on GitHubSource: guides/settings.md