Provon Quickstart

If you have not installed Provon yet, see Install Provon. If you prefer to follow the built-in Workbench setup flow, see Workbench onboarding.

Prerequisites#

• A Provon project in the hosted Workbench or a local/self-hosted deployment. See Install Provon.
• 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. Open Provon#

Hosted#

Open https://app.provon.dev and sign in. The Workbench onboarding walks you through creating an organization, project, and API key.

Self-hosted or local development#

For a one-line self-hosted install:

curl -fsSL https://provon.dev/install.sh | sh

Then source the generated environment file and start the server. The installer output tells you the exact command.

For source development:

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

Then open http://127.0.0.1:3000. The local development server runs the API on port 3001 by default; the Workbench is on port 3000.

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#

During onboarding the Workbench creates a project and shows an API key. If you skipped that step or need another key:

1. Open API keys in the project sidebar.
2. Select Create API key.
3. Copy the secret when it is shown. It cannot be retrieved later.

Set the key and the API origin for the following examples:

export PROVON_API_KEY="your_project_api_key"
export PROVON_API_URL="https://api.provon.dev/v1"

For local development use:

export PROVON_API_URL="http://127.0.0.1:3001/v1"

The default project key can ingest and read telemetry, invoke the Gateway, inspect diagnostics, read model pricing, and discover its project. Mutation capabilities are not granted by default. 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. For hosted Provon use the Gateway origin:

export PROVON_GATEWAY_URL="https://gateway.provon.dev/v1"

For local development use:

export PROVON_GATEWAY_URL="http://127.0.0.1:3001/gateway/v1"

Send a request:

curl "$PROVON_GATEWAY_URL/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. You can also run the curl examples in examples/gateway-endpoints.

Path B: OpenTelemetry#

For hosted Provon:

export PROVON_OTEL_URL="https://otel.provon.dev/v1"

For local development:

export PROVON_OTEL_URL="http://127.0.0.1:3001/v1"

Point an existing OTLP/HTTP exporter at Provon:

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="$PROVON_OTEL_URL/traces"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer $PROVON_API_KEY"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"

Run your instrumented agent once. Provon accepts POST /v1/traces at the OTLP origin.

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. Runnable observability examples are in examples/agent-observability-*.

Path C: Agent transcript#

Project an existing Claude Code, Codex, or Pi transcript with the Provon CLI.

If you installed Provon through the self-hosted installer or package manager:

provon ingest sync ~/.claude/projects --once --dry-run --print-sample

If you are working from the source repository:

pnpm --filter @provon/cli build
node cli/dist/bin.js ingest sync ~/.claude/projects --once --dry-run --print-sample

Review the sample output, then remove --dry-run to upload. Common transcript directories include:

~/.claude/projects
~/.codex/sessions
~/.pi/agent/sessions

Use --include-tool-output none if tool outputs contain private data you do not want to upload. See Agent transcript sync for source detection, continuous sync, sanitization, and tool-output controls. The CLI also has a local viewer at provon transcripts that does not upload anything.

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.

5. Enable diagnostics#

If you followed Workbench onboarding, you already analyzed your latest conversation in the Discover step. Continue here to enable ongoing diagnosis.

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 Diagnostic rules for Rule configuration, confidence thresholds, and signal overrides, and Findings for 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: Use a coding agent to connect#

If you use Claude Code, Codex, or Cursor, copy the project-specific setup prompt from the Workbench Connect step and hand it to your coding agent. The prompt tells the agent to inspect the codebase, recommend the best capture path, and implement it using repository conventions. The agent waits for your confirmation before making changes.

This is the fastest way to connect an existing codebase without writing the first integration yourself.

Optional: Seed a demo product tour#

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

pnpm seed:demo
pnpm dev

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

Sign in with demo@provon.dev and password provon123.