Configuration Guide

Relevant source files

The following files were used as context for generating this wiki page:

• status.config.example.yml
• packages/core/src/config.ts
• ARCHITECTURE.md
• README.md
• DEPLOYMENT.md

StatusBeam is designed around a "configuration-as-YAML" philosophy. The entire monitoring suite is driven by a single file, typically named status.config.yml. This configuration is validated at runtime by the Core package and stored within Cloudflare KV to ensure that the status page remains independent of the build process.

The configuration dictates how services are monitored, which notification channels are alerted on status changes, and how the frontend status page is branded and localized.

Sources: ARCHITECTURE.md:16-24, README.md:189-194, packages/core/src/config.ts:145-148

Configuration Architecture

StatusBeam uses a single YAML file as the source of truth for its operational logic. This file is parsed and validated using Zod schemas defined in packages/core/src/config.ts. Once validated, the configuration is uploaded to Cloudflare KV under the key config. Both the check Worker (producing data) and the Astro site (consuming data) read from this KV key.

The diagram above illustrates the lifecycle of the configuration from a local YAML file to its runtime utilization at the edge.
Sources: ARCHITECTURE.md:95-98, packages/core/src/config.ts:145-152

Site Monitoring Configuration

The sites block is an array of objects defining which services to monitor. StatusBeam supports several check types, ranging from simple HTTP probes to mirroring third-party status pages.

Check Types and Options

Each site must specify a check kind. The system currently supports:

• http: Standard HTTP(S) request.
• statuspage: Mirrors an Atlassian Statuspage.
• incidentio: Mirrors an incident.io status page.
• sentry: Integrates with Sentry Uptime monitors.

Field	Type	Default	Description
name	string	-	Human-readable name of the service.
url	string (url)	-	The endpoint to probe or the base URL of a status page.
check	enum	http	Kind of check: http, tcp, ssl, statuspage, incidentio, sentry.
method	string	GET	HTTP method for http checks.
expectedStatusCodes	number[]	[200]	Status codes treated as "up".
maxResponseTime	number	5000	Threshold in ms; higher values mark the site as "degraded".
slug	string	slugify(name)	URL-safe identifier for the site.

Sources: packages/core/src/config.ts:13-73, status.config.example.yml:6-12

Specialized Adapters

For statuspage and incidentio, the system can target specific components. For sentry, a specific configuration block is required to enable the poll backstop.

The class diagram shows the relationship between a general site definition and the specialized Sentry configuration.
Sources: packages/core/src/config.ts:25-42, packages/core/src/config.ts:80-94

Notifications Configuration

The notifications block defines how and where alerts are sent when a service status changes. StatusBeam supports immediate delivery or a decoupled queue-based delivery for reliability.

Delivery Methods

• inline (default): Directly POSTs to targets during the check run. It is best-effort and does not include retries.
• queue: Enqueues notification events to Cloudflare Queues, enabling automatic retries and dead-lettering.

Notification Targets

Target	Configuration Field	Description
Slack	slack.webhookUrl	The incoming webhook URL for a Slack channel.
Generic Webhooks	webhooks	An array of URLs to receive a POST payload on status changes.

Sources: packages/core/src/config.ts:108-132, status.config.example.yml:51-64

Theme and Localization

The theme block controls the visual appearance and the default language of the status page.

Option	Type	Default	Description
logoUrl	string	-	URL to a custom logo image.
darkMode	boolean	true	Enables/disables the dark mode theme.
locale	enum	en	Fallback language: en, zh, ja, or ko.

Sources: packages/core/src/config.ts:134-143, status.config.example.yml:66-73

Configuration Management

Configuration is handled via the StatusBeam CLI. Users should not modify the system code to change their status page; instead, they edit the YAML file and use the following workflow:

1. Edit: Modify status.config.yml.
2. Upload: Use statusbeam deploy (or statusbeam setup during initial provisioning).
3. Storage: The CLI uploads the file to the config key in the STATUS_KV namespace.
4. Validation: The Core package ensures the YAML adheres to the StatusConfig Zod schema before it is accepted by the Workers.

Sources: DEPLOYMENT.md:30-45, ARCHITECTURE.md:104-106

Summary

The StatusBeam configuration system enables a declarative approach to service monitoring and status reporting. By centralizing all logic—from probe thresholds to notification delivery—into a single, validated YAML file stored at the edge, the system maintains high performance and reliability even during infrastructure outages.

Sources: README.md:189-195, ARCHITECTURE.md:104-108