Configure the TracePilot AI SDK for your TypeScript project

Set up your API key safely with environment variables, configure a custom ingest endpoint for self-hosted deployments, and enable TypeScript strict mode.

The TracePilot SDK requires only an API key to get started. Beyond that, you can point the SDK at a self-hosted ingest server and take advantage of TypeScript’s type system to catch configuration mistakes at compile time. This page covers all configuration options and the recommended patterns for each.

API key

Your API key authenticates every request the SDK sends to the TracePilot ingest endpoint. Keys always begin with tp_live_. Retrieve yours from the TracePilot dashboard.

Never hardcode your API key directly in source code. If the key is committed to a repository — even a private one — it can be exposed through git history, forks, or accidental leaks. Store it in an environment variable and read it at runtime.

Recommended pattern

Store the key in an environment variable named TRACEPILOT_API_KEY and reference it with process.env:

import { TracePilot } from 'tracepilot-sdk';

const tp = new TracePilot(process.env.TRACEPILOT_API_KEY!);

The ! non-null assertion tells TypeScript you have verified the variable is set. For stricter runtime validation, check the value explicitly:

import { TracePilot } from 'tracepilot-sdk';

const apiKey = process.env.TRACEPILOT_API_KEY;
if (!apiKey) {
  throw new Error('TRACEPILOT_API_KEY environment variable is not set.');
}

const tp = new TracePilot(apiKey);

Use dotenv to load environment variables from a .env file during local development. Add .env to your .gitignore immediately. In production, use your runtime’s native secret management — for example, AWS Secrets Manager, Vercel environment variables, or Kubernetes secrets.

Loading with dotenv

import 'dotenv/config'; // loads .env into process.env
import { TracePilot } from 'tracepilot-sdk';

const tp = new TracePilot(process.env.TRACEPILOT_API_KEY!);

Your .env file:

.env

TRACEPILOT_API_KEY=tp_live_xxxxxxxxxxxxxxxx

Custom ingest endpoint

By default, the SDK sends trace data to the TracePilot cloud. If you run a self-hosted TracePilot server, pass your server’s ingest URL as the second argument to the constructor:

import { TracePilot } from 'tracepilot-sdk';

const tp = new TracePilot(
  process.env.TRACEPILOT_API_KEY!,
  process.env.TRACEPILOT_ENDPOINT ?? 'https://your-server.com/api/ingest'
);

Store the endpoint URL in an environment variable so you can switch between environments (local, staging, production) without touching source code.

TypeScript setup

The SDK ships with full TypeScript types. No additional @types packages are required. Install the SDK and you’re ready:

npm install tracepilot-sdk

For strict null checking — recommended — enable strictNullChecks in your tsconfig.json:

tsconfig.json

{
  "compilerOptions": {
    "strict": true,
    "strictNullChecks": true
  }
}

With strict mode enabled, TypeScript will warn you if process.env.TRACEPILOT_API_KEY could be undefined, prompting you to add the runtime check shown above.

Environment variable reference

Variable	Required	Description
TRACEPILOT_API_KEY	Yes	Your tp_live_... API key from the dashboard.
TRACEPILOT_ENDPOINT	No	Custom ingest URL for self-hosted deployments.