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.

Configure the Mortem SDK by passing a MortemConfig object to the Mortem constructor. Most options have sensible defaults so you only need to supply your API key and agent ID to get started. Use SessionOptions each time you call mortem.startSession() to describe the individual agent run.

​
MortemConfig

Pass these options when you instantiate the Mortem client. Options marked required must be present or the SDK disables itself silently. 
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, // remove after first run
  environment: "devnet",
  ingestUrl: process.env.MORTEM_INGEST_URL,
})
​
apiKey
string
required
Your agent API key, shown once during onboarding in the dashboard. If this value is an empty string the SDK disables itself and logs a warning through your configured logger.
​
agentId
string
Your agent’s unique identifier, copied from the dashboard. Defaults to "unknown" when omitted. Mortem uses this to route traces to the correct agent in the dashboard and to match the verify token on first run.
If you supply a verifyToken without an agentId, the SDK ignores the token and logs a warning. Always provide agentId alongside verifyToken.
​
verifyToken
string
A one-time token that proves you control this agent. The dashboard generates it during onboarding. Include it on the first run so the wizard can confirm the connection, then remove it from your environment and code — it cannot be reused.
The token is sent with the first batch flush and never again. After the dashboard shows the agent as verified, delete MORTEM_VERIFY_TOKEN from your .env file.
​
ingestUrl
string
default:"https://ingest.mortem.dev"
The URL of the Mortem ingest service. The default points to the hosted service. Override this in local development to point at your local ingest instance.
MORTEM_INGEST_URL=http://localhost:4001
​
environment
string
Tags every trace with the Solana environment your agent is running against. Accepted values are "devnet" and "mainnet". Traces appear in the dashboard filtered by environment, which helps you keep dev and production runs separate.
​
enabled
boolean
default:"true"
Set to false to disable the SDK without removing it from your code. Useful in CI pipelines or when you want to silence telemetry temporarily. When disabled, all SDK calls are no-ops and nothing is sent to ingest.
​
flushIntervalMs
number
default:"250"
How often (in milliseconds) the SDK automatically flushes its internal buffer to the ingest service. Lower values reduce the risk of losing events if the process exits unexpectedly. Higher values reduce network overhead.
​
maxBufferBytes
number
default:"102400"
The maximum size of the internal event buffer in bytes (default is 100 KB). When the buffer exceeds this limit, the SDK forces a flush before accepting more events. Increase this value if your traces contain large payloads.
​
logger
object
An optional logger for SDK diagnostics. The object must expose a warn(message: string, context?: Record<string, unknown>): void method. SDK errors are best-effort and never thrown into your agent runtime — they are routed to this logger instead.
const mortem = new Mortem({
  apiKey: process.env.MORTEM_API_KEY ?? "",
  logger: {
    warn(message, context) {
      console.warn("[mortem]", message, context)
    },
  },
})

​
SessionOptions

Pass these options to mortem.startSession() for each agent run. A session maps to a single trace in the dashboard. 
const session = await mortem.startSession({
  inputSummary: "Evaluate whether to swap 1 SOL for JUP",
  tags: ["swap", "devnet"],
})
​
inputSummary
string
required
A human-readable description of what this agent run is attempting to do. This becomes the trace title in the dashboard and in shared autopsy links. Write it in plain language — it is the first thing you see when reviewing a failed run.
​
tags
string[]
Labels you can use to filter and group traces in the dashboard. Add as many as you need. Common examples: strategy name, token pair, environment, run mode.
tags: ["sol-jup", "arbitrage", "devnet"]
​
traceId
string
Override the auto-generated trace ID. Use this when you need to correlate a Mortem trace with an ID from another system (for example, a job ID from your scheduling infrastructure). The SDK generates a ULID by default.
​
agentId
string
Override the client-level agentId for this session only. Useful when a single Mortem instance emits traces on behalf of multiple logical agents.
​
startedAt
Date
Backfill a start time for the trace. Use this when you want the trace timeline to reflect when your agent actually started rather than when startSession was called — for example, if you initialize Mortem after some startup work has already completed.

​
Payload encryption

Set the MORTEM_MASTER_KEY environment variable to enable AES-256-GCM encryption for all event payloads before they leave your process. Generate a key with: 
openssl rand -base64 32
Keep MORTEM_MASTER_KEY stable. If you rotate or lose the key, previously encrypted payloads cannot be decrypted. Refer to the encryption guide for key rotation procedures.