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

# Install and configure @mortemlabs/sdk in your agent

> Install @mortemlabs/sdk in your TypeScript agent, configure your API key and agent ID, and create a Mortem client to start capturing traces.

The Mortem SDK is the single package your agent needs to start sending traces. Install it, set your credentials, and create a client — that is everything required before you start recording sessions and events.

## Install the package

<CodeGroup>
  ```bash npm theme={null}
  npm install @mortemlabs/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @mortemlabs/sdk
  ```

  ```bash yarn theme={null}
  yarn add @mortemlabs/sdk
  ```
</CodeGroup>

The SDK has no hard dependency on OpenAI, Anthropic, Ollama, the Vercel AI SDK, LangChain, or the Solana web3.js library. Instrumentation wrappers use structural typing, so your agent only pays the cost of the providers it actually imports.

## Set environment variables

Add these variables to your agent's environment before starting the process.

<ParamField path="MORTEM_API_KEY" type="string" required>
  Your agent's API key, available from the dashboard under **Agent settings**. An empty string disables the SDK entirely without throwing an error.
</ParamField>

<ParamField path="MORTEM_AGENT_ID" type="string">
  The agent ID shown in the dashboard. Used to associate traces with the correct agent. If you omit it here you can also pass it to `new Mortem({ agentId })` or to `startSession({ agentId })`.
</ParamField>

<ParamField path="MORTEM_VERIFY_TOKEN" type="string">
  A one-time token shown during the onboarding wizard. Include it on the first run so Mortem can verify agent ownership. Remove it from your environment and code once the dashboard shows the agent as verified.
</ParamField>

<ParamField path="MORTEM_INGEST_URL" type="string">
  The URL of the ingest service. Defaults to `https://ingest.mortem.dev`. Override this only when running ingest locally — for example, `http://localhost:4001`.
</ParamField>

A minimal `.env` for local development:

```bash .env.local theme={null}
MORTEM_API_KEY=your_api_key_here
MORTEM_AGENT_ID=your_agent_id_here
MORTEM_VERIFY_TOKEN=your_verify_token_here   # remove after first successful connection
MORTEM_INGEST_URL=http://localhost:4001
```

<Note>
  `MORTEM_VERIFY_TOKEN` is sent only once, on the first flush after the client is initialized. After the onboarding wizard confirms the agent is verified, you can safely delete the variable.
</Note>

## Create the client

Instantiate `Mortem` once at the top of your agent entry point and reuse the same instance for every session.

```ts agent.ts theme={null}
import { Mortem } from "@mortemlabs/sdk"

const mortem = new Mortem({
  apiKey: process.env.MORTEM_API_KEY ?? "",
  agentId: process.env.MORTEM_AGENT_ID,
  verifyToken: process.env.MORTEM_VERIFY_TOKEN,
  environment: "devnet",
  ingestUrl: process.env.MORTEM_INGEST_URL,
})
```

Call `mortem.close()` when the process exits to flush any buffered data:

```ts agent.ts theme={null}
try {
  // agent work
} finally {
  await mortem.close()
}
```

### Configuration reference

<ParamField path="apiKey" type="string" required>
  Your agent's API key. Pass an empty string to disable the SDK without crashing — useful for local development where you have not yet created a Mortem agent.
</ParamField>

<ParamField path="agentId" type="string">
  Agent identifier. Can also be supplied per-session via `startSession({ agentId })`, which overrides the client-level value.
</ParamField>

<ParamField path="verifyToken" type="string">
  One-time ownership verification token from the onboarding wizard. Ignored unless `agentId` is also set.
</ParamField>

<ParamField path="ingestUrl" type="string">
  Ingest endpoint. Defaults to `https://ingest.mortem.dev`. Override for local development only.
</ParamField>

<ParamField path="environment" type="&#x22;devnet&#x22; | &#x22;mainnet&#x22; | &#x22;localnet&#x22;">
  Tags every trace with the Solana cluster your bot is targeting. Helps filter traces in the dashboard.
</ParamField>

<ParamField path="enabled" type="boolean">
  Set to `false` to disable all SDK behavior without removing the code. Defaults to `true`.
</ParamField>

<ParamField path="logger" type="MortemLogger">
  Optional logger that receives SDK warnings. Must implement `warn(message: string, context?): void`. SDK errors are never thrown into agent code, but they will be forwarded here if a logger is provided.
</ParamField>

<ParamField path="flushIntervalMs" type="number">
  How often the buffer is flushed to the ingest service in milliseconds. Defaults to `250`.
</ParamField>

<ParamField path="maxBufferBytes" type="number">
  Maximum buffer size in bytes before an early flush is triggered. Defaults to `102400` (100 KB).
</ParamField>

<Tip>
  The default ingest URL (`https://ingest.mortem.dev`) is correct for production. Set `MORTEM_INGEST_URL` only when you are running the ingest service locally.
</Tip>