Voight

https://docs.voight.xyz
Admin
Voight is an observability and debugging platform for AI agents, autonomous systems, and production...
Tokens:84,051
Snippets:759
Trust Score:5.2
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Quickstart with bitfrost.quickstart

Source: https://docs.voight.xyz/python/bitfrost

One-line setup that auto-detects installed LLM libraries and streams events to the terminal with tokens, latency, and estimated cost. No network calls or account required.

```python
import bitfrost

bitfrost.quickstart(agent="my-app")   # auto-detects openai / anthropic / litellm / smolagents
```

--------------------------------

### npx setup command with --privacy flag

Source: https://docs.voight.xyz/changelog

Example command shown in the welcome menu for non-TTY installs. Instructs users to re-run setup with a privacy level flag, e.g., Standard.

```bash
npx -y @voightxyz/sdk setup --privacy=2
```

--------------------------------

### bitfrost.quickstart(agent)

Source: https://docs.voight.xyz/python/bitfrost

One-line setup that auto-detects supported LLM libraries and starts streaming events to the terminal.

```APIDOC
## bitfrost.quickstart(agent)

### Description
Initializes bitfrost with automatic detection of installed LLM libraries (openai, anthropic, litellm, smolagents) and starts streaming events to the terminal.

### Method
Function

### Signature
`bitfrost.quickstart(agent: str) -> None`

### Parameters
- **agent** (string) - Required - Identifier for the agent or application.

### Usage Example
```python
import bitfrost
bitfrost.quickstart(agent="my-app")
```

### Notes
- No network calls or account required.
- Output is color-coded with tokens, latency, and estimated cost.
```

--------------------------------

### Setup with the wizard (recommended)

Source: https://docs.voight.xyz/sdk/codex

Run this command to start the Voight setup wizard for Codex. The wizard prompts for your privacy level and Voight API key, then writes the [otel] block to ~/.codex/config.toml. A backup of your previous config is saved as config.toml.voight-backup. Restart Codex after setup.

```bash
npx -y @voightxyz/sdk setup --target=codex

```

--------------------------------

### Install Voight SDK via npx setup command

Source: https://docs.voight.xyz/quickstart

Run this command to start the Voight SDK setup wizard for coding agents like Claude Code, Cursor, or Codex. The wizard auto-detects the agent or accepts a --target flag.

```bash
npx -y @voightxyz/sdk setup
```

--------------------------------

### Initialize Voight SDK in production app

Source: https://docs.voight.xyz/quickstart

Run this command in your app directory to start the Voight setup wizard for production LLM apps using OpenAI or Anthropic. The wizard detects the SDKs and configures the wrappers.

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

--------------------------------

### Vercel AI SDK init session with telemetry activation and exporter install

Source: https://docs.voight.xyz/ai-apps/wizard

Example terminal session for `npx @voightxyz/sdk init` when `ai` is detected in package.json. Shows the wizard output, the code to add to `app/api/chat/route.ts` to enable telemetry with `experimental_telemetry`, and the command to install the Voight exporter (`pnpm add @voightxyz/vercel-ai @vercel/otel`). The metadata object populates `metadata.tags.*` in Voight, with `userId` powering the Users sub-tab.

```text
$ cd ~/projects/ai-chatbot
$ npx -y @voightxyz/sdk init

  Voight · init → /Users/jane/projects/ai-chatbot

  ✓ Detected providers: ai (^6.0.0) + openai (^4.79.2)
    (using the Vercel AI SDK path — covers both)
  ✓ Detected package manager: pnpm
  ✓ Detected framework: Next.js

  ✓ Privacy: standard
  ✓ Key valid
  ✓ Agent: production-chat-api

  ✓ Wrote instrumentation.ts
  ✓ Created .env.local with VOIGHT_KEY

  Activate telemetry on your existing calls:

    // app/api/chat/route.ts
    import { openai } from '@ai-sdk/openai'
    import { streamText } from 'ai'

    export async function POST(req: Request) {
      const result = streamText({
        model: openai('gpt-4o-mini'),
        prompt: (await req.json()).prompt,
        experimental_telemetry: {
          isEnabled: true,
          metadata: { userId: 'user_123', plan: 'pro' },
        },
      })
      return result.toAIStreamResponse()
    }

  Per-user attribution: anything you put in `metadata` shows up
  under `metadata.tags.*` in Voight — `userId` powers the Users sub-tab.

  One more step — install the Voight exporter:
    pnpm add @voightxyz/vercel-ai @vercel/otel

  Then open https://voight.xyz/dashboard/ai-apps
```

--------------------------------

### Setup wizard command

Source: https://docs.voight.xyz/privacy/overview

Runs the Voight SDK setup wizard to configure privacy level interactively.

```bash
npx -y @voightxyz/sdk setup

```

--------------------------------

### Run Voight SDK init and capture example session output

Source: https://docs.voight.xyz/ai-apps/wizard

Shows the full interactive terminal session when running `npx -y @voightxyz/sdk init` in a Next.js project. It demonstrates provider detection, privacy level selection, API key validation, agent naming, file generation, and the final install command. The session ends with a link to the dashboard and the generated handler code.

```text
$ cd ~/projects/customer-support-saas
$ npx -y @voightxyz/sdk init

  Voight · init → /Users/jane/projects/customer-support-saas

  ✓ Detected providers: openai (^4.79.2) + @anthropic-ai/sdk (^0.96.0)
  ✓ Detected package manager: pnpm
  ✓ Detected framework: Next.js

  Privacy level for this project?

    1) Minimal · metadata only (tokens, latency, cost)
    2) Standard ★ Required for customer-facing apps — PII scrubbing on
    3) Full · raw, no scrubbing (debugging only)

  > 2

  ✓ Privacy: standard

  Now we need your Voight API key:
    1. Open → https://voight.xyz/dashboard
    2. Sign in (Google / X / wallet)
    3. Settings → Generate key → copy the vk_… secret

  Paste it here: vk_aBcD…

  ✓ Validating key with api.voight.xyz…
  ✓ Key valid

  Agent name (defaults to "customer-support-saas")? production-chat-api

  ✓ Agent: production-chat-api

  ✓ Wrote src/lib/voight.ts
  ✓ Created .env.local with VOIGHT_KEY

  Use it in your handlers:

    // app/api/route.ts
    import { openai, withTrace } from '@/lib/voight'

    export async function POST(req: Request) {
      return withTrace(
        async () => {
          const r = await openai.chat.completions.create({ ... })
          return Response.json({ reply: r.choices[0].message })
        },
        {
          routeTag: 'POST /api/chat',
          tags: { userId: 'user_123', plan: 'pro' },
        },
      )
    }

  One more step — install the wrappers:
    pnpm add @voightxyz/openai @voightxyz/anthropic

  Then open https://voight.xyz/dashboard/ai-apps
```

--------------------------------

### Install provider SDKs for troubleshooting

Source: https://docs.voight.xyz/ai-apps/wizard

Run these commands to install the OpenAI and Anthropic SDKs when the wizard reports that neither is detected. Required before re-running the wizard in a project that doesn't use either provider yet.

```bash
npm install openai
npm install @anthropic-ai/sdk

```

--------------------------------

### Install @voightxyz/nosana

Source: https://docs.voight.xyz/integrations/nosana

Install the SDK package via npm. Requires Node.js and npm.

```bash
npm install @voightxyz/nosana

```

--------------------------------

### Install Voight provider wrappers manually

Source: https://docs.voight.xyz/quickstart

Install the provider-specific wrapper packages for OpenAI and/or Anthropic. Choose the one matching your provider or install both.

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

--------------------------------

### Install openai and @voightxyz/openai

Source: https://docs.voight.xyz/ai-apps/openai

Installs the required packages. Requires Node.js 18+ (uses global fetch) and openai SDK 4.0.0+.

```bash
npm install openai @voightxyz/openai

```

--------------------------------

### Installation

Source: https://docs.voight.xyz/sdk/library-mode

Install the Voight SDK via npm. Requires Node.js 18+ or compatible runtimes.

```APIDOC
## Install

```bash
npm install @voightxyz/sdk
```

Requirements:
- Node.js 18+ (uses global `fetch`)
- Bun, Deno, browsers, and Cloudflare Workers all supported
```

--------------------------------

### Install bitfrost

Source: https://docs.voight.xyz/ai-apps/python

Installs the bitfrost package. Requires Python 3.10 or later.

```bash
pip install bitfrost

```

--------------------------------

### Re-run setup with Standard privacy

Source: https://docs.voight.xyz/quickstart

Re-run setup with Standard privacy to capture content fields that Minimal mode strips.

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

```

--------------------------------

### Install Voight SDK as a library

Source: https://docs.voight.xyz/quickstart

Install the @voightxyz/sdk package to use Voight in autonomous agents like ElizaOS or Solana Agent Kit.

```bash
npm install @voightxyz/sdk
```

--------------------------------

### Install @anthropic-ai/sdk and @voightxyz/anthropic

Source: https://docs.voight.xyz/ai-apps/anthropic

Installs the required packages. Requires Node.js 18+ and @anthropic-ai/sdk 0.30.0+.

```bash
npm install @anthropic-ai/sdk @voightxyz/anthropic

```

--------------------------------

### Install @voightxyz/vercel-ai and dependencies

Source: https://docs.voight.xyz/ai-apps/vercel-ai

Install the Voight exporter, Vercel AI SDK, OpenAI provider, and OpenTelemetry packages. Requires Node.js 18+, Vercel AI SDK 6.0.0+, and a Voight API key.

```bash
npm install ai @ai-sdk/openai @vercel/otel @voightxyz/vercel-ai

```

--------------------------------

### Install bitfrost with pip

Source: https://docs.voight.xyz/python/bitfrost

Install the core package, the extended CLI/TUI/web dashboard extras, or everything. Requires Python 3.10–3.13 and is MIT licensed.

```bash
pip install bitfrost                 # core
pip install 'bitfrost[cli,serve]'    # + CLI, TUI, and local web dashboard
pip install 'bitfrost[all]'          # everything
```

--------------------------------

### Install Voight SDK via npm

Source: https://docs.voight.xyz/sdk/library-mode

Install the @voightxyz/sdk package using npm. Requires Node.js 18+ with global fetch support; Bun, Deno, browsers, and Cloudflare Workers are also supported.

```bash
npm install @voightxyz/sdk

```

--------------------------------

### Check SDK version

Source: https://docs.voight.xyz/quickstart

Confirm the installed SDK version is 0.4.2 or higher.

```bash
npx -y @voightxyz/sdk@latest --version

```

--------------------------------

### Quickstart with VoightBackend

Source: https://docs.voight.xyz/ai-apps/python

Initializes bitfrost at your application's entrypoint. Auto-detects and instruments supported libraries (openai, anthropic, litellm, smolagents) and streams LLM calls to the Voight dashboard. VoightBackend reads the API key from the VOIGHT_KEY environment variable.

```python
import bitfrost
from bitfrost.backends.voight import VoightBackend

bitfrost.quickstart(agent="my-app", backend=VoightBackend())

```

--------------------------------

### Quick Start

Source: https://docs.voight.xyz/sdk/library-mode

Initialize the Voight client and log an event. The constructor accepts configuration options, and the log method sends event data to the backend.

```APIDOC
## Quick Start

```typescript
import { Voight } from '@voightxyz/sdk'

const voight = new Voight({
  agentId: 'trading-bot.sol',     // SNS domain recommended for autonomous agents
  apiKey: process.env.VOIGHT_KEY, // from voight.xyz/dashboard
})

await voight.log({
  reasoning: 'SOL/USDC spread 8bps — arb window open',
  toolExecuted: 'jupiter.swap',
  transaction: '4zK…9Fp',
  amount: { token: 'SOL', value: 1.5 },
  outcome: 'success',
})
```

Returns `{ ok: true, eventId, agentId }` on success, `{ ok: false, error: { code, message } }` on failure.
```

--------------------------------

### Quickstart with minimal privacy

Source: https://docs.voight.xyz/ai-apps/python

Enables the 'minimal' privacy level, which drops prompt and response content before anything leaves the process. Other levels are 'standard' (default) and 'off'. PII scrubbing (12 patterns plus Luhn) runs on outbound content.

```python
bitfrost.quickstart(agent="my-app", backend=VoightBackend(), privacy="minimal")

```

--------------------------------

### Initialize Voight SDK with npx

Source: https://docs.voight.xyz/ai-apps/vercel-ai

Run this command in your app directory to install and configure the Voight SDK. It detects the ai package, prompts for privacy level, Voight key, and agent name, then writes an instrumentation.ts file.

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

```

--------------------------------

### Example prompts for Voight agents

Source: https://docs.voight.xyz/mcp/agents

Example natural language prompts that the assistant can handle, such as deploying research agents, checking usage, scheduling briefs, and deleting test agents.

```text
"Deploy three research agents, give each a topic, and merge what they find."
"Which of my agents are running, and how much did they use this week?"
"Schedule a daily 8:00 brief on my research agent."
"Delete the test agents we deployed this morning."

```

--------------------------------

### bitfrost CLI commands

Source: https://docs.voight.xyz/python/bitfrost

CLI commands for live tailing, replaying JSONL captures, querying SQLite, full-screen TUI, and local web dashboard.

```bash
bitfrost watch  capture.db        # live tail
bitfrost replay capture.jsonl     # re-render a captured run
bitfrost query  capture.db "SELECT model, COUNT(*) FROM events GROUP BY model"
bitfrost tui    capture.db        # full-screen terminal dashboard
bitfrost serve  capture.db        # local web dashboard
```

--------------------------------

### Correlate Nosana job and get attributes

Source: https://docs.voight.xyz/integrations/nosana

Import the SDK, call correlateNosana() to detect the job, then use nosanaAttributes() to get metadata attributes. Merge these into event metadata sent to Voight.

```javascript
import { correlateNosana, nosanaAttributes } from '@voightxyz/nosana'

const nosana = await correlateNosana()
if (nosana) {
  const attrs = nosanaAttributes(nosana)
  // { 'nosana.job_id': '…', 'nosana.state': 'RUNNING', 'nosana.market': '…', … }
  // merge attrs into the metadata of any event you send to Voight
}

```

--------------------------------

### GET /me/traces

Source: https://docs.voight.xyz/api-reference/me

Traces grouped by metadata.traceId.

```APIDOC
## GET /me/traces

### Description
Traces (grouped by `metadata.traceId`).

### Method
GET

### Endpoint
/me/traces

### Parameters
#### Query Parameters
- **since** (string) - Optional - Time range filter (e.g., `24h`, `7d`).

### Response
#### Success Response (200)
- **traces** (array) - List of trace objects.

#### Response Example
{}

```

--------------------------------

### GET /me/alerts

Source: https://docs.voight.xyz/api-reference/me

List active, acknowledged, or all alerts.

```APIDOC
## GET /me/alerts

### Description
Active / acknowledged / all alerts.

### Method
GET

### Endpoint
/me/alerts

### Parameters
#### Query Parameters
- **status** (string) - Optional - Filter by status (e.g., active, acknowledged).
- **count** (integer) - Optional - Number of alerts to return.

### Response
#### Success Response (200)
- **alerts** (array) - List of alert objects.

#### Response Example
{}

```

--------------------------------

### GET /me/errors

Source: https://docs.voight.xyz/api-reference/me

Error clusters grouped by fingerprint.

```APIDOC
## GET /me/errors

### Description
Error clusters (Sentry-style, grouped by fingerprint).

### Method
GET

### Endpoint
/me/errors

### Parameters
#### Query Parameters
- **since** (string) - Optional - Time range filter (e.g., `24h`, `7d`).

### Response
#### Success Response (200)
- **errors** (array) - List of error cluster objects.

#### Response Example
{}

```

--------------------------------

### Minimal example: wrapOpenAI and withTrace

Source: https://docs.voight.xyz/ai-apps/tracing

Wraps the OpenAI client with wrapOpenAI and uses withTrace to create a trace around a chat completion. Logs 'chat request received' and 'reply generated' events, which appear as one trace card in the dashboard.

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

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

app.post('/api/chat', async (req, res) => {
  await withTrace(
    async () => {
      log('chat request received', { userId: req.user.id })

      const reply = await openai.chat.completions.create({
        model: 'gpt-4o-mini',
        messages: [{ role: 'user', content: req.body.prompt }],
      })

      log('reply generated', { tokens: reply.usage?.total_tokens })

      res.json({ reply: reply.choices[0].message.content })
    },
    {
      routeTag: 'POST /api/chat',
      tags: { userId: req.user.id, plan: req.user.plan },
    },
  )
})
```
Tokens:
Raw