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.

New in v1.5.0 — 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.

Step 1 — Install the SDK

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:

.envbash
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.tstypescript
import { initAtlasBurnAuto } from "@atlasburn/sdk";

export function register() {
  if (process.env.ATLASBURN_KEY) {
    initAtlasBurnAuto({
      apiKey: process.env.ATLASBURN_KEY,
    });
  }
}

Node.js / Express / other runtimes

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

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

initAtlasBurnAuto({ apiKey: process.env.ATLASBURN_KEY });

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.tstypescript
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.tstypescript
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