Quickstart

Run Pulse server

Set up Pulse in this order: install binary, choose mode, run setup, then run the server.

1) Install the binary

curl -fsSL https://raw.githubusercontent.com/EK-LABS-LLC/trace-service/main/scripts/install.sh | bash -s -- pulse-server

This installs both pulse-server (trace service) and pulse (CLI integrations).

2) Choose single vs scale mode and set env vars

Use single for the fastest local setup. Use scale when you need Postgres-backed multi-node or higher-throughput ingest.

See Single vs Scale Modes for an in-depth comparison and operational guidance.

Single mode (default, local SQLite):

export PULSE_MODE=single
export BETTER_AUTH_SECRET="$(openssl rand -hex 32)"
export ENCRYPTION_KEY="$(openssl rand -hex 32)"
export BETTER_AUTH_URL='http://localhost:3000'

Scale mode (Postgres + partitioned listeners):

export PULSE_MODE=scale
export DATABASE_URL='postgresql://pulse:pulse@localhost:5432/pulse'
export BETTER_AUTH_SECRET="$(openssl rand -hex 32)"
export ENCRYPTION_KEY="$(openssl rand -hex 32)"
export BETTER_AUTH_URL='http://localhost:3000'

3) Run pulse setup

pulse setup

pulse setup creates your dashboard account, project, and API key, then writes ~/.pulse/config.toml.

4) Start the server

pulse-server

Use the same env vars from step 2 when starting the server. If pulse setup already started pulse-server, you can skip this step.

Optional: run the dashboard UI

If you want the hosted frontend UI, run the separate pulse-dashboard Docker image.

See Dashboard UI (Docker) for same-origin and split-origin deployment patterns.

Install SDK

TypeScript

bun add @eklabs/pulse-sdk

Python

pip install pulse-trace-sdk

Works with Bun, Node, or any JavaScript/Python runtime.

CLI integrations (Claude Code, Opencode, OpenClaw)

If you want Pulse to capture coding-agent events in addition to SDK traces:

# Bootstrap config + account + integrations
pulse setup --no-start-server

# Verify config + connectivity + integration status
pulse status

See CLI Reference for full command and config details.

Initialize

Call initPulse() once at application startup using the API key created during pulse setup.

TypeScript

import { initPulse } from "@eklabs/pulse-sdk";

initPulse({
  apiKey: "pulse_sk_...",
});

Python

from pulse_sdk import init_pulse

init_pulse({
  "api_key": "pulse_sk_...",
})

This starts background trace batches and registers shutdown handlers to flush remaining traces on exit.

Wrap your client

Use observe() to wrap your LLM client. The returned client behaves identically and tracing is captured as a side effect.

TypeScript

import { initPulse, observe, Provider } from "@eklabs/pulse-sdk";
import OpenAI from "openai";

initPulse({ apiKey: "pulse_sk_..." });

const client = observe(
  new OpenAI({ apiKey: "sk-..." }),
  Provider.OpenAI
);

const res = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello" }],
});

Python

from pulse_sdk import init_pulse, observe, Provider
from openai import OpenAI

init_pulse({ "api_key": "pulse_sk_..." })

client = observe(
  OpenAI(api_key="sk-..."),
  Provider.OPENAI
)

res = client.chat.completions.create(
  model="gpt-4o",
  messages=[{"role": "user", "content": "Hello"}],
)

What gets captured

Field	Description
Request and response bodies	Full prompt and completion
Token counts	Input and output tokens
Latency	End-to-end request duration in milliseconds
Cost	Provider-reported or SDK-estimated when model pricing is available
Model	Requested and actual model used
Status	success or error
Provider	openai, anthropic, or openrouter

Supported providers

Provider	Client	Enum
OpenAI	openai	Provider.OpenAI
Anthropic	@anthropic-ai/sdk	Provider.Anthropic
OpenRouter	openai	Provider.OpenRouter

See Providers for detailed usage.

Next steps

CLI Reference

Configuration

Sessions & Metadata

REST API