Skip to main content

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.

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

npm install @mortemlabs/sdk
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.
​
MORTEM_API_KEY
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.
​
MORTEM_AGENT_ID
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 }).
​
MORTEM_VERIFY_TOKEN
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.
​
MORTEM_INGEST_URL
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.
A minimal .env for local development:
.env.local
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
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.

​
Create the client

Instantiate Mortem once at the top of your agent entry point and reuse the same instance for every session.
agent.ts
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:
agent.ts
try {
  // agent work
} finally {
  await mortem.close()
}

​
Configuration reference

​
apiKey
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.
​
agentId
string
Agent identifier. Can also be supplied per-session via startSession({ agentId }), which overrides the client-level value.
​
verifyToken
string
One-time ownership verification token from the onboarding wizard. Ignored unless agentId is also set.
​
ingestUrl
string
Ingest endpoint. Defaults to https://ingest.mortem.dev. Override for local development only.
​
environment
"devnet" | "mainnet" | "localnet"
Tags every trace with the Solana cluster your bot is targeting. Helps filter traces in the dashboard.
​
enabled
boolean
Set to false to disable all SDK behavior without removing the code. Defaults to true.
​
logger
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.
​
flushIntervalMs
number
How often the buffer is flushed to the ingest service in milliseconds. Defaults to 250.
​
maxBufferBytes
number
Maximum buffer size in bytes before an early flush is triggered. Defaults to 102400 (100 KB).
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.