Start here

Provenrail from zero: open a terminal, ship your first proof

Built your app by vibe-coding and never really touched a terminal? Good. This is the one page that takes you from a blank screen to a verified, tamper-evident record of what your AI agent did. Every keystroke is written out. You do not need to know how to code, and you do not need to install or understand Python.

Last updated 16 September 2026

0. What you need

That is the whole list:

• A computer running macOS, Windows, or Linux.
• An internet connection (only for the two install steps; recording itself works offline).
• About ten minutes.

You do not need Python, Node, Docker, an account, a credit card, or any prior command-line experience. Provenrail is the open-source tool that records what your AI agent did and lets anyone verify the record was not altered after the fact. We will install it, prove it works, then record a run of your own.

1. Open the terminal

The terminal is a plain text window where you type a command and press Enter to run it. Open it once and leave it open for the whole guide.

You will see a line ending in a symbol like %, $, or >, with a cursor next to it. That is the prompt: the computer waiting for you to type. To run any command in this guide, click into the window, type (or paste) the command, and press Enter.

2. Install uv (this handles Python for you)

uv is a tiny, fast tool that installs command-line apps and quietly brings its own copy of Python, kept separate from anything else on your machine. That one detail is why people who installed Python through other means sometimes watch their tools break after an update: those tools lean on a shared system Python that moves under them. uv does not. Install it once and you never think about Python again.

Copy the line for your system, paste it into the terminal, and press Enter.

$ curl -LsSf https://astral.sh/uv/install.sh | sh

> powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

It prints a few lines as it downloads, ending with something like installed uv and a note about your PATH.

$ uv --version
uv 0.11.6

3. Install Provenrail

One command. This installs the pr tool (that is the Provenrail command) in its own isolated space, so it can never clash with your other software.

$ uv tool install provenrail
Installed 3 executables: pr, pr-server, pr-verify

Check it is there by running pr on its own. It prints its list of commands, which means it is installed and working:

$ pr
Provenrail: a tamper-evident, independently verifiable record of what your AI agent did.

Start here (no account, nothing leaves your machine):
  pr demo            create a sample sealed run

4. The first useful answer: what your agents already did

Most tools give you nothing until you change how you work. This one does not. If you have ever used Claude Code on this computer, it has already written a file for every session, quietly, in a folder called ~/.claude/projects. One command reads all of them and tells you what those sessions cost, what they ran, what they touched, and which of their commands Provenrail's rules would have stopped.

$ pr report

It takes a minute or two on a big pile of sessions and prints something like this. These are one machine's numbers on 16 September 2026, trimmed, not a benchmark:

PROVENRAIL REPORT

  942 sessions across 23 projects, over 31 days,
  ran 79,883 tool calls and spent an estimated
  $7,863.51.
  517 of those would have been stopped: 23 refused,
  494 sent to you to approve.

  2,163 transcripts, 3.79 GB, 128.0s

Nothing was set up, no account was made, and nothing left the machine: there is no network call anywhere in this command. If you have never run Claude Code, it will say it found no transcripts, which is the honest answer rather than an empty report.

Three flags are worth knowing on the first run. pr report --since 2026-09-01 limits it to the last few weeks. pr report --project myapp narrows it to projects whose name contains myapp. And pr report --share prints the version that is safe to paste in public: the path to your home folder is gone, every project name is replaced by a short hash, and every command is cut down to its verb and flags so no file path, hostname or API key can be hiding in it.

5. Your first proof, with no code at all

Before touching your own agent, prove the whole idea in two commands. The first creates a small sample run and seals it into a file called a bundle. The second checks that bundle, recomputing every hash and signature, and tells you whether anyone tampered with it.

$ pr demo
Recorded a 6-event demo run and sealed it into bundle.json.

Now prove it is tamper-evident. Re-derive every hash and signature, trusting nothing:
  pr verify bundle.json

$ pr verify bundle.json
[info] summary: 6 records, 1 anchors, 0 heartbeats.
RESULT: VERIFIED
The warn/info lines above are advisory context, not failures.

That green VERIFIED is the entire product in one word. The verifier trusted nobody: not us, not the file, not your network. It re-derived the record from scratch and confirmed it is intact. Want to feel the other side? Open bundle.json in any text editor, change a single character inside it, save, and run pr verify bundle.json again. It will report TAMPERING DETECTED and refuse to pass. That is the point: a changed record cannot pass.

6. Record a run of your own agent

Now record something yourself. We will keep it to a tiny example with no AI keys required, so it runs anywhere. Once you see it work, swapping in your real agent is one line (next section).

$ mkdir my-first-agent
$ cd my-first-agent

$ pr quickstart
started a local sink (pid 12345) and wrote .provenrail.json

See it work right now, without writing any code:
    pr demo                   # records a real run and writes bundle.json
    pr verify bundle.json     # recomputes everything, trusts nobody

Then record your own agent. The whole setup is two lines:
    import provenrail as fr
    with fr.record('my-agent'):
        ...   # your agent runs; calls are captured automatically

$ pr demo
$ pr verify bundle.json
RESULT: VERIFIED

import provenrail as fr

with fr.record("my-first-agent") as run:
    run.record_model_call(
        "anthropic", "claude-opus-4-8",
        request={"prompt": "Summarize the contract."},
        response={"text": "Three key risks: A, B, C."},
        usage={"input": "640", "output": "180"},
    )
    run.record_decision("answer is grounded; returning to user", confidence="high")
    run.record_human_oversight("approved", approver="[email protected]")

print("Done. The run was captured and sealed off-box.")

$ cat > my_first_agent.py <<'EOF'
import provenrail as fr
with fr.record("my-first-agent") as run:
    run.record_model_call("anthropic", "claude-opus-4-8",
        request={"prompt": "Summarize the contract."},
        response={"text": "Three key risks: A, B, C."},
        usage={"input": "640", "output": "180"})
    run.record_decision("answer is grounded; returning to user", confidence="high")
    run.record_human_oversight("approved", approver="[email protected]")
print("Done. The run was captured and sealed off-box.")
EOF

$ uv run --with provenrail python my_first_agent.py
Installed 26 packages in 19ms
Done. The run was captured and sealed off-box.

$ pr export my-run.json
wrote my-run.json (5 records, 1 anchors). Verify it yourself with:
    pr verify my-run.json

$ pr verify my-run.json
RESULT: VERIFIED

$ pr report --regime eu-ai-act my-run.json --md > report.md

$ pr pack my-run.json --out evidence.zip
Wrote 12893 byte evidence pack to evidence.zip (regime=generic)   # exact size varies by run
Contents: MANIFEST.json, VERIFY.txt, bundle.json, cover.html, evidence-report-generic.json, evidence-report-generic.md, report.html

$ pr quickstart --stop
stopped the local Provenrail sink

7. Capture your real AI calls automatically

The example above logged events by hand so it would run with no API keys. In a real app you do not write those lines yourself. You hand Provenrail your OpenAI or Anthropic client once, and every model call inside the recorded block is captured for you:

import provenrail as fr
from openai import OpenAI

client = OpenAI()

with fr.record("billing-agent", clients=[client]):
    client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "..."}],
    )
    # every call your agent makes in here is recorded, no extra lines

Anthropic works the same way: pass your Anthropic client in clients=[...]. LangChain and MCP are supported too, and anything else records with one explicit line. Full reference lives in the docs.

8. Share a proof and go live

Everything so far ran free on your own machine, and it stays that way. Your records never move. What a paid plan adds is the one thing you cannot produce yourself: an independent party who wrote down what your chain looked like, at a time you did not choose. You send a 32-byte fingerprint of your records and keep every record. Your client or auditor gets a receipt they can check without an account and without trusting you, carrying a timestamp from a public time authority. This runs at provenrail.com today, and every account gets one anchor free, so you can hold the receipt before you decide anything:

pr anchor-push bundle.json
pr anchor-verify bundle.json anchor-receipt.json

1. Go to provenrail.com/account and sign in with your email (you get a one-click magic link, no password).
2. Pick a plan. After payment your account page shows a license key that starts with prl_live_.
3. Activate it in your terminal:

   $ pr activate prl_live_your_key_here
   License valid: anchored statements (no expiry). Verified offline, nothing was sent anywhere.

The key is checked on your own machine, offline. From then on your runs can carry trusted timestamps and shareable proof links. See pricing for what each tier includes.

If something goes wrong

Almost every first-time snag is one of these. Find your message on the left.

Still stuck? Email [email protected] with the exact command you ran and the exact message you saw, and we will get you moving.

FAQ

Do I need to know how to code?

No. Steps 1 through 5 are pure copy and paste and give you a real verified proof. Recording your own agent (step 6) means pasting one short file; you do not need to understand it to run it.

Do I need Python installed?

No. uv brings its own Python, and the uv run command uses it. You never install or manage Python yourself.

Does it matter which folder I am in?

For installing (steps 2 and 3) it does not matter at all. For recording your own run (step 6), make a folder and cd into it first, so the config file and your script live together. The recorder reads the config from the folder you run your script in.

Do I have to keep the terminal open?

Keep it open while you work through the guide. The local recorder from pr quickstart runs until you run pr quickstart --stop or close the terminal. Installed tools like pr and uv stay installed forever; you do not reinstall them.

Is any of my data sent to Provenrail?

No, and not on a paid plan either. Installing, recording and verifying all happen on your own machine and work offline. Your agent records stay in your own sink. A paid plan sends one thing: the Merkle root of your chain and how many records it covers. There is no field in that request a record could travel in.

Does this work on Windows?

Yes. Use the Windows lines where this page shows them (opening the terminal, and the uv install command). Everything else is identical.

What is the difference between this and the docs?

This page assumes nothing and spells out every keystroke. The docs are the faster reference once you are comfortable in a terminal.