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.
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.
# 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
# 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.
pip install shdwsdk export SHDW_API_KEY=shdw_live_...
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.
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://www.shdwsdk.ai/api/v1/otlp/v1/traces OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/json OTEL_EXPORTER_OTLP_TRACES_HEADERS=x-shdw-key=shdw_live_...
exporters:
otlphttp/shdw:
traces_endpoint: https://www.shdwsdk.ai/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.
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_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.
# 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
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.
# 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
Wraps standard completions and SSE streaming chunks in one line with zero latency impact.
import OpenAI from "openai";
import { ShdwTelemetryClient } from "@shdwsdk/sdk";
const shdw = new ShdwTelemetryClient({
apiKey: process.env.SHDW_API_KEY!,
endpoint: "https://www.shdwsdk.ai/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
Track Claude Sonnet 5.5 and Haiku 5.5 usage inside Next.js Route Handlers and Server Actions.
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)
Instrument your OpenAI or Anthropic client once and attribute each request to the customer it serves.
# 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
Inject credentials in Docker containers and automatically compile CycloneDX v1.7 & SPDX 3.0 AI-BOM files in CI/CD.
services:
ai-api-server:
build: .
environment:
- NODE_ENV=production
- SHDW_API_KEY=${SHDW_API_KEY}
- SHDW_GRID_REGION=us-west-2
restart: unless-stopped