Skip to content

Workbench onboarding

The first time you open the Provon Workbench you see a three-step onboarding flow: Workspace → Connect → Discover. This page explains each step and how it maps to the Quickstart.

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

Before you start#

Make sure you can reach a Provon deployment:

  • Hosted: open https://app.provon.dev and sign in.
  • Self-hosted: run the installer, start the server, and open the Workbench URL printed in the logs. See Install Provon.

Step 1: Workspace#

Create an organization and a project.

  • An organization holds your team members and their roles, and the organization name and slug.
  • A project holds traces, Findings, and Rules.

The Workbench suggests placeholder names. You can rename them later in Organization settings and Project settings.

After you confirm the names, Provon creates the project and generates a project API key. Copy it immediately — it is shown only once.

Step 2: Connect#

The recommended card hands a coding agent (Claude Code, Codex, or Cursor) a project-specific setup prompt: copy it, and the agent inspects the codebase, recommends the best capture path, and implements it using your repository conventions.

Below the card, pick one capture path:

  1. AI Gateway: copy a curl or SDK snippet and send one OpenAI-compatible request.
  2. OpenTelemetry: copy exporter environment variables and run your already-instrumented agent.
  3. CLI: install hooks for live capture or backfill persisted transcripts. The Workbench lists Claude, Codex, OpenCode, dsh, Cursor, and Pi, but live upload works today only for Claude, Codex, and Cursor; backfill covers Claude, Codex, and Pi (~/.pi/agent/sessions). See the live-capture status.

You can also connect later from API keys, Providers, or Project settings. See Choose a capture path for a detailed comparison.

Step 3: Discover#

After the first trace arrives, click Find Findings. Provon runs the enabled diagnostic Rules against the most recent conversation and shows any produced Findings.

Discover is the fastest way to confirm that:

  • traces are reaching the right project;
  • conversation identity is stable;
  • the trajectory can be reconstructed;
  • Rules produce reviewable output for your workload.

If no Finding appears, that can be correct. Healthy conversations and weak candidates are intentionally excluded. See No Findings appear from automatic diagnosis.

Success Check#

  • The organization and project exist and the project API key was copied before leaving the page.
  • At least one trace appears in Traces with a stable conversation identifier.
  • Find Findings either lists candidates or returns an empty result on a healthy conversation; an empty result is not a failure by itself.

Troubleshooting#

Symptom Likely cause Fix
No trace after the Connect step Exporter not flushed, or wrong project key Re-run one request; verify key matches the project; see Troubleshooting
Find Findings returns empty Healthy conversation or thresholds filtering candidates Expected on healthy sessions; check enabled Rules and thresholds on the Findings → Rules popover
Connector menu missing a tracker Connector not configured for the project Enable the tracker with token or OAuth; see Troubleshooting
Local CLI cannot reach the app PROVON_API_URL misconfigured Use https://api.provon.dev for hosted (no /v1 suffix); see Install

After onboarding#

Once onboarding is complete:

  • Open Traces to inspect the full trajectory.
  • Open Rules on the Findings page and enable at least one Rule so future conversations are analyzed automatically.
  • Open Findings to confirm, dismiss, or hand off supported problems.
  • On Findings, open the issue tracker menu to link GitHub, GitLab, Linear, or Jira for repair handoff.

Follow the Quickstart for the complete trace-to-Finding workflow, or continue with the repair loop.