> ## 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.

# Mortem SDK configuration reference for MortemConfig

> Complete reference for MortemConfig and SessionOptions — every option the SDK accepts, its type, default value, and when to use it.

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.

```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, // remove after first run
  environment: "devnet",
  ingestUrl: process.env.MORTEM_INGEST_URL,
})
```

<ParamField path="apiKey" type="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.
</ParamField>

<ParamField path="agentId" type="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.

  <Warning>
    If you supply a `verifyToken` without an `agentId`, the SDK ignores the token and logs a warning. Always provide `agentId` alongside `verifyToken`.
  </Warning>
</ParamField>

<ParamField path="verifyToken" type="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.

  <Note>
    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.
  </Note>
</ParamField>

<ParamField path="ingestUrl" type="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.

  ```bash theme={null}
  MORTEM_INGEST_URL=http://localhost:4001
  ```
</ParamField>

<ParamField path="environment" type="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.
</ParamField>

<ParamField path="enabled" type="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.
</ParamField>

<ParamField path="flushIntervalMs" type="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.
</ParamField>

<ParamField path="maxBufferBytes" type="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.
</ParamField>

<ParamField path="logger" type="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.

  ```ts theme={null}
  const mortem = new Mortem({
    apiKey: process.env.MORTEM_API_KEY ?? "",
    logger: {
      warn(message, context) {
        console.warn("[mortem]", message, context)
      },
    },
  })
  ```
</ParamField>

## `SessionOptions`

Pass these options to `mortem.startSession()` for each agent run. A session maps to a single trace in the dashboard.

```ts theme={null}
const session = await mortem.startSession({
  inputSummary: "Evaluate whether to swap 1 SOL for JUP",
  tags: ["swap", "devnet"],
})
```

<ParamField path="inputSummary" type="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.
</ParamField>

<ParamField path="tags" type="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.

  ```ts theme={null}
  tags: ["sol-jup", "arbitrage", "devnet"]
  ```
</ParamField>

<ParamField path="traceId" type="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.
</ParamField>

<ParamField path="agentId" type="string">
  Override the client-level `agentId` for this session only. Useful when a single `Mortem` instance emits traces on behalf of multiple logical agents.
</ParamField>

<ParamField path="startedAt" type="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.
</ParamField>

## 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:

```bash theme={null}
openssl rand -base64 32
```

<Warning>
  Keep `MORTEM_MASTER_KEY` stable. If you rotate or lose the key, previously encrypted payloads cannot be decrypted. Refer to the [encryption guide](/sdk/encryption) for key rotation procedures.
</Warning>