2-Minute Developer & DevOps Setup
Zero Application Latency (1.5s Guard)
Windows · macOS · Linux · Docker

Install @shdwsdk/sdk on Any Operating System & Software Stack

Get started in 60 seconds using our interactive CLI setup wizard (npx @shdwsdk/sdk init or npx shdw-init), or follow the manual OS-specific instructions below for Microsoft Windows, Apple macOS, and Linux.

JavaScript SDK sourcePython SDK sourceMIT licensed · see exactly what the SDK sends
Recommended · 60-Second Setup
Windows · macOS · Linux

Quick Start: Interactive CLI Setup Wizard

Run one command in your project root. The wizard prompts for your shdw_live_* API key, lets you pick from 22 EU/global cloud regions and 11 featured AI models, safely updates .env or .env.local without touching other keys, generates src/lib/shdw.ts, and runs a live 1500ms connectivity test.

Run Interactive Wizard (npm / npx)
# 1. Install @shdwsdk/sdk and run the interactive setup wizard
npm install @shdwsdk/sdk
npx @shdwsdk/sdk init

# Or invoke the standalone CLI binary directly
npx shdw-init
Non-Interactive / CI Mode (Optional Flags)
# Pre-fill options via CLI flags for automated environments
npx shdw-init \
  --api-key shdw_live_your_key \
  --region eu-north-1 \
  --model claude-sonnet-5-5 \
  --out src/lib/shdw.ts

Python, OpenTelemetry and LiteLLM

Not on Node.js, or already tracing your AI calls? Use one of these instead of the JavaScript SDK. All of them send only model names and token counts; energy and carbon are computed on our side with the same methodology.

Python SDK

OpenAI and Anthropic clients, sync and async, including streaming.

Terminal
pip install shdwsdk
export SHDW_API_KEY=shdw_live_...
app.py
import shdwsdk
from openai import OpenAI

shdwsdk.init(grid_region="us-east-1")
client = shdwsdk.instrument(OpenAI())

# Optional: attribute calls to one of your customers
with shdwsdk.customer(account.id):
    client.chat.completions.create(model="gpt-5.4-mini", messages=msgs)

OpenTelemetry (no SDK)

Send existing GenAI spans (gen_ai.* attributes) from any language or an OpenTelemetry Collector. JSON encoding only.

Environment variables (any OpenTelemetry SDK)
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://www.shdwsdk.ai/eu/api/v1/otlp/v1/traces
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/json
OTEL_EXPORTER_OTLP_TRACES_HEADERS=x-shdw-key=shdw_live_...
otel-collector.yaml
exporters:
  otlphttp/shdw:
    traces_endpoint: https://www.shdwsdk.ai/eu/api/v1/otlp/v1/traces
    encoding: json
    headers:
      x-shdw-key: ${env:SHDW_API_KEY}
service:
  pipelines:
    traces:
      exporters: [otlphttp/shdw]

Optional span or resource attributes: shdw.customer_ref (your customer's account id), shdw.grid_region (otherwise cloud.region). Spans without token usage are ignored. If two instrumentations both record the same call, keep only one.

LiteLLM (SDK or proxy)

One callback covers every provider LiteLLM routes to.

Python
import litellm
from shdwsdk.integrations.litellm import ShdwLiteLLMLogger

litellm.callbacks = [ShdwLiteLLMLogger()]
litellm.completion(model="anthropic/claude-haiku-5-5", messages=msgs,
                   metadata={"shdw_customer_ref": account.id})
LiteLLM proxy config.yaml (pip install shdwsdk on the proxy)
litellm_settings:
  callbacks: shdwsdk.integrations.litellm.proxy_handler_instance

environment_variables:
  SHDW_API_KEY: os.environ/SHDW_API_KEY

1. Operating System Setup (Microsoft Windows, macOS, and Linux)

Select your operating system below for prerequisites, package manager commands, and environment variable configuration.

Step 1: Install Node.js LTS & Package Manager on Windows

Works on Windows 10, Windows 11, and Windows Server 2022+ using Windows Terminal, PowerShell, or WSL2.

PowerShell (Administrator) — Install Node.js 22 LTS via Winget
# Install Node.js LTS using the official Microsoft Winget package manager
winget install OpenJS.NodeJS.LTS

# Verify Node.js and npm versions
node --version
npm --version
PowerShell — Install @shdwsdk/sdk in Your Project Directory
cd C:\Projects\your-ai-application

# Using npm (recommended)
npm install @shdwsdk/sdk

# Or using pnpm / yarn / bun on Windows
pnpm add @shdwsdk/sdk
yarn add @shdwsdk/sdk
bun add @shdwsdk/sdk

Step 2: Configure Your SHDW API Key on Windows

Set your organization's API key in PowerShell, Command Prompt (CMD), or a local .env file.

Windows PowerShell & Command Prompt (CMD)
# Option A: Set for current PowerShell session
$env:SHDW_API_KEY="shdw_live_your_organization_key"
$env:SHDW_GRID_REGION="us-west-2"

# Option B: Persist across Windows user sessions (CMD / PowerShell)
setx SHDW_API_KEY "shdw_live_your_organization_key"

# Option C: Add to your project's .env file
echo SHDW_API_KEY=shdw_live_your_organization_key >> .env

2. Popular Software, Frameworks & AI Stack Integrations

Copy-and-paste production templates for the most common AI software stacks, frameworks, and developer tools.

OpenAI SDK + Node.js / Express / Fastify

Most Popular

Wraps standard completions and SSE streaming chunks in one line with zero latency impact.

src/lib/openai.ts
import OpenAI from "openai";
import { ShdwTelemetryClient } from "@shdwsdk/sdk";

const shdw = new ShdwTelemetryClient({
  apiKey: process.env.SHDW_API_KEY!,
  endpoint: "https://www.shdwsdk.ai/eu/api/v1/ingest-telemetry",
  defaultGridRegion: process.env.SHDW_GRID_REGION, // optional: unset uses your Settings region
  timeoutMs: 1500, // Strictly non-blocking 1.5s fail-silent guard
});

// Wrap your OpenAI client once and use it everywhere in your app
export const openai = shdw.wrapClient(new OpenAI(), {
  provider: "openai",
  gridRegion: "us-west-2",
});

Anthropic Claude + Next.js App Router

Next.js App Router

Track Claude Sonnet 5.5 and Haiku 5.5 usage inside Next.js Route Handlers and Server Actions.

app/api/assistant/route.ts
import Anthropic from "@anthropic-ai/sdk";
import { ShdwTelemetryClient } from "@shdwsdk/sdk";
import { NextResponse } from "next/server";

const shdw = new ShdwTelemetryClient({
  apiKey: process.env.SHDW_API_KEY!,
  defaultGridRegion: "us-west-2",
});

const anthropic = shdw.wrapClient(new Anthropic(), {
  provider: "anthropic",
});

export async function POST(req: Request) {
  const { prompt } = await req.json();
  const msg = await anthropic.messages.create({
    model: "claude-sonnet-5-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: prompt }],
  });
  return NextResponse.json(msg);
}

Python (FastAPI / Django / Flask)

Python 3.9+

Instrument your OpenAI or Anthropic client once and attribute each request to the customer it serves.

main.py (FastAPI)
# pip install shdwsdk   (reads SHDW_API_KEY)
import shdwsdk
from anthropic import Anthropic
from fastapi import FastAPI, Request

shdwsdk.init()
claude = shdwsdk.instrument(Anthropic())
app = FastAPI()

@app.post("/summarize")
async def summarize(req: Request):
    body = await req.json()
    with shdwsdk.customer(body["account_id"]):  # your customer's account id
        msg = claude.messages.create(
            model="claude-sonnet-5-5", max_tokens=512,
            messages=[{"role": "user", "content": body["text"]}],
        )
    return {"summary": msg.content[0].text}

Docker Compose & GitHub Actions CI/CD

DevSecOps & AI-BOM

Inject credentials in Docker containers and automatically compile CycloneDX v1.7 & SPDX 3.0 AI-BOM files in CI/CD.

docker-compose.yml
services:
  ai-api-server:
    build: .
    environment:
      - NODE_ENV=production
      - SHDW_API_KEY=${SHDW_API_KEY}
      - SHDW_GRID_REGION=us-west-2
    restart: unless-stopped