# 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. From that verified evidence path you can continue
into Knowledge extraction, Dataset collection, or model improvement.

If you have not installed Provon yet, see [Install Provon](./install.md). If you prefer to follow the
built-in Workbench setup flow, see [Workbench onboarding](./workbench-onboarding.md).

## Prerequisites

- A Provon project in the hosted Workbench or a local/self-hosted deployment. See
  [Install Provon](./install.md).
- 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](./workbench-onboarding.md)
walks you through creating an organization, project, and API key.

### Self-hosted or local development

For a one-line self-hosted install:

```bash
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:

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

> [!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/v1"
```

For local development use:

```bash
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:

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

For local development use:

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

Send a 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": "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](../ai-gateway/quickstart.md) for first-request and evidence verification,
then use the [migration guide](../ai-gateway/migration.md) for a staged production change,
[SDK integrations](../ai-gateway/integrations.md) for client configuration, and the
[Gateway overview](../ai-gateway/index.md) to find routing, governance, production, and API reference pages.
You can also run the curl examples in [`examples/gateway-endpoints`](https://github.com/provon/provon/tree/main/examples/gateway-endpoints).

### Path B: OpenTelemetry

For hosted Provon:

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

For local development:

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

Point an existing OTLP/HTTP exporter at Provon:

```bash
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](../tracing/quickstart.md) for a transparent first OTLP trace. See
[OpenTelemetry setup](../tracing/opentelemetry.md) for Python, Node.js, Collector, and SDK configuration.
Use the [OTLP/HTTP API](../api/otlp.md) for transport, response, limit, and retry details.
Runnable observability examples are in
[`examples/agent-observability-*`](https://github.com/provon/provon/tree/main/examples).

### 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:

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

If you are working from the source repository:

```bash
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:

```text
~/.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](../tracing/agent-transcripts.md) 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.

> [!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](./troubleshooting.md) for the
> full checklist.

## 5. Enable diagnostics

If you followed [Workbench onboarding](./workbench-onboarding.md), 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](../findings/rules.md) for Rule configuration, confidence thresholds, and signal overrides, and [Findings](../findings/index.md) 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:

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