Skip to content

Provon Quickstart

By the end of this guide you will have Provon running locally, one agent trace in the Workbench, diagnostic Rules ready to produce Findings, and an optional GitHub repair handoff.

View as Markdown Open the plain-text version of this page.
On this page Browse sections

Prerequisites#

  • Node.js 22 or newer
  • pnpm 10
  • A model-provider API key if you use the Gateway path
  • A GitHub token or OAuth app if you want to create repair issues

1. Start Provon#

bash
git clone https://github.com/provon/provon
cd provon
pnpm install
pnpm dev

Open http://127.0.0.1:3000. Create an account, organization, and project when prompted.

The local runtime stores metadata in libSQL/SQLite, telemetry in DuckDB, and blobs on the local filesystem under .provon/.

2. Create A Project API Key#

In the project sidebar:

  1. Open API keys.
  2. Select Create API key.
  3. Copy the secret when it is shown. It cannot be retrieved later.
  4. Export it for the following examples:

Important

The secret is shown only once at creation. Store it in a secret manager before leaving the page; if it is lost you must rotate the key.

bash
export PROVON_API_KEY="your_project_api_key"
export PROVON_BASE_URL="http://127.0.0.1:3000"

The default project key can ingest and read telemetry, read diagnostics, and invoke the Gateway. Workbench actions such as changing Rules or creating a repair issue use your signed-in project permissions.

3. Capture Trace Evidence#

Choose one primary path. All paths produce project-scoped trace evidence.

Path A: Provon Gateway#

Open Providers, select a provider, and add its API key. Then send an OpenAI-compatible request:

bash
curl "$PROVON_BASE_URL/gateway/v1/chat/completions" \
  -H "Authorization: Bearer $PROVON_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-otel-gen-ai-conversation-id: quickstart-conversation-1" \
  -H "x-otel-gen-ai-agent-id: quickstart-agent" \
  -d '{
    "model": "openai/gpt-5-mini",
    "messages": [
      {
        "role": "user",
        "content": "Summarize why production evidence matters for coding agents."
      }
    ]
  }'

Replace the model with one enabled for your provider. The response should use the familiar OpenAI shape. Provon records the request, response, provider attempt, latency, tokens, cost, and errors according to the project's trace-capture settings.

See the Gateway quickstart for first-request and evidence verification, then use the migration guide for a staged production change, SDK integrations for client configuration, and the Gateway overview to find routing, governance, production, and API reference pages.

Path B: OpenTelemetry#

Point an existing OTLP/HTTP exporter at Provon:

bash
export OTEL_EXPORTER_OTLP_ENDPOINT="$PROVON_BASE_URL"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer $PROVON_API_KEY"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"

Run your instrumented agent once. Provon accepts:

text
POST /v1/traces
POST /v1/logs
POST /v1/metrics

Use the Tracing quickstart for a transparent first OTLP trace. See OpenTelemetry setup for Python, Node.js, Collector, and SDK configuration. Use the OTLP/HTTP API for transport, response, limit, and retry details.

Path C: Agent Transcript#

Project an existing Claude Code, Codex, or Pi transcript:

bash
pnpm --filter @provon/cli build
node cli/dist/bin.js sync ~/.claude/projects --once

Use --dry-run --print-sample before uploading private transcript content. See Agent transcript sync for source detection, continuous sync, sanitization, and tool-output controls.

4. Verify The Trace#

Open Traces in the Workbench and select the new trace.

Verify that:

  • the service and operation names identify the agent workload;
  • model and tool spans preserve their parent-child order;
  • a stable gen_ai.conversation.id is present for multi-turn diagnosis;
  • token, cost, latency, status, and error fields appear when the source emitted them.

Telemetry ingestion is successful when the trace is visible. A healthy trace does not need to produce a Finding.

Tip

If the trace does not appear, confirm the API key is project-scoped and the endpoint matches PROVON_BASE_URL. See troubleshooting for the full checklist.

5. Enable Diagnostics#

Open Findings:

  1. Leave the five built-in Rules enabled, or open Rules to configure them.
  2. Turn on Auto-diagnose.
  3. Run real agent conversations that include tool use and a clear user goal.

Automatic Runs are queued after a conversation has been inactive for 10 minutes. For existing telemetry, open Rules and run an enabled Rule against the last 24 hours.

Provon publishes only candidates that pass the Rule's signal and confidence thresholds. The default Rules cover runtime reliability, tool correctness, task fulfillment, answer grounding, and conversation health.

See Findings for Rule configuration, confidence, review states, and evidence.

6. Hand Off A Finding To GitHub#

This step requires at least one supported Finding.

  1. Open Connectors and expand GitHub.
  2. Connect with OAuth or enter a token manually.
  3. Set Default owner and Default repo, then enable the connector.
  4. Return to Findings, expand a Finding, and select Create repair issue.

Provon creates a GitHub Issue with:

  • a focused repair goal;
  • the Finding summary and cause assessment;
  • trace and span evidence links;
  • a remediation hint;
  • the provon-repair label and hidden correlation metadata.

The Finding becomes Confirmed and Handed off. Provon later records a merged pull request or closed issue as the external resolution; it does not edit the repository itself.

Optional: Seed A Local Product Tour#

To inspect the Workbench without generating your own workload, seed an empty local database before starting the server:

bash
pnpm seed:local
pnpm dev

The seed command prints the test account, project API key, and inserted record counts. It refuses to write into a non-empty metadata or telemetry database.

Next Steps#