Skip to content

Provon Quickstart

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

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

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

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

  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.

    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.

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

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

    A default project key carries six read/invoke capabilities: telemetry:ingest, telemetry:read, diagnostics:read, gateway:invoke, model-pricing:read, and workspace:read. Mutation capabilities such as diagnostics:write, gateway:manage, and workspace:write are not granted by default. Workbench actions such as changing Rules or creating a repair issue use your signed-in project permissions; see API keys for the full capability list.

  3. Capture trace evidence

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

    Open Providers, select a provider, and add its API key. Set the Gateway origin for your environment:

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

    Then send an OpenAI-compatible request:

    bash
    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": "replace-with-your-configured-model",
    "messages": [
      {
        "role": "user",
        "content": "Summarize why production evidence matters for coding agents."
      }
    ]
  }'

    Replace <configured-model-id> with a model bound on the Providers page. 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.

  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_GATEWAY_URL or PROVON_OTEL_URL. See troubleshooting for the full checklist.

  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. Automatic diagnosis is on while at least one Rule is enabled.
    2. 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 through the backfill dialog. The dialog offers a range (last 24 hours, 7 days, 30 days, 90 days, or all time) and defaults to the last 30 days.

    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 safety.

    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. On the Findings page, open the issue tracker menu and choose 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.

Success Check#

  • provon auth status shows the active project, or the Workbench API keys page lists the key.
  • Traces lists at least one trace from the chosen capture path with a stable conversation id.
  • Findings produces candidates only when the conversation crosses a Rule threshold; an empty list on healthy traffic is expected.
  • A handoff work item opens in the tracker with the Finding id and evidence links.

Troubleshooting#

Symptom Fix
Gateway call returns 401 / 403 Key lacks gateway:invoke; create a key with the default capabilities and bind a model in Providers
OTLP returns 401 Use a project key with telemetry:ingest; provider keys and GitHub tokens are not valid here
Trace missing after capture Confirm the endpoint and project; see Troubleshooting
No Finding appears after traces Wait the 10-minute idle delay, run a Rule backfill, or lower thresholds; see Troubleshooting

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:

bash
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.