> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voight.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get events from your agent or LLM app into the Voight dashboard in 30 seconds.

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.

```bash theme={null}
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.

```bash theme={null}
npm install @voightxyz/sdk
```

```ts theme={null}
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](/sdk/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)

```bash theme={null}
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](/ai-apps/wizard).

**C2 · Manual** (you prefer to wire it yourself)

Skip the wizard and install the wrappers directly:

```bash theme={null}
# pick the one matching your provider (or both)
npm install openai @voightxyz/openai
npm install @anthropic-ai/sdk @voightxyz/anthropic
```

```ts theme={null}
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](/concepts/per-user-spend) — the dashboard's **Users sub-tab** populates with per-customer cost as soon as your first request lands. Full reference: [OpenAI SDK](/ai-apps/openai) · [Anthropic SDK](/ai-apps/anthropic).

### D · Any language over HTTP

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

```bash theme={null}
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](/api-reference/events).

## 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](/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](https://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](https://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](https://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](/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:

```bash theme={null}
# 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

<AccordionGroup>
  <Accordion title="Events aren't showing up">
    1. Confirm the SDK version: `npx -y @voightxyz/sdk@latest --version` (should be 0.4.2 or higher).
    2. 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.
    3. For path B / C — confirm your code is actually calling `voight.log()` or POSTing, and that `VOIGHT_KEY` is set in the runtime environment.
    4. Check the dashboard's **Audit log** for the most recent events — they should appear within \~2 seconds of being sent.
  </Accordion>

  <Accordion title="npx serves an old SDK version">
    Force the latest with an explicit version:

    ```bash theme={null}
    npx -y @voightxyz/sdk@0.4.2 setup
    ```

    Or clear the npx cache:

    ```bash theme={null}
    rm -rf ~/.npm/_npx
    ```
  </Accordion>

  <Accordion title="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:

    ```bash theme={null}
    npx -y @voightxyz/sdk setup --privacy=standard
    ```

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

  <Accordion title="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](https://voight.xyz/dashboard/settings) includes a framing line ("Set up Voight observability here:") that gives the agent the intent it needs to skip the warning.
  </Accordion>
</AccordionGroup>

## Next

* [Concepts → Events](/concepts/events) — the data model
* [Privacy overview](/privacy/overview) — pick the right level for your workflow
* [Library mode](/sdk/library-mode) — deep dive on path B
* [OpenAI SDK](/ai-apps/openai) · [Anthropic SDK](/ai-apps/anthropic) — deep dive on path C
* [Per-user spend](/concepts/per-user-spend) — one line of code to attribute cost per end-user
* [HTTP API](/sdk/http-api) — deep dive on path D