Configuration

Use configuration to control where events are sent, what content is recorded, and how safely the SDK delivers events in production.

When to use this

Use this page when you need to:

Send events to Lynx Cloud or a local backend
Attach workspace, agent, version, or environment metadata
Avoid sending raw prompts or responses
Tune delivery timeouts, queues, and circuit breaker behavior

Basic setup

import { LynxTracer } from "@lynxops/sdk";

const lynx = new LynxTracer({
  clientId: "support-api",
  apiKey: process.env.LYNX_API_KEY,
  workspaceId: "workspace_123",
  environment: "production",
  appVersion: "1.4.0",
});

endpoint defaults to https://api.lynxops.co. Use a custom endpoint only for local development or self-hosted deployments.

const lynx = new LynxTracer({
  clientId: "support-api",
  endpoint: "http://localhost:4000",
  apiKey: process.env.LYNX_API_KEY,
});

Issue reporting

Issue reporting is disabled until issueReporting.enabled is explicitly set to true. Runtime configuration can provide prompts and firewall policies, but it does not enable issue reporting by itself.

const lynx = new LynxTracer({
  clientId: "support-api",
  apiKey: process.env.LYNX_API_KEY,
  issueReporting: {
    enabled: true,
    reportRunFailures: true,
    reportLlmFailures: true,
    slowLlmThresholdMs: 10_000,
    slowLlmConsecutiveOccurrences: 2,
    recoverySuccessThreshold: 3,
  },
});

Option	Default	Description
`enabled`	`false`	Sends supported detections to the asynchronous issue review pipeline.
`reportRunFailures`	`true`	Reports unhandled root Run errors and explicit failed outcomes.
`reportLlmFailures`	`true`	Reports errors raised by instrumented LLM calls.
`slowLlmThresholdMs`	`10000`	Marks an instrumented LLM call as slow. Set `0` to disable slow detection.
`slowLlmConsecutiveOccurrences`	`2`	Consecutive slow calls required before sending one issue candidate.
`recoverySuccessThreshold`	`3`	Healthy observations required before sending a recovery record.

Capture options

Option	Default	Description
`sampleRate`	`1`	Fraction of runs to record, from `0` to `1`.
`captureInput`	`true`	Whether input fields may be recorded.
`captureOutput`	`true`	Whether output fields may be recorded.
`captureMode`	`"smart"`	`full`, `metadata-only`, or `smart`.
`maxPayloadLength`	—	Backward-compatible per-string truncation limit.
`maxPayloadBytes`	`65536`	Maximum UTF-8 JSON size retained for one event payload.
`smartDetailLatencyThresholdMs`	`10000`	Latency at which `smart` mode preserves masked detail.

Capture modes

Mode	Behavior
`full`	Keeps input and output fields when `captureInput` and `captureOutput` allow them.
`metadata-only`	Removes raw input and output, then keeps hashes, lengths, timing, usage, errors, and metadata.
`smart`	Keeps important metadata and truncates long strings. Failures and policy events keep enough detail for debugging.

const lynx = new LynxTracer({
  clientId: "support-api",
  apiKey: process.env.LYNX_API_KEY,
  captureMode: "metadata-only",
});

Delivery options

const lynx = new LynxTracer({
  clientId: "support-api",
  apiKey: process.env.LYNX_API_KEY,
  delivery: {
    mode: "BACKGROUND",
    timeoutMs: 1000,
    flushOnRunEnd: false,
    flushIntervalMs: 3000,
    batchSize: 50,
    maxQueueSize: 1000,
    overflowStrategy: "DROP_OLDEST",
  },
  circuitBreaker: {
    enabled: true,
    failureThreshold: 3,
    cooldownMs: 30000,
  },
});

Environment variables

The default lynx export reads configuration from environment variables.

import { lynx } from "@lynxops/sdk";

Variable	Description
`LYNX_CLIENT_ID`	Client or service identifier. Defaults to `local_dev_env`.
`LYNX_ENDPOINT`	Optional endpoint override. Defaults to `https://api.lynxops.co`.
`LYNX_API_KEY`	API key for event ingestion.
`LYNX_WORKSPACE_ID`	Default workspace ID.
`LYNX_AGENT_ID`	Default agent ID.
`LYNX_SESSION_ID`	Default session ID when `run()` does not receive one.
`LYNX_SAMPLE_RATE`	Sampling rate from `0` to `1`.
`LYNX_RUNTIME_CONFIG_MAX_STALE_AGE_MS`	Maximum age of a last-known-good prompt and policy bundle. Defaults to 24 hours.
`LYNX_RUNTIME_CONFIG_REQUIRE_SIGNATURE`	Reject unsigned runtime bundles when `true`.
`LYNX_RUNTIME_CONFIG_SIGNATURE_PUBLIC_KEY`	Ed25519 public key used to verify runtime bundles.
`LYNX_RUNTIME_CONFIG_REQUIRE_TARGET_MATCH`	Reject a bundle for another environment or an unresolved Agent.
`LYNX_RUNTIME_CONFIG_CACHE_ENABLED`	Persist validated runtime settings in `.lynxconf`.
`LYNX_RUNTIME_CONFIG_CACHE_PATH`	Optional exact `.lynxconf` path.
`LYNX_ISSUE_REPORTING_ENABLED`	Send detected issue candidates and recovery records when `true`.
`LYNX_ISSUE_REPORTING_TIMEOUT_MS`	Deadline for one issue-record request.
`LYNX_ISSUE_REPORTING_MAX_QUEUE_SIZE`	Maximum issue records kept in the isolated memory queue.
`LYNX_ISSUE_REPORTING_MAX_ATTEMPTS`	Maximum delivery attempts for one issue record.
`LYNX_ISSUE_REPORT_RUN_FAILURES`	Set `false` to disable automatic Run failure candidates.
`LYNX_ISSUE_REPORT_LLM_FAILURES`	Set `false` to disable automatic LLM error candidates.
`LYNX_ISSUE_SLOW_LLM_THRESHOLD_MS`	Slow LLM threshold in milliseconds. Defaults to `10000`; `0` disables it.
`LYNX_ISSUE_SLOW_LLM_CONSECUTIVE_OCCURRENCES`	Consecutive slow LLM calls required. Defaults to `2`.
`LYNX_ISSUE_RECOVERY_SUCCESS_THRESHOLD`	Healthy observations required before an automatic recovery record. Defaults to `3`.
`LYNX_APPROVAL_MAX_REQUEST_ATTEMPTS`	Attempts for transient approval API failures. Defaults to `3`.
`LYNX_CAPTURE_INPUT`	`true` or `false`.
`LYNX_CAPTURE_OUTPUT`	`true` or `false`.
`LYNX_CAPTURE_MODE`	`full`, `metadata-only`, or `smart`.
`LYNX_MAX_PAYLOAD_LENGTH`	Maximum payload string length.
`LYNX_MAX_PAYLOAD_BYTES`	Maximum UTF-8 JSON bytes retained per event payload.
`LYNX_SMART_DETAIL_LATENCY_THRESHOLD_MS`	Latency threshold for preserving detail in `smart` mode.
`LYNX_APP_VERSION`	Application version metadata.
`LYNX_DEPLOYMENT_ID`	Deployment ID metadata.
`LYNX_ENVIRONMENT`	Runtime environment. Falls back to `NODE_ENV`.
`LYNX_POLICY_VERSION`	Default policy version metadata.
`LYNX_DELIVERY_MODE`	`BACKGROUND` or `BLOCKING`.
`LYNX_DELIVERY_TIMEOUT_MS`	Delivery timeout in milliseconds.
`LYNX_DELIVERY_FLUSH_ON_RUN_END`	`true` or `false`.
`LYNX_DELIVERY_FLUSH_INTERVAL_MS`	Background flush interval in milliseconds.
`LYNX_DELIVERY_BATCH_SIZE`	Delivery batch size.
`LYNX_DELIVERY_MAX_QUEUE_SIZE`	Maximum queued event count.
`LYNX_DELIVERY_OVERFLOW_STRATEGY`	`DROP_OLDEST` or `DROP_NEWEST`.
`LYNX_CIRCUIT_BREAKER_ENABLED`	`true` or `false`.
`LYNX_CIRCUIT_BREAKER_FAILURE_THRESHOLD`	Consecutive failure count before opening the breaker.
`LYNX_CIRCUIT_BREAKER_COOLDOWN_MS`	Circuit breaker cooldown in milliseconds.

Security note

Depending on your settings, Lynx may receive prompts, tool arguments, and model responses. Avoid sending secrets, credentials, access tokens, or private keys. The SDK masks common sensitive keys, but you should still avoid passing secrets into prompts or tool payloads. Use metadata-only, captureInput: false, or captureOutput: false when raw content should not be sent.

Getting started

TypeScript SDK

OpenAPI

Configuration

When to use this

Basic setup

Issue reporting

Capture options

Capture modes

Delivery options

Environment variables

Security note

Next steps

​When to use this

​Basic setup

​Issue reporting

​Capture options

​Capture modes

​Delivery options

​Environment variables

​Security note

​Next steps

When to use this

Basic setup

Issue reporting

Capture options

Capture modes

Delivery options

Environment variables

Security note

Next steps