AtlasBurn
DocsPlatformIntegrationsOperationsReference

Quickstart

Summary

Get AtlasBurn capturing telemetry in under 60 seconds. This guide covers installation, initialization, and verification.

System maturity: Stable

The quickstart flow is production-ready across all supported runtimes.

Universal Framework Support

Initialize once at boot — AtlasBurn now automatically survives aggressive caching and request-cycle overrides from Next.js, Nuxt, and SvelteKit. No custom wrappers required.

Prerequisites

  • An AtlasBurn account with an API key (generated in the Integration Protocol dashboard)
  • Node.js, Vercel Edge, or a Chromium/WebKit browser runtime
  • At least one auto-captured provider: OpenAI, Anthropic, Google Gemini, or Google Vertex AI. Other priced providers (Meta/Llama, Mistral, DeepSeek, xAI, Cohere, OpenRouter) use the Edge Proxy.

Fastest setup — the abn CLI

The abn CLI ships inside the SDK, so install the package first — that also gives you the CLI. Then run abn init from your project root and it handles the key and wiring for you:

bash
npm install @atlasburn/sdk
npx abn init

abn init detects your framework and env file, auto-detects providers, asks for your ingest key (hidden input, sanitized + abn_-prefix validated), shows a diff of exactly what it will change and asks before writing, wires up initialization in the correct place (e.g. src/instrumentation.ts on Next.js), and runs a verification test. Use --dry-run to preview and --yes for CI. If it can't auto-detect your setup it falls back to a safe env-only setup and points you at the manual steps below.

Other commands (run via npx abn <cmd>):

  • abn test — verify your key + connectivity; sends one verification event
  • abn status — current guardrail state (active / throttled / suspended)
  • abn doctor — environment diagnostics + fixes

Prefer to wire it up by hand?

The manual steps below do exactly the same thing. Use them for full control, an unusual setup, or a framework the CLI doesn't auto-detect. After either path, continue with Step 4 (guardrails) and Step 5 (verify).

Manual setup

Wire it up yourself with the three steps below — the CLI above automates exactly this.

Step 1 — Install the SDK

bash
npm install @atlasburn/sdk

Step 2 — Set Your API Key

Generate an API key in your AtlasBurn dashboard under Integration Protocol. Store it as an environment variable:

.env
bash
ATLASBURN_KEY=abn_xxxxxxxxxxxxxxxxxxxx

Never commit API keys

Raw API keys are never stored by AtlasBurn. They are verified server-side via HMAC-SHA-256 hash comparison. Still, never commit them to source control.

Step 3 — Initialize at Your Entry Point

Call initAtlasBurnAuto at the boot level of your application — beforeany LLM call is made. The correct location depends on your runtime:

Do NOT initialize in layout.tsx

In the Next.js App Router, layout.tsx is subject to React caching and does not reliably patch server-side route handlers. The only supported way to initialize in Next.js is via src/instrumentation.ts.

Next.js (App Router) — required

Create an instrumentation.ts file in your src/ directory (or project root if not using src) and call initAtlasBurnAuto inside theregister() function:

src/instrumentation.ts
typescript
import { initAtlasBurnAuto } from "@atlasburn/sdk";

export function register() {
  // The if-guard narrows ATLASBURN_KEY from string | undefined to string, so this
  // type-checks under strict: true (no non-null ! needed). No key -> stays dormant.
  if (process.env.ATLASBURN_KEY) {
    initAtlasBurnAuto({ apiKey: process.env.ATLASBURN_KEY });
  } else {
    console.warn("[AtlasBurn] ATLASBURN_KEY not set - telemetry disabled.");
  }
}

Node.js / Express / other runtimes

Initialize at the very top of your entry file, before importing any AI provider libraries:

src/index.ts
typescript
import { initAtlasBurnAuto } from "@atlasburn/sdk";

// Initialize ONCE at the very top - BEFORE importing any AI provider SDK - so the
// fetch auto-patch is active before the first LLM call. The if-guard narrows
// ATLASBURN_KEY to string (type-safe under strict: true); no key -> stays dormant.
if (process.env.ATLASBURN_KEY) {
  initAtlasBurnAuto({ apiKey: process.env.ATLASBURN_KEY });
} else {
  console.warn("[AtlasBurn] ATLASBURN_KEY not set - telemetry disabled.");
}

import OpenAI from "openai"; // import providers AFTER init

Step 4 — Configure Budget Guardrails

In your AtlasBurn dashboard, configure dailyBudgetUsd under Safety Guardrails. This sets the deterministic limit that triggers the Auto Kill protocol if breached.

Step 5 — Verify Telemetry

Make any LLM API call. Open your AtlasBurn Forensic Ledger. You should see a telemetry pulse within ~5–10 seconds (the SDK flushes batches every ~5s).

verify.ts
typescript
import OpenAI from "openai";

const openai = new OpenAI();

const response = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello" }],
});

// Check your Forensic Ledger — the call is already tracked.

Or use this snippet to verify programmatically:

verify-sdk.ts
typescript
import { verifyAtlasBurn } from "@atlasburn/sdk";

await verifyAtlasBurn({
  apiKey: process.env.ATLASBURN_KEY,
  debug: true,
});

Expected result

A telemetry pulse appears in the Forensic Ledger within ~5–10 seconds of the LLM request, showing model, tokens, observed spend, and feature attribution.

Minimal Integration Checklist

  1. Generate API key in AtlasBurn dashboard
  2. Call initAtlasBurnAuto at the root entry point
  3. Configure dailyBudgetUsd in Safety Guardrails
  4. Verify telemetry in Forensic Ledger

Notes

  • The SDK is fire-and-forget — do not await the init call or it will add latency to your application
  • If telemetry doesn't appear, check the browser console for a "Pulse Sent" log message
  • Auto-detect works by monkey-patching globalThis.fetch — if you use a custom HTTP client or an unsupported provider, route through the Edge Proxy

Next Steps