trAIce SDK
Documentation menu
DocsGetting started

Install Guide

Sign in, configure an SDK or collector, and send your first trAIce event.

View source

This is the canonical setup guide for trAIce. Use it for a fresh workspace, a new service, or an internal AI-tool collector rollout.

Prefer agent-assisted setup? Install the public skills and give your coding agent one prompt. See Coding-Agent Setup.

Before You Start

You need:

1. Sign In

Sign in at runtraice.com. A workspace is created automatically the first time you sign in.

2. Create An API Key

Open API keys, create a key, and store it in your secret manager or .env file.

Shell
TRAICE_API_KEY=your_workspace_key

The full key is shown once.

3. Send Product LLM Events

npm install @traice/sdk openai
import { configure, flush, meter } from "@traice/sdk";
import OpenAI from "openai";

configure({
  adapters: ["cloud"],
  cloudApiKey: process.env.TRAICE_API_KEY,
});

const openai = new OpenAI();

await meter(
  () =>
    openai.chat.completions.create({
      model: "gpt-4o-mini",
      messages: [{ role: "user", content: "Summarize this ticket" }],
    }),
  {
    tenantId: "customer_42",
    userId: "user_123",
    workflowId: "support",
  },
);
await flush();

tenantId is the key field for customer margin. Pass the customer or account id you bill on every product event.

4. Track Internal AI-Tool Spend

Internal Spend is separate from product events. The maintained collector supports Claude Code and Codex today. Send other employee or team usage through the authenticated internal-usage API until native connectors are available.

Install the local collector for Claude Code:

Shell
npx @traice/collector@latest setup

Setup starts browser authorization when needed, stores the renewable session in the operating system credential manager, patches selected agent settings, and installs a background user service. Rerunning it is safe. Add --no-browser for SSH, or --no-service if another process manager will run the collector. API keys remain supported for CI, containers, and other unattended automation. See Collector Overview for optional identity, subscription, backfill, server, and credential-storage parameters.

Restart every running coding-agent session after setup. Existing sessions do not reload the telemetry settings.

Send an internal usage row directly:

Shell
curl -X POST "https://www.runtraice.com/api/v1/internal-usage" \
  -H "authorization: Bearer $TRAICE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "sourceKey": "claude-code-local",
    "sourceName": "Claude Code local collector",
    "sourceKind": "claude_code_otel",
    "tool": "claude-code",
    "category": "coding_agent",
    "employeeEmail": "you@company.com",
    "employeeName": "Your Name",
    "teamName": "Engineering",
    "provider": "openai",
    "model": "gpt-5.5",
    "inputTokens": 42000,
    "cachedInputTokens": 38000,
    "outputTokens": 800,
    "costBasis": "usage_only"
  }'

Product events answer which customer or feature spent money. Internal Spend answers which employee, team, and AI tool spent money. Keep those identifiers separate.

5. Check The Dashboard

After the first product event lands, open the dashboard. For customer margin, add revenue rows under Settings -> Customer revenue.

For Internal Spend, open Dashboard -> Internal Spend after collector events arrive.

6. Ask From The CLI Or An MCP Client

Save the same workspace API key in the operating system credential store, then ask a question:

Shell
npm install --global @traice/sdk
export TRAICE_API_KEY="lm_live_..."
traice auth login
unset TRAICE_API_KEY
traice ask "top spend by feature in the last 7 days"

Workspace owners and admins can connect Slack from Settings -> Ask trAIce -> Add to Slack. See Ask trAIce for Slack, Cursor, VS Code, MCP, CLI, and direct API setup.

For an OAuth-capable MCP client, add https://www.runtraice.com/api/mcp without an authorization header. The client opens trAIce for sign-in and explicit workspace consent. API keys are the fallback for unattended MCP clients.

Next Steps