Docs / Quick start

Quick start

Clone the repo, run docker compose up, instrument your agent with a single decorator or callback, and watch signals arrive in the dashboard within fifteen seconds.

Fastest path: let your coding agent do it

If you use Claude Code, Cursor or Codex, the dunetrace-setup skill instruments your repository for you. It finds your agent's real entry point, asks before changing anything, verifies events arrived, and reports which detectors are now live.

npx skills add dunetrace/dunetrace-skills --skill dunetrace-setup

Then /dunetrace-setup in Claude Code or Cursor, or $dunetrace-setup in Codex. Codex uses $ rather than /. You can also just say "add Dunetrace to this repo" and the skill triggers on its own.

You still need a backend for events to land in, so do step 1 below either way. The skill checks whether one is reachable and tells you if it is not. Full detail at dunetrace/dunetrace-skills.

The manual path follows.

Prerequisites

  • Docker + Docker Compose
  • Python 3.11+
  • A Slack webhook URL (optional, for alerts)

1. Start the backend

Clone the repo, copy the environment file, and bring up the stack with Docker Compose.

git clone https://github.com/dunetrace/dunetrace
cd dunetrace
cp .env.example .env
docker compose build
docker compose up -d

Four services come up:

ServicePortWhat it does
Dashboard:3000Mission control — static HTML
Ingest API:8001Accepts events from the SDK
Customer API:8002API behind the dashboard and any integrations — reads plus scope-gated writes (policies, approvals, keys)
Postgres:5432Shared state

2. Install the SDK

pip install dunetrace                          # any framework
pip install 'dunetrace[langchain]'            # LangChain / LangGraph
pip install 'dunetrace[langchain,langfuse]'   # LangChain + Langfuse integration
pip install 'dunetrace[otel]'                 # OpenTelemetry export

3. Instrument your agent

The fastest path for a Python agent using OpenAI or Anthropic is the decorator:

from dunetrace import Dunetrace

dt = Dunetrace()                 # no api_key needed for local dev
dt.init(agent_id="my-agent")    # patches openai, anthropic, mistral, botocore, langchain, crewai, httpx, requests

@dt.agent()
def run_agent(query: str) -> str:
    # LLM + HTTP calls inside here are tracked automatically
    resp = openai_client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": query}],
    )
    return resp.choices[0].message.content

run_agent("What is the capital of France?")
dt.shutdown()

For LangChain, use the callback handler:

from dunetrace import Dunetrace
from dunetrace.integrations.langchain import DunetraceCallbackHandler

dt = Dunetrace()
callback = DunetraceCallbackHandler(dt, agent_id="my-langchain-agent")

result = agent.invoke(
    {"messages": [("human", "What is the capital of France?")]},
    config={"callbacks": [callback]},
)

4. Open the dashboard

Navigate to http://localhost:3000. Your run should appear within fifteen seconds.

ℹ
Dev mode. Running locally, no api_key is required — the backend accepts unauthenticated requests when AUTH_MODE=dev. Production deployments should generate and use a dt_live_ key.

5. Trigger a failure to verify

The SDK ships with failure scenarios so you can confirm signals fire end-to-end before pointing Dunetrace at production traffic:

SCENARIO=failures python examples/decorator_agent.py
# → triggers TOOL_LOOP, RETRY_STORM, RAG_EMPTY_RETRIEVAL

SCENARIO=tool_loop python examples/langchain_agent.py
# → triggers TOOL_LOOP via LangChain

Each signal appears in the dashboard Alerts page within fifteen seconds and fires a Slack alert if SLACK_WEBHOOK_URL is set.

6. Wire up Slack (optional)

Add to .env:

SLACK_WEBHOOK_URL=https://hooks.slack.com/services/xxx/yyy/zzz
SLACK_CHANNEL=#agent-alerts
SLACK_MIN_SEVERITY=HIGH   # LOW | MEDIUM | HIGH | CRITICAL

Restart the alerts worker:

docker compose up -d --force-recreate alerts

Next steps