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

# 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](https://tracepilotai.com/dashboard).

<Warning>
  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.
</Warning>

### Recommended pattern

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

```typescript theme={null}
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:

```typescript theme={null}
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);
```

<Tip>
  Use [dotenv](https://github.com/motdotla/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.
</Tip>

### Loading with dotenv

```typescript theme={null}
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:

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

```typescript theme={null}
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:

```bash theme={null}
npm install tracepilot-sdk
```

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

```json tsconfig.json theme={null}
{
  "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. |