Setup, App, CLI, and API

Architecture

Pulse is serverless end to end. There is no long-running process to babysit.

• Vercel Cron invokes /api/cron/check-monitors every minute. The scheduler packs due monitors into one batch, checks them concurrently, and resolves state transitions atomically.
• Neon stores incidents, exception payloads, and compact rollups. An adaptive storage governor keeps the database inside a 500 MB budget by compacting routine checks while preserving incident detail.
• Edge Config serves the accepted monitoring configuration and the latest public state with minimal latency, and acts as a fallback if the database is unreachable.
• Resend sends one email when a monitor is confirmed down and one when it recovers.
• A second cron, /api/cron/maintenance, runs daily at 03:17. It compacts routine checks, builds rollups, and snapshots database usage.

Environment variables

The canonical list lives in .env.example. Values are validated at boot.

Email alerts

Pulse sends exactly three kinds of email, all from RESEND_FROM_EMAIL. When the failure threshold confirms an outage, every recipient on the monitor gets one message. When the recovery threshold confirms the fix, they get one more. Delivery runs through a durable outbox, so retries never duplicate a message.

The subject line is the headline: a monitor named Inference pages you as “Inference is down”. Both incident emails deep-link to /incidents/:id, and that is the whole surface. There are no digests, reminders, or marketing follow-ups.

Hardening your deployment

Default secure, but production needs a few extra operator-side controls tightened.

Run under a least-privilege database role. Create a dedicated Postgres login with only the grants the app needs, and point the pooled DATABASE_URL at it. Keep the Neon owner (neondb_owner) and the unpooled DATABASE_URL_UNPOOLED credential for migrations only, and remove it from the application environment so the running app never authenticates as the schema owner.

Add the browser security headers. Production ships HSTS. Add the rest of the central policy so the dashboard is defended in depth.

Claim the first admin immediately. A fresh deployment boots into onboarding with no administrator. Claim the initial account the moment the deploy is live so no one else can. Creating that first admin requires a one-time bootstrap credential supplied through the PULSE_BOOTSTRAP_TOKEN environment variable; set it before first run, use it to create the admin, then remove it.

Rotate provider secrets and scope them tightly. Generate fresh values for RESEND_API_KEY, CRON_SECRET, DEVICE_AUTH_SECRET, and API_TOKEN_HASH_KEY for your own deployment rather than reusing any shared value, and scope the Resend key to sending only.

Install the CLI only from the official source. Until signed release artifacts exist, build pulsectl from source with Go and nothing else.

go install github.com/0xSMW/pulse-uptime/cli/cmd/pulsectl@latest

Onboarding · /onboarding

A fresh deployment boots straight into onboarding. A readiness gate checks Vercel, the database, Edge Config, and email before anything else, then three steps create the administrator account, add a first monitor, and verify a live check before activating it. A closing screen hands off to the CLI and agent tokens. Sign in afterwards at /login.

Overview · /

The home screen lists every monitor with its live state, 24-hour uptime, check timeline, and latency. A health banner summarizes the whole system, and the ⌘K command palette jumps anywhere or runs quick actions. New Monitor opens a sheet that asks for four fields: name, URL, group, and interval. Method, timeout, expected status, and thresholds are tucked behind Advanced.

Monitor detail · /monitors/:id

One monitor's full story: the current state with its confirmation progress, a segmented check timeline, a latency chart, and recent transitions. Pause, resume, edit, test, and archive actions live here. Archiving keeps history. Re-create a monitor with the same id, through the API or config apply, and it comes back.

Incidents · /incidents

Every failure gets a durable record. The list filters by monitor and resolution state. The detail view (/incidents/:id) shows the cause, the event trail of every state transition with timestamps, and which notifications were delivered. Incidents open only after the failure threshold confirms an outage, so flapping checks don't page you.

Settings · /settings

Four areas, one per sidebar item:

• General: theme, time zone, default recipients, and outbound sender info.
• Monitors: every monitor, plus the groups that structure the dashboard and the public status page.
• Access: create scoped API tokens for agents and automation, review linked CLI installations, and revoke either.
• System: live storage budget, per-category usage, how long each data category is kept, and the governor's current mode. Domain monitoring shows Porkbun connection, webhook, polling, and expiry-alert status.

Domain monitoring · /settings/system

Porkbun supplies registration expiry and auto-renew for covered domains. The System card runs every ten minutes and reads the Porkbun portfolio for due domains, normally once per 24 hours. It accepts signed domain.renewed and domain.expiring webhooks. Expiry alerts are off by default and notify default recipients at 30 and 14 days. Certificate checks remain direct TLS probes. Certificate alerts are out of scope.

Status page · /status

A public, indexable status page that revalidates every 30 seconds, with per-group views at /status/:group. It shows current operational state per monitor without exposing internal detail. The page title comes from NEXT_PUBLIC_STATUS_PAGE_NAME.

Install & link

go install github.com/0xSMW/pulse-uptime/cli/cmd/pulsectl@latest
pulsectl me --server https://pulse.superposition.app

Build the CLI from source with Go until signed release artifacts are published. Replace the example URL with your deployment. pulsectl me triggers an interactive browser approval on first run and stores the session in your operating-system keyring. Once linked, it reports who you are and which scopes you hold.

Authentication

Interactive linking uses an OAuth-style device flow:

1. The CLI requests a device authorization and prints a short user code.
2. Your browser opens /cli/authorize on the server, where you confirm the code as a signed-in administrator.
3. The CLI polls until approval, then stores the session token in the OS keyring, never on disk.

pulsectl auth login          # link this installation
pulsectl auth status         # inspect the current session
pulsectl auth unlink --yes   # remove it

# headless environments: pass a scoped token instead
export PULSECTL_TOKEN=pulse_live_...
echo "$PULSECTL_TOKEN" | pulsectl monitor list --token-stdin

Contexts & flags

Contexts are named server profiles stored in local config, so one binary can drive several Pulse deployments.

pulsectl context add production --url https://pulse.superposition.app --use
pulsectl context add staging --url https://staging.superposition.app
pulsectl context list
pulsectl monitor list --context staging

Settings resolve in precedence order: flags, then environment, then the active context.

Command reference

Every command declares the API scope it needs, the same scopes you grant to tokens. authenticated means any signed-in principal.

Output formats

Data goes to stdout, diagnostics to stderr. On a TTY the default is a table. When piped, output defaults to json (jsonl for monitor watch), so scripts never parse table art.

pulsectl monitor list -o json | jq '.[].id'
pulsectl monitor watch -o jsonl --state DOWN
pulsectl incident list -o yaml

Exit codes

Exit codes are typed so scripts and agents can branch without parsing messages.

Agents

Agents get the same control plane as people. Create a scoped token in Settings → Access and export three variables. The CLI then runs without a browser, and help --output json hands your agent a manifest of every command, flag, and required scope.

export PULSECTL_URL=https://pulse.superposition.app
export PULSECTL_TOKEN=pulse_live_...
export PULSECTL_OUTPUT=json

pulsectl help --output json   # machine-readable command manifest
pulsectl config schema        # JSON schema for the config document
pulsectl monitor list

The config file

version: 2
settings:
  concurrency: 25
  defaultTimeoutMs: 8000
  defaultFailureThreshold: 2
  defaultRecoveryThreshold: 2
  defaultRecipients:
    - codex@superposition.app
  userAgent: Pulse/1.0
groups:
  - id: production
    name: Production
monitors:
  - id: api
    name: API
    url: https://inference.superposition.app/health
    enabled: true
    groupId: production
    method: GET
    intervalMinutes: 1
    timeoutMs: 8000
    expectedStatus: { minimum: 200, maximum: 299 }
    failureThreshold: 2
    recoveryThreshold: 2
    recipients: []

Monitor ids must be unique, at most 100 monitors may be enabled, and the document may not exceed 55 KB. Exporting a v1 document automatically upgrades it to the v2 group format.

Plan & apply

pulsectl config export --file monitors.yaml
# edit monitors.yaml
pulsectl config validate --file monitors.yaml
pulsectl config plan --file monitors.yaml
pulsectl config apply --file monitors.yaml --wait

validate checks the document against the schema and semantic rules without touching the server state. plan computes an exact diff plus content hashes of the base and target. The diff covers settings changes. For groups it lists creates, renames, and deletes. For monitors it lists creates, field-level updates, pauses, resumes, and archives. apply submits the plan and, with --wait, polls the resulting operation until it is accepted (written to Edge Config) or rejected.

Safety rails

• Optimistic concurrency. Every export carries an ETag. Apply sends it back as If-Match along with the base, target, and plan hashes. If anyone changed configuration in between, the apply fails with a conflict instead of silently clobbering.
• Destructive-change tripwire. A plan that archives monitors or deletes groups sets destructiveConsentRequired. Non-interactive applies must state intent twice: --allow-destructive --yes.
• Archives, not deletes. Removing a monitor archives it with its history. Re-adding the same id restores it.

Conventions

The base URL is your deployment. Pulse is self-hosted, so there is no shared api.pulse.dev. Every response is a typed envelope:

{
  "apiVersion": "v1",
  "kind": "MonitorList",
  "data": [ ],
  "meta": {
    "requestId": "req_01j8zqf7",
    "nextCursor": null
  }
}

• Kinds. kind names the payload shape: Monitor, MonitorList, Incident, ConfigurationPlan, Error, and so on.
• Pagination. List endpoints take limit and cursor. Follow meta.nextCursor until it is null.
• Idempotency. Every mutating request must include an Idempotency-Key header containing a UUID. Retries with the same key return the original result.
• Request ids. Every response carries meta.requestId for correlation.

Authentication & scopes

curl https://pulse.superposition.app/api/v1/monitors \
  -H "Authorization: Bearer $PULSE_TOKEN"

Three principal types share one permission model:

• Humans: first-party cookie sessions from the web app. They hold every scope, and mutations are origin-checked against the deployment URL as CSRF protection.
• API tokens: created in Settings or via pulsectl token create. They carry exactly the scopes you grant, require an explicit expiry of at most 365 days (the CLI defaults to 90d), and are stored only as keyed digests.
• CLI sessions: pulsectl installations linked through the browser device flow. Approval grants the full administrator scope set.

Requests without credentials get 401 with a WWW-Authenticate header. Authenticated requests missing a scope get 403 with error code SCOPE_DENIED.

Errors & rate limits

{
  "apiVersion": "v1",
  "kind": "Error",
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This operation requires monitors:write.",
    "details": {},
    "requestId": "req_01j8zqf7"
  }
}

Rate limits are per principal over a five-minute window: 600 reads and 120 mutations. Exceeding either returns 429 with a Retry-After header. Validation failures return 400 with field-level detail in error.details. Concurrency conflicts (stale If-Match, duplicate ids, reused idempotency keys with different bodies) return 409.

Version & principal

{
  "apiVersion": "v1",
  "kind": "Version",
  "data": {
    "supportedApiVersions": ["v1"],
    "minimumCliVersion": "0.3.0",
    "latestCliVersion": "0.3.2"
  },
  "meta": { "requestId": "req_01j8zqf7" }
}

{
  "apiVersion": "v1",
  "kind": "Me",
  "data": {
    "principalType": "api_token",
    "email": null,
    "tokenId": "0d9f6c1e-…",
    "tokenName": "ci-agent",
    "scopes": ["monitors:read", "incidents:read"],
    "installation": null
  },
  "meta": { "requestId": "req_01j8zqf7" }
}

Monitors

curl "https://pulse.superposition.app/api/v1/monitors?state=DOWN" \
  -H "Authorization: Bearer $PULSE_TOKEN"

# equivalent
pulsectl monitor list --state DOWN -o json

{
  "apiVersion": "v1",
  "kind": "MonitorList",
  "data": [
    {
      "id": "api",
      "name": "API",
      "url": "https://inference.superposition.app/health",
      "enabled": true,
      "group": "Production",
      "groupId": "production",
      "method": "GET",
      "intervalMinutes": 1,
      "timeoutMs": 8000,
      "expectedStatus": { "minimum": 200, "maximum": 299 },
      "failureThreshold": 2,
      "recoveryThreshold": 2,
      "recipients": ["codex@superposition.app"],
      "state": "DOWN"
    }
  ],
  "meta": { "requestId": "req_01j8zqf7", "nextCursor": null }
}

curl -X POST https://pulse.superposition.app/api/v1/monitors \
  -H "Authorization: Bearer $PULSE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"id": "console", "name": "Console", "url": "https://console.superposition.app"}'

# equivalent
pulsectl monitor create --id console --name "Console" --url https://console.superposition.app

curl https://pulse.superposition.app/api/v1/monitors/api \
  -H "Authorization: Bearer $PULSE_TOKEN"

curl -X PATCH https://pulse.superposition.app/api/v1/monitors/api \
  -H "Authorization: Bearer $PULSE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"intervalMinutes": 5, "timeoutMs": 10000}'

curl -X DELETE https://pulse.superposition.app/api/v1/monitors/api \
  -H "Authorization: Bearer $PULSE_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

curl -X POST https://pulse.superposition.app/api/v1/monitors/api/pause \
  -H "Authorization: Bearer $PULSE_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
curl -X POST https://pulse.superposition.app/api/v1/monitors/api/resume \
  -H "Authorization: Bearer $PULSE_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

{
  "apiVersion": "v1",
  "kind": "MonitorTest",
  "data": {
    "successful": true,
    "method": "GET",
    "finalUrl": "https://inference.superposition.app/health",
    "statusCode": 200,
    "latencyMs": 42,
    "redirectCount": 0,
    "errorCode": null,
    "errorMessage": null
  },
  "meta": { "requestId": "req_01j8zqf7" }
}

Groups

{
  "apiVersion": "v1",
  "kind": "GroupList",
  "data": [
    { "id": "production", "name": "Production", "monitorCount": 4 }
  ],
  "meta": { "requestId": "req_01j8zqf7", "nextCursor": null }
}

curl -X POST https://pulse.superposition.app/api/v1/groups \
  -H "Authorization: Bearer $PULSE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"id": "marketing", "name": "Marketing"}'

curl -X PATCH https://pulse.superposition.app/api/v1/groups/marketing \
  -H "Authorization: Bearer $PULSE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name": "Marketing Site"}'

curl -X DELETE https://pulse.superposition.app/api/v1/groups/marketing \
  -H "Authorization: Bearer $PULSE_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

Incidents

{
  "apiVersion": "v1",
  "kind": "IncidentList",
  "data": [
    {
      "id": "8f4e2c10-…",
      "monitorId": "api",
      "openedAt": "2026-07-12T08:14:00Z",
      "resolvedAt": "2026-07-12T08:31:00Z"
    }
  ],
  "meta": { "requestId": "req_01j8zqf7", "nextCursor": null }
}

curl https://pulse.superposition.app/api/v1/incidents/8f4e2c10-… \
  -H "Authorization: Bearer $PULSE_TOKEN"

# equivalent
pulsectl incident get 8f4e2c10-…

Status

curl https://pulse.superposition.app/api/v1/status \
  -H "Authorization: Bearer $PULSE_TOKEN"

# equivalent
pulsectl status

Configuration

The API surface behind plan & apply. Exports carry an ETag. Applies send it back as If-Match.

curl -i https://pulse.superposition.app/api/v1/config \
  -H "Authorization: Bearer $PULSE_TOKEN"
# ETag: "sha256:2c26b46b…"

pulsectl config schema -o json

{
  "apiVersion": "v1",
  "kind": "ConfigurationValidation",
  "data": { "valid": true, "errors": [] },
  "meta": { "requestId": "req_01j8zqf7" }
}

{
  "apiVersion": "v1",
  "kind": "ConfigurationPlan",
  "data": {
    "baseConfigHash": "sha256:2c26…",
    "targetConfigHash": "sha256:9d1a…",
    "planHash": "sha256:77b0…",
    "diff": {
      "settingsChanged": [ ],
      "groupCreates": [ ],
      "groupUpdates": [ ],
      "groupDeletes": [ ],
      "creates": [ ],
      "updates": [ ],
      "pauses": [ ],
      "resumes": [ ],
      "archives": [ ],
      "unchanged": [ ]
    },
    "destructiveConsentRequired": false
  },
  "meta": { "requestId": "req_01j8zqf7" }
}

curl -X POST https://pulse.superposition.app/api/v1/config/apply \
  -H "Authorization: Bearer $PULSE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'If-Match: "sha256:2c26…"' \
  -d '{
    "baseConfigHash": "sha256:2c26…",
    "targetConfigHash": "sha256:9d1a…",
    "planHash": "sha256:77b0…",
    "targetConfig": { … },
    "allowDestructiveChanges": false
  }'

{
  "apiVersion": "v1",
  "kind": "ConfigurationOperation",
  "data": { "id": "b3a9e0d2-…", "state": "accepted" },
  "meta": { "requestId": "req_01j8zqf7" }
}

Tokens

pulsectl token create --name ci-agent \
  --scope monitors:read --scope incidents:read \
  --expires-in 90d

{
  "apiVersion": "v1",
  "kind": "CreatedToken",
  "data": {
    "id": "0d9f6c1e-…",
    "name": "ci-agent",
    "token": "pulse_live_…",
    "scopes": ["monitors:read", "incidents:read"],
    "expiresAt": "2026-10-16T00:00:00Z"
  },
  "meta": { "requestId": "req_01j8zqf7" }
}

pulsectl token list --all

pulsectl token revoke 0d9f6c1e-… --yes

Notifications

pulsectl notification test --recipient codex@superposition.app

CLI authorization

The device flow behind pulsectl auth login. You rarely call these directly, but they're documented for custom clients.

{
  "apiVersion": "v1",
  "kind": "DeviceAuthorization",
  "data": {
    "deviceCode": "d5c1…",
    "userCode": "BQTV-XKGF",
    "verificationUri": "https://pulse.superposition.app/cli/authorize",
    "verificationUriComplete": "https://pulse.superposition.app/cli/authorize?code=BQTV-XKGF",
    "expiresIn": 600,
    "interval": 5
  },
  "meta": { "requestId": "req_01j8zqf7" }
}

{
  "apiVersion": "v1",
  "kind": "CliSession",
  "data": {
    "token": "pulse_cli_…",
    "tokenType": "Bearer",
    "expiresAt": "2026-10-16T00:00:00Z",
    "scopes": ["monitors:read", "monitors:write", "…"]
  },
  "meta": { "requestId": "req_01j8zqf7" }
}

pulsectl auth unlink --yes

Database health

{
  "apiVersion": "v1",
  "kind": "DatabaseHealth",
  "data": {
    "health": "HEALTHY",
    "summary": "Storage remains within its configured budget",
    "budgetBytes": 500000000,
    "usedBytes": 118000000,
    "governor": {
      "mode": "FULL_DETAIL",
      "action": "None required",
      "lastCompactionAt": "2026-07-18T03:17:00Z"
    }
  },
  "meta": { "requestId": "req_01j8zqf7" }
}

curl -X POST https://pulse.superposition.app/api/v1/database-health/refresh \
  -H "Authorization: Bearer $PULSE_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"