See every LLM call. Turn failures into tests. Prove the next version is better.
A self-hosted OpenAI-compatible proxy and web app for debugging, testing, and improving AI agents.
Website | User guide | Installation | Changelog
Proxytrace sits between your agent and its LLM provider. It forwards the request, captures the complete interaction, and makes it available as an inspectable trace. From there you can detect anomalies, turn production failures into regression tests, compare agent versions, and automate the workflow through its REST API or MCP server.
You need Docker. One container includes the web UI, API, ingestion proxy, PostgreSQL, and Redis:
docker run -d --name proxytrace \
-p 5101:80 -p 5102:8081 \
-v proxytrace:/data \
ghcr.io/nordsteinsoftware/proxytrace- Open http://localhost:5101.
- Follow the setup wizard to create the administrator, provider, and first project.
- Copy the project endpoint shown by the wizard.
The proxytrace volume contains the database and encryption keys. Keep it when replacing or
upgrading the container. For a production deployment with separate PostgreSQL and Redis containers,
use the proxytrace.zip release artifact
and follow the deployment guide.
Keep your OpenAI SDK and provider key. Change the client's base URL to the project-scoped endpoint from the setup wizard:
client = OpenAI(
- base_url="https://api.openai.com/v1",
+ base_url="http://localhost:5102/my-project/openai/v1",
api_key=os.environ["OPENAI_API_KEY"],
)Send a request normally, then open Traces in Proxytrace. The full conversation, tool calls, model parameters, token usage, latency, cache usage, and cost are captured automatically.
For deterministic agent attribution, add the optional x-proxytrace-agent header:
client = OpenAI(
base_url="http://localhost:5102/my-project/openai/v1",
api_key=os.environ["OPENAI_API_KEY"],
default_headers={"x-proxytrace-agent": "support-agent"},
)The setup wizard generates ready-to-use Python, TypeScript, C#, and curl examples with your actual project endpoint. See Proxy setup for API keys, Azure OpenAI, custom providers, and additional routing options.
| Capability | |
|---|---|
| Inspect | Read complete prompts, responses, tool round-trips, parameters, errors, and timings. |
| Diagnose | Find unusual token usage, latency, tool activity, cache behavior, and custom rule matches. |
| Test | Promote a real trace into a reusable test case and evaluate it with deterministic or LLM-based assertions. |
| Compare | Run the same suite against agent or model candidates and compare quality, speed, and cost. |
| Improve | Review optimization proposals backed by measured A/B test results. |
| Automate | Query traces, curate suites, and start runs through the REST API or project-scoped MCP server. |
Proxytrace supports OpenAI, Azure OpenAI, and OpenAI-compatible providers on linux/amd64 and
linux/arm64. Feature availability varies by plan; see proxytrace.dev for
the current feature matrix.
Promote a production interaction as-is or correct the expected answer before adding it to a suite.
Run one suite against multiple agent or model candidates and inspect every score, failure, latency, and cost difference.
Optimization proposals connect a concrete prompt change to the failures that motivated it and the A/B test that validated it.
- Get started with the product
- Configure the ingestion proxy
- Connect Claude Code, Cursor, or another MCP client
- Install and operate Proxytrace
- Report a bug or request a feature
- Read the security policy
Source-available under the Elastic License 2.0: you may use, copy, modify and redistribute Proxytrace, but you may not offer it as a managed service to third parties, circumvent its license-key functionality, or remove its licensing and copyright notices. A free tier is built in; paid tiers unlock higher limits and additional features.