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

## 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](./gateway-quickstart.md) for first-request and evidence verification,
then use the [migration guide](./gateway-migration.md) for a staged production change,
[SDK integrations](./gateway-integrations.md) for client configuration, and the
[Gateway overview](./gateway.md) 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](./tracing-quickstart.md) for a transparent first OTLP trace. See
[OpenTelemetry setup](./opentelemetry.md) for Python, Node.js, Collector, and SDK configuration.
Use the [OTLP/HTTP API](./otlp-api.md) 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](./agent-transcripts.md) 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](./troubleshooting.md) 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](./findings.md) 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

- Review the [trace model](./tracing-model.md).
- Use the [tracing attribute reference](./tracing-attributes.md).
- Apply the [diagnosis-ready tracing checklist](./tracing-best-practices.md).
- Model participant ownership with [multi-agent and distributed tracing](./tracing-multi-agent.md).
- Investigate in the [Workbench](./trace-explorer.md) or with the [CLI](./tracing-cli.md).
- Build against the [Trace read API](./trace-api.md).
- Run [trace diagnosis with CLI](./trace-diagnosis.md).
- Configure [production tracing](./tracing-production.md).
- Choose a [self-hosting runtime](./self-hosting.md).
- Add [connectors](./connectors.md).
- Use [troubleshooting](./troubleshooting.md) when a verification step fails.