How do I install Dunetrace?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Dunetrace need an API key?

No required environment variable is listed on this record.

What transport does Dunetrace use?

Dunetrace runs locally over stdio.

When was Dunetrace last checked?

Last checked 2026-10-27. The runtime reliability layer for AI agents.

Dunetrace MCP server

Dunetrace

Runtime reliability for AI agents. Structural and semantic detection, runtime prevention, native root cause, and one-click fixes.

Slack alert

Star us ⭐

If Dunetrace helps you, consider giving it a ⭐ on top right, it helps others find the project.

The problem

AI agents fail silently:

✓ API returns 200 ✓ Latency is normal ✓ Cost looks normal
✗ The upstream API returned an error body. The agent invented the numbers and reported success.
✗ Two agents delegated in a circle. Eight runs, all green, no progress.
✗ A document your agent read last week wrote an instruction into its memory. It fired today.

Tracers answer "what happened?" i.e. after you already know it broke. Dunetrace answers "is something breaking right now?" with deterministic, zero-LLM checks on every run, and in the request path, where a policy can block the action before it executes.

Five pillars, one platform

Dunetrace covers the full agent reliability lifecycle, not just one slice of it:

	Pillar	What it does
1	Sessions & Events	Every run, every tool call, every LLM exchange — the raw data everything else is built on
2	Structural Detection	34 zero-LLM detectors (31 of them in-path, sub-500μs per hook) — the always-on first line → docs/detectors.md
3	Semantic Evaluation	LLM-based judgment (hallucination, task completion, cross-turn frustration) — post-hoc, sampling-based, opt-in → docs/semantic-evaluation.md
4	Runtime Prevention	Policies that stop, redirect, or downgrade a run while it's happening — the differentiator no tracer offers → docs/policies.md
5	Root Cause & Fix	Native root-cause analysis, auto-applied policy fixes, or a one-click draft PR → Diagnose & fix

Quick Start

1. Start the backend

git clone https://github.com/dunetrace/dunetrace
cd dunetrace && cp .env.example .env
docker compose -f docker-compose.ghcr.yml up -d   # localhost, auth off — see docs/operations.md to deploy
curl -s localhost:8001/ready && curl -s localhost:8002/ready   # both {"status":"ok",...}

2. Install the SDK

pip install dunetrace                       # Python
npm install dunetrace                       # Node.js / TypeScript

# Or skip steps 2-3 entirely: the skill installs the SDK and instruments your
# code. Run /dunetrace-setup (Claude Code, Cursor) or $dunetrace-setup (Codex).
npx skills add dunetrace/dunetrace-skills --skill dunetrace-setup

3. Instrument your agent

Python

from dunetrace import Dunetrace
import openai

dt = Dunetrace()
dt.init(agent_id="support-agent")   # auto-instruments installed clients (OpenAI, Anthropic, Mistral, Bedrock, LangChain, CrewAI, httpx, requests)

@dt.agent("support-agent", model="gpt-4o")
def my_agent(question: str) -> str:
    resp = openai.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": question}],
    )
    return resp.choices[0].message.content   # LLM + tool calls tracked automatically, no manual hooks

TypeScript / Node.js

import { Dunetrace, autoInstrument } from "dunetrace";
import OpenAI from "openai";

const dt = new Dunetrace();
autoInstrument({ openai: OpenAI });   // patches OpenAI + outbound fetch; add `anthropic:` / `mistral:` too, or wrap one client with dt.wrapOpenAI()

const openai = new OpenAI();          // constructed after the patch — still tracked

await dt.run("support-agent", { model: "gpt-4o" }, async (run) => {
  await openai.chat.completions.create({ model: "gpt-4o", messages });
  run.finalAnswer();                  // LLM + tool calls tracked automatically, streaming included
});

→ TypeScript auto-instrumentation

Try the built-in failure scenarios

cd packages/sdk-py                                      # Python
python examples/basic_agent.py                          # No LLM calls, no API key
SCENARIO=tool_loop python examples/langchain_agent.py   # TOOL_LOOP via LangChain — needs OPENAI_API_KEY
SCENARIO=failures python examples/decorator_agent.py    # TOOL_LOOP, RETRY_STORM, RAG_EMPTY_RETRIEVAL

cd ../sdk-ts && npm install                             # TypeScript — needs Node 22+
ollama pull llama3.2                                    # and Ollama, so no API key is needed
npm run example:vercel-ai                               # Happy path
npm run example:vercel-ai:loop                          # TOOL_LOOP → detect → explain, end to end

More, including approvals, policies, agent memory and voice → examples index

Open the dashboard: http://localhost:3000

Detectors

34 detectors run on every completed run — no configuration, no LLM. A few of the main ones:

Signal	What it catches
`TOOL_LOOP`	Same tool called repeatedly with identical args
`RETRY_STORM`	Tool failing, agent retrying it repeatedly
`COST_SPIKE`	Total token consumption unusually high vs per-agent baseline
`PROMPT_INJECTION_SIGNAL`	Input matched adversarial injection patterns
`MEMORY_POISONING`	An injection directive was written into the agent's own memory, re-steering it when read back
`DELEGATION_LOOP`	Agents delegate to each other in a cycle that never converges
`RUNAWAY_ITERATION`	Step or cost ceiling crossed with no completion signal
`SILENT_TRUNCATION`	A response was truncated and the agent used it without retrying
`MODEL_FALLBACK_DRIFT`	The run silently switched to a weaker model (e.g. under rate limiting)

Each alert carries what fired, why it matters, a concrete fix, and rate context (first occurrence / recurring / systemic). → docs/detectors.md for all 34

Multi-agent — nested dt.run() calls auto-link into a delegation graph that DELEGATION_LOOP and HANDOFF_CONTEXT_LOSS read → docs/multi-agent.md
Agent memory — instrument memory writes/reads and MEMORY_POISONING flags adversarial content persisted into them → docs/memory.md
Custom detectors — describe one in plain English; it runs in shadow mode until you approve the fire rate → docs/detectors.md
Detector packs — opt-in bundles per org; the voice pack adds 9 detectors → detector packs · voice pack

Semantic evaluation

Opt-in LLM judgment for what structural checks can't see — seven DeepEval-backed evaluators (hallucination, task completion, task-understanding failure, off-topic drift, user frustration, confusion loops, sycophancy). Post-hoc and sampling-based, never in your agent's request path. Its own container, off by default:

SEMANTIC_WORKER_ENABLED=true

→ docs/semantic-evaluation.md

Dashboard

Overview

Live at http://localhost:3000. Auto-refreshes every 15s.

→ docs/dashboard.md

Alerts

Slack and generic webhook (PagerDuty, Linear, custom).

SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
SLACK_MIN_SEVERITY=LOW   # LOW | MEDIUM | HIGH | CRITICAL
DIGEST_ENABLED=true      # weekly digest of top failure types, Monday 9am UTC

→ docs/alerts.md

Diagnose & fix

Click Explain + on any alert: Dunetrace analyzes the run's own stored events (no third-party tracer) and returns a cause plus a fix — either a runtime policy it applies itself (tool loops, retry storms, runaway step counts) or a prompt/code diff you copy in or open as a draft PR. Fix effectiveness is tracked automatically.

Policies

Runtime guardrails that fire mid-run — before a failure propagates. Defined in code or in the dashboard (the SDK refetches every 60s).

dt.add_policy(                                  # stop, switch_model, escalate, inject, ...
    name="cap tool calls",
    condition={"trigger": "tool_call_count", "operator": "gt", "value": 5},
    action={"type": "stop"},
)
dt.add_policy(                                  # human-in-the-loop: blocks the call until
    name="approve-wires",                       # someone approves in Slack or the dashboard,
    condition={"trigger": "before_tool_call", "operator": "eq", "value": "wire_money"},
    action={"type": "require_approval", "params": {"timeout_s": 300}},   # fail-closed on timeout
)

→ docs/policies.md · docs/approvals.md

MCP server

Query agent signals from Claude Code, Cursor, or Codex — "what failed in the last 24 hours?" — without leaving your editor.

pip install dunetrace-mcp

31 tools covering agents, runs, signals, fixes, issues, policies, custom detectors and voice calls. Claude Code registers the server automatically in ~/.claude.json (restart to load); Cursor and Codex need one config block.

Tool	What you can ask
`list_agents`	"Which agents are monitored and how healthy are they?"
`get_agent_signals`	"What failures did my agent have today?"
`get_agent_health`	"Show me the health score breakdown for my agent."
`get_signal_detail`	"Show me signal #42 with full evidence and fix code."
`get_agent_patterns`	"Is this failure systemic or a one-off?"
`get_run_detail`	"Walk me through run abc123 step by step."
`get_agent_runs`	"List recent runs for my agent with their status."
`search_signals`	"Show me all CRITICAL signals in the last 24 hours."
`summarize_agent`	"Give me a one-shot diagnosis of my agent."
`get_agent_token_stats`	"How much is my agent wasting on failed runs?"

→ docs/mcp-server.md

Architecture

Services share one Postgres and no message broker: the SDK ships events to the ingest API, and each worker polls for what it needs next. The core pipeline runs with no LLM key; three workers are opt-in.

→ docs/architecture.md — services, data flow, detection paths, schema · docs/operations.md — deploying, probes and metrics, retention, redaction, rate limiting

Integrations

Model providers — OpenAI, Anthropic, Mistral and AWS Bedrock, auto-instrumented with no call-site changes.

Evaluation & tracing

Fix & workflow

Voice

Contributing

Fork, branch, change, make test, PR — open an issue first for new integrations or architecture changes. Requires Python 3.11+, Node.js 22+, Docker + Docker Compose.

→ CONTRIBUTING.md (setup and workflow) · good first issues · adding a detector

Contact

Dunetrace UG (haftungsbeschränkt) · Kolonnenstr. 8, 10827 Berlin, Germany · [email protected]

License

Apache 2.0

Dunetrace

Runtime reliability for AI agents. Structural and semantic detection, runtime prevention, native root cause, and one-click fixes.

Slack alert

Star us ⭐

If Dunetrace helps you, consider giving it a ⭐ on top right, it helps others find the project.

The problem

AI agents fail silently:

✓ API returns 200 ✓ Latency is normal ✓ Cost looks normal
✗ The upstream API returned an error body. The agent invented the numbers and reported success.
✗ Two agents delegated in a circle. Eight runs, all green, no progress.
✗ A document your agent read last week wrote an instruction into its memory. It fired today.

Five pillars, one platform

Dunetrace covers the full agent reliability lifecycle, not just one slice of it:

	Pillar	What it does
1	Sessions & Events	Every run, every tool call, every LLM exchange — the raw data everything else is built on
2	Structural Detection	34 zero-LLM detectors (31 of them in-path, sub-500μs per hook) — the always-on first line → docs/detectors.md
3	Semantic Evaluation	LLM-based judgment (hallucination, task completion, cross-turn frustration) — post-hoc, sampling-based, opt-in → docs/semantic-evaluation.md
4	Runtime Prevention	Policies that stop, redirect, or downgrade a run while it's happening — the differentiator no tracer offers → docs/policies.md
5	Root Cause & Fix	Native root-cause analysis, auto-applied policy fixes, or a one-click draft PR → Diagnose & fix

Quick Start

1. Start the backend

git clone https://github.com/dunetrace/dunetrace
cd dunetrace && cp .env.example .env
docker compose -f docker-compose.ghcr.yml up -d   # localhost, auth off — see docs/operations.md to deploy
curl -s localhost:8001/ready && curl -s localhost:8002/ready   # both {"status":"ok",...}

2. Install the SDK

pip install dunetrace                       # Python
npm install dunetrace                       # Node.js / TypeScript

# Or skip steps 2-3 entirely: the skill installs the SDK and instruments your
# code. Run /dunetrace-setup (Claude Code, Cursor) or $dunetrace-setup (Codex).
npx skills add dunetrace/dunetrace-skills --skill dunetrace-setup

3. Instrument your agent

Python

from dunetrace import Dunetrace
import openai

dt = Dunetrace()
dt.init(agent_id="support-agent")   # auto-instruments installed clients (OpenAI, Anthropic, Mistral, Bedrock, LangChain, CrewAI, httpx, requests)

@dt.agent("support-agent", model="gpt-4o")
def my_agent(question: str) -> str:
    resp = openai.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": question}],
    )
    return resp.choices[0].message.content   # LLM + tool calls tracked automatically, no manual hooks

TypeScript / Node.js

import { Dunetrace, autoInstrument } from "dunetrace";
import OpenAI from "openai";

const dt = new Dunetrace();
autoInstrument({ openai: OpenAI });   // patches OpenAI + outbound fetch; add `anthropic:` / `mistral:` too, or wrap one client with dt.wrapOpenAI()

const openai = new OpenAI();          // constructed after the patch — still tracked

await dt.run("support-agent", { model: "gpt-4o" }, async (run) => {
  await openai.chat.completions.create({ model: "gpt-4o", messages });
  run.finalAnswer();                  // LLM + tool calls tracked automatically, streaming included
});

→ TypeScript auto-instrumentation

Try the built-in failure scenarios

cd packages/sdk-py                                      # Python
python examples/basic_agent.py                          # No LLM calls, no API key
SCENARIO=tool_loop python examples/langchain_agent.py   # TOOL_LOOP via LangChain — needs OPENAI_API_KEY
SCENARIO=failures python examples/decorator_agent.py    # TOOL_LOOP, RETRY_STORM, RAG_EMPTY_RETRIEVAL

cd ../sdk-ts && npm install                             # TypeScript — needs Node 22+
ollama pull llama3.2                                    # and Ollama, so no API key is needed
npm run example:vercel-ai                               # Happy path
npm run example:vercel-ai:loop                          # TOOL_LOOP → detect → explain, end to end

More, including approvals, policies, agent memory and voice → examples index

Open the dashboard: http://localhost:3000

Detectors

34 detectors run on every completed run — no configuration, no LLM. A few of the main ones:

Signal	What it catches
`TOOL_LOOP`	Same tool called repeatedly with identical args
`RETRY_STORM`	Tool failing, agent retrying it repeatedly
`COST_SPIKE`	Total token consumption unusually high vs per-agent baseline
`PROMPT_INJECTION_SIGNAL`	Input matched adversarial injection patterns
`MEMORY_POISONING`	An injection directive was written into the agent's own memory, re-steering it when read back
`DELEGATION_LOOP`	Agents delegate to each other in a cycle that never converges
`RUNAWAY_ITERATION`	Step or cost ceiling crossed with no completion signal
`SILENT_TRUNCATION`	A response was truncated and the agent used it without retrying
`MODEL_FALLBACK_DRIFT`	The run silently switched to a weaker model (e.g. under rate limiting)

Each alert carries what fired, why it matters, a concrete fix, and rate context (first occurrence / recurring / systemic). → docs/detectors.md for all 34

Multi-agent — nested dt.run() calls auto-link into a delegation graph that DELEGATION_LOOP and HANDOFF_CONTEXT_LOSS read → docs/multi-agent.md
Agent memory — instrument memory writes/reads and MEMORY_POISONING flags adversarial content persisted into them → docs/memory.md
Custom detectors — describe one in plain English; it runs in shadow mode until you approve the fire rate → docs/detectors.md
Detector packs — opt-in bundles per org; the voice pack adds 9 detectors → detector packs · voice pack

Semantic evaluation

SEMANTIC_WORKER_ENABLED=true

→ docs/semantic-evaluation.md

Dashboard

Overview

Live at http://localhost:3000. Auto-refreshes every 15s.

→ docs/dashboard.md

Alerts

Slack and generic webhook (PagerDuty, Linear, custom).

SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
SLACK_MIN_SEVERITY=LOW   # LOW | MEDIUM | HIGH | CRITICAL
DIGEST_ENABLED=true      # weekly digest of top failure types, Monday 9am UTC

→ docs/alerts.md

Diagnose & fix

Policies

Runtime guardrails that fire mid-run — before a failure propagates. Defined in code or in the dashboard (the SDK refetches every 60s).

dt.add_policy(                                  # stop, switch_model, escalate, inject, ...
    name="cap tool calls",
    condition={"trigger": "tool_call_count", "operator": "gt", "value": 5},
    action={"type": "stop"},
)
dt.add_policy(                                  # human-in-the-loop: blocks the call until
    name="approve-wires",                       # someone approves in Slack or the dashboard,
    condition={"trigger": "before_tool_call", "operator": "eq", "value": "wire_money"},
    action={"type": "require_approval", "params": {"timeout_s": 300}},   # fail-closed on timeout
)

→ docs/policies.md · docs/approvals.md

MCP server

Query agent signals from Claude Code, Cursor, or Codex — "what failed in the last 24 hours?" — without leaving your editor.

pip install dunetrace-mcp

Tool	What you can ask
`list_agents`	"Which agents are monitored and how healthy are they?"
`get_agent_signals`	"What failures did my agent have today?"
`get_agent_health`	"Show me the health score breakdown for my agent."
`get_signal_detail`	"Show me signal #42 with full evidence and fix code."
`get_agent_patterns`	"Is this failure systemic or a one-off?"
`get_run_detail`	"Walk me through run abc123 step by step."
`get_agent_runs`	"List recent runs for my agent with their status."
`search_signals`	"Show me all CRITICAL signals in the last 24 hours."
`summarize_agent`	"Give me a one-shot diagnosis of my agent."
`get_agent_token_stats`	"How much is my agent wasting on failed runs?"

→ docs/mcp-server.md

Architecture

→ docs/architecture.md — services, data flow, detection paths, schema · docs/operations.md — deploying, probes and metrics, retention, redaction, rate limiting

Integrations

Model providers — OpenAI, Anthropic, Mistral and AWS Bedrock, auto-instrumented with no call-site changes.

Evaluation & tracing

Fix & workflow

Voice

Contributing

Fork, branch, change, make test, PR — open an issue first for new integrations or architecture changes. Requires Python 3.11+, Node.js 22+, Docker + Docker Compose.

→ CONTRIBUTING.md (setup and workflow) · good first issues · adding a detector

Contact

Dunetrace UG (haftungsbeschränkt) · Kolonnenstr. 8, 10827 Berlin, Germany · [email protected]

License

Apache 2.0

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Dunetrace?

Does Dunetrace need an API key?

What transport does Dunetrace use?

When was Dunetrace last checked?

Documentation

Dunetrace

Star us ⭐

The problem

Five pillars, one platform

Quick Start

Detectors

Semantic evaluation

Dashboard

Alerts

Diagnose & fix

Policies

MCP server

Architecture

Integrations

Contributing

Contact

License

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Dunetrace?

Does Dunetrace need an API key?

What transport does Dunetrace use?

When was Dunetrace last checked?

Documentation

Dunetrace

Star us ⭐

The problem

Five pillars, one platform

Quick Start

Detectors

Semantic evaluation

Dashboard

Alerts

Diagnose & fix

Policies

MCP server

Architecture

Integrations

Contributing

Contact

License