Developer Documentation

RuntimeHQ Documentation

RuntimeHQ provides centralized operational runtime-state infrastructure specifically engineered for customer-facing web and mobile applications during incidents, maintenance events, and partial degraded outages.

By decoupling public banners and circuit fallbacks from standard databases and CI/CD redeploy pipelines, Incident Commanders can inject mitigation banners, routing controls, or safe system fallbacks in real-time.

Core Concepts

Quick Start SDK Setup

We provide official SDKs for both raw JavaScript/TypeScript environments and React. Explore our source code and repositories on GitHub:

npm install @theruntimehq/js

npm install @theruntimehq/react @theruntimehq/js

import { RuntimeHQClient } from "@theruntimehq/js";

const client = new RuntimeHQClient({
  runtimeKey: "rt_prod_xxxxx"
});

import { RuntimeHQProvider } from "@theruntimehq/react";

function App() {
  return (
    <RuntimeHQProvider 
      runtimeKey="rt_prod_xxxxx" 
      intervalSeconds={15}
    >
      <YourComponents />
    </RuntimeHQProvider>
  );
}

JS / TS SDK Integration Example

Query the runtime status directly using standard JavaScript/TypeScript. The SDK returns typed status indicators and handles local fallback caching under the hood:

import { RuntimeHQClient } from "@theruntimehq/js";

const client = new RuntimeHQClient({
  runtimeKey: "rt_prod_xxxxx"
});

async function checkStatus() {
  try {
    const runtime = await client.getRuntime();
    if (runtime.state !== "OPERATIONAL") {
      showBanner(runtime.message);
    }
  } catch (error) {
    console.error("Failed to fetch runtime status:", error);
  }
}

React SDK Integration Example

Consume dynamic state changes reactively within components. The hook automatically listens to state changes managed by the provider:

import { useRuntimeHQ, isOperational } from "@theruntimehq/react";

function RuntimeBanner() {
  const { runtime, loading, error } = useRuntimeHQ();

  if (loading || error) return null;
  if (!runtime || isOperational(runtime)) return null;

  return (
    <div className="runtime-banner">
      {runtime.message}
    </div>
  );
}

Next.js Integration Example

For maximum SEO indexability and server rendering compatibility, fetch dynamic state on the backend inside pre-rendering paths:

import { RuntimeHQClient } from "@theruntimehq/js";

const client = new RuntimeHQClient({
  runtimeKey: process.env.RUNTIMEHQ_RUNTIME_KEY!
});

export default async function Page() {
  const runtime = await client.getRuntime();

  return (
    <main>
      {runtime.state !== "OPERATIONAL" && (
        <div className="banner">
          ⚠️ {runtime.message}
        </div>
      )}
    </main>
  );
}

Runtime-State REST API Spec

For integrations outside the React/JS ecosystem, interact directly with our low-latency, edge-cached REST API endpoints. No authorization headers or credentials are required; simply include your API runtime key in the URL path.

{
  "applicationId": "app_019e8625-c3e4-7ab0-843e-730054f4efbe",
  "state": "RUNTIME_STATE_OPERATIONAL",
  "message": "All systems operational",
  "sourceType": "RUNTIME_STATE_SOURCE_OPERATIONAL",
  "startedAt": "2026-06-05T12:09:32.609Z",
  "updatedAt": "2026-06-05T12:09:32.611Z"
}

Runtime State Schema Reference

The standard fields delivered inside all REST payloads:

Environment-Specific Runtime Keys

RuntimeHQ strictly separates state metrics between production and non-production channels. These keys can be obtained for your respective application from the Console → Applications → Integration tab:

• Production keys (rt_prod_*): Tied to live edge caches and incident control dashboards.
• Non-production keys (rt_test_*): Dedicated for lower environments, testing banners, and preview workflows.

Runtime-State Testing

Validate banner rendering behaviors, customer warning layouts, and fallbacks by safely simulation testing runtime states.

By utilising non-production API keys or SDK dry-run profiles, engineering teams can conduct full disaster recovery rehearsals, verifying that public channels correctly present banners without triggering real incidents.

Recommended Caching Behavior

To balance propagation speed and edge API constraints, standard organizations should configure their SDK parameters based on:

Failure Handling Recommendations

RuntimeHQ SDK integrations are built to act as passive guardrails, ensuring that network interruptions or platform outages on the state control plane never impact your customers' core experiences.

Operational Workflows

The standard operating procedures implemented within the RuntimeHQ control panel:

System Auditability

RuntimeHQ enforces immutable audit trail tracking. Every incident creation, state transition, message modification, and targeting configuration change is logged permanently. Incident commanders or SRE teams can inspect complete history trails to compile post-incident reviews or timelines.

Planned Documentation Expansion

Future documentation sections are scheduled to cover advanced operational architectures: