Configure the TracePilot AI SDK for your TypeScript project

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.

​API key

​Recommended pattern

​Loading with dotenv

​Custom ingest endpoint

​TypeScript setup

​Environment variable reference

API key

Recommended pattern

Loading with dotenv

Custom ingest endpoint

TypeScript setup

Environment variable reference