Quickstart

Four install paths. Same dashboard, same privacy model, same API. Pick the one that matches what you’re building.

Step 1 — Install

A · Coding agent (Claude Code, Cursor)

A wizard writes the right hooks and env into your IDE’s config. No code changes.

npx -y @voightxyz/sdk setup

Verified working today: Claude Code and Cursor — the wizard auto-detects which one you’re running. Codex integration is in an active fix cycle (Codex’s sandbox blocks the hooks from reaching the SDK reliably); the wrapper exists and the changelog tracks attempts, but it isn’t a target we’d recommend installing right now.

B · Autonomous agent (ElizaOS, Solana Agent Kit, custom)

Install the SDK as a library and call voight.log() from your agent code.

npm install @voightxyz/sdk

import { voight } from '@voightxyz/sdk'

voight.init({ key: process.env.VOIGHT_KEY })

await voight.log({
  kind: 'decision',
  agentId: 'my-trading-bot',
  input: 'should I rebalance?',
})

Full reference in Library mode.

C · Production LLM app (OpenAI / Anthropic in user-facing flows)

If your app already uses openai or @anthropic-ai/sdk (or both), wrap your clients once and every model call is captured — prompts, tokens, cache reads, tool calls, latency, errors. Per-user spend attribution with one extra line of code. Two ways to install: C1 · Wizard (recommended — 30 seconds)

cd your-app
npx -y @voightxyz/sdk init

The wizard detects openai and @anthropic-ai/sdk in your package.json, asks for your Voight API key, validates it against api.voight.xyz, and writes src/lib/voight.ts with the wrapped clients ready to import. Tailors the usage snippet to your framework (Next.js or vanilla) and prints the right install command for your package manager (pnpm / yarn / bun / npm). Provider keys (OPENAI_API_KEY / ANTHROPIC_API_KEY) stay in your app’s env — Voight never sees them. Full deep-dive in Wizard. C2 · Manual (you prefer to wire it yourself) Skip the wizard and install the wrappers directly:

# pick the one matching your provider (or both)
npm install openai @voightxyz/openai
npm install @anthropic-ai/sdk @voightxyz/anthropic

import OpenAI from 'openai'
import { wrapOpenAI, withTrace } from '@voightxyz/openai'

const openai = wrapOpenAI(new OpenAI(), {
  agent: 'production-chat-api',
  privacy: 'standard',
})

app.post('/api/chat', async (req, res) => {
  await withTrace(
    async () => {
      const reply = await openai.chat.completions.create({
        model: 'gpt-4o-mini',
        messages: [{ role: 'user', content: req.body.prompt }],
      })
      res.json({ reply })
    },
    {
      routeTag: 'POST /api/chat',
      tags: { userId: req.user.id, plan: req.user.plan },
    },
  )
})

Set VOIGHT_KEY in your runtime environment (or in .env.local). The tags map drives per-user spend tracking — the dashboard’s Users sub-tab populates with per-customer cost as soon as your first request lands. Full reference: OpenAI SDK · Anthropic SDK.

D · Any language over HTTP

For Python, Go, Rust, or anything that speaks JSON — POST events directly, no SDK required.

curl https://api.voight.xyz/v1/events \
  -H "authorization: Bearer $VOIGHT_KEY" \
  -H "content-type: application/json" \
  -d '{ "kind": "decision", "agentId": "my-agent", "input": "hello" }'

Full schema in the HTTP API reference.

Step 2 — Pick your privacy level

For path A the wizard prompts you. For path B pass it on voight.init({ privacy: 'standard' }). For path C set it on wrapOpenAI(..., { privacy: 'standard' }). For path D include metadata.privacyLevel on each request — scrubbing is your responsibility on the raw HTTP path.

Minimal — metadata only. No prompts, responses, file paths, cwd, or git context leave your machine.
Standard ★ — full content with local PII scrubbing. Credentials and personal info redacted before transmission.
Full — everything captured as-is.

The privacy overview breaks down what each level keeps, scrubs, or drops, field by field.

Step 3 — Generate your API key

When the wizard asks for a key — or before you initialize the library / send your first request — open voight.xyz/dashboard/settings and click + Generate key. Copy the vk_... secret. You’ll only see it once, so save it to a password manager. Paste it into the wizard, or set it as VOIGHT_KEY in your runtime environment.

Step 4 — You’re connected

Open voight.xyz/dashboard. Within seconds you should see:

A new agent in the Agents list (auto-named from your install path, renameable)
Events streaming in Overview and Audit log
Token counts, cost USD, and model tags on each event
A per-event privacy chip (MIN / STD / FULL) confirming which level captured it

For path C (App SDKs): also open voight.xyz/dashboard/ai-apps for the dedicated production-app surface — Overview / Traces / Models / Tools / Users. The Users sub-tab populates as soon as you pass tags.userId inside withTrace. See AI Apps overview for the full surface.

Non-TTY install for path A

If stdin isn’t an interactive TTY (running the wizard from inside a chat agent, CI, or any non-interactive shell), setup runs in 3-step progressive mode instead of an interactive prompt:

# See the menu
npx -y @voightxyz/sdk setup

# Pick a privacy level
npx -y @voightxyz/sdk setup --privacy=2

# Paste your key
npx -y @voightxyz/sdk setup --privacy=2 --key=vk_YOUR_KEY

Each step prints instructions and exits cleanly. The chain reads naturally for both humans and AI agents.

Troubleshooting

Events aren't showing up

Confirm the SDK version: npx -y @voightxyz/sdk@latest --version (should be 0.4.2 or higher).
For path A — check your IDE’s settings file (~/.claude/settings.json for Claude Code): env.VOIGHT_KEY should be set and hooks should contain entries calling npx -y @voightxyz/sdk hook. Restart your IDE afterwards — hooks are read on startup.
For path B / C — confirm your code is actually calling voight.log() or POSTing, and that VOIGHT_KEY is set in the runtime environment.
Check the dashboard’s Audit log for the most recent events — they should appear within ~2 seconds of being sent.

npx serves an old SDK version

Force the latest with an explicit version:

npx -y @voightxyz/sdk@0.4.2 setup

Or clear the npx cache:

rm -rf ~/.npm/_npx

The SDK isn't capturing my prompts

You’re probably on Minimal mode, which strips content fields by design. Re-run setup with Standard or Full:

npx -y @voightxyz/sdk setup --privacy=standard

Or for path B / C, pass the level on voight.init({ privacy: 'standard' }).

My IDE shows a warning about the package

Some coding agents flag unfamiliar packages installed with -y for safety. The two-line copy block in your dashboard onboarding includes a framing line (“Set up Voight observability here:”) that gives the agent the intent it needs to skip the warning.

Concepts → Events — the data model
Privacy overview — pick the right level for your workflow
Library mode — deep dive on path B
OpenAI SDK · Anthropic SDK — deep dive on path C
Per-user spend — one line of code to attribute cost per end-user
HTTP API — deep dive on path D

Getting started

Concepts

AI Apps

Python

Integrations

Install paths

Reference

Resources

Step 1 — Install

A · Coding agent (Claude Code, Cursor)

B · Autonomous agent (ElizaOS, Solana Agent Kit, custom)

C · Production LLM app (OpenAI / Anthropic in user-facing flows)

D · Any language over HTTP

Step 2 — Pick your privacy level

Step 3 — Generate your API key

Step 4 — You’re connected

Non-TTY install for path A

Troubleshooting

Next

​Step 1 — Install

​A · Coding agent (Claude Code, Cursor)

​B · Autonomous agent (ElizaOS, Solana Agent Kit, custom)

​C · Production LLM app (OpenAI / Anthropic in user-facing flows)

​D · Any language over HTTP

​Step 2 — Pick your privacy level

​Step 3 — Generate your API key

​Step 4 — You’re connected

​Non-TTY install for path A

​Troubleshooting

​Next

Step 1 — Install

A · Coding agent (Claude Code, Cursor)

B · Autonomous agent (ElizaOS, Solana Agent Kit, custom)

C · Production LLM app (OpenAI / Anthropic in user-facing flows)

D · Any language over HTTP

Step 2 — Pick your privacy level

Step 3 — Generate your API key

Step 4 — You’re connected

Non-TTY install for path A

Troubleshooting

Next