Start here
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.
$ are commands you type into the terminal. Do not type the $ itself. Type or paste the rest, then press Enter. The greyed-out lines under a command are what the computer prints back, so you can check you are on track.That is the whole list:
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.
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.
Press Cmd + Space to open Spotlight, type Terminal, and press Enter. A small window opens with a blinking cursor.
Press the Windows key, type Terminal (or PowerShell), and press Enter. If you have neither, type cmd instead. Any of them works.
Press Ctrl + Alt + T, or open your applications menu and search for Terminal.
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.
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.
macOS / Linux$ 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 command. To confirm it worked, run:
$ uv --version
uv 0.11.6If you see a version number, you are set. If instead you see command not found, jump to If something goes wrong.
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-verifyCheck it is there by running pr on its own. It prints its list of commands, which means it is installed and working:
$ pr
usage: pr [-h] {serve,activate,demo,verify,disclose,report,pack,diff,quickstart,...} ...pr says command not found, close and reopen the terminal once (the same PATH reason as uv), then try again. Still stuck? See troubleshooting.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 6 events to bundle.json
Client pin written to pin.json
$ pr verify bundle.json
[info] summary: 6 records, 1 anchors, 0 heartbeats.
RESULT: VERIFIEDThat 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.
[warn] lines, and that is expected on the free plan. They say things like "local anchor only" and "not witnessed": the record carries your own machine's time, not a trusted third-party timestamp. That timestamp, plus witness cosignatures, is the paid Builder feature. The integrity proof is identical on every plan, so the line that matters here is the last one: RESULT: VERIFIED. Warnings are guidance, not failures; only TAMPERING DETECTED is a failure.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).
A folder keeps the files for this run together. mkdir makes the folder; cd ("change directory") steps into it. Every command after this runs inside that folder.
$ mkdir my-first-agent
$ cd my-first-agentThis starts a small local recorder in the background and writes a tiny config file so your code needs zero setup. It runs entirely on your own computer.
$ pr quickstart
started a local sink (pid 12345) and wrote .provenrail.json
Now your whole setup is two lines:
import provenrail as fr
with fr.record('my-agent'):
... # your agent runs; calls are captured automaticallyIn the same folder, make a file named my_first_agent.py with the code below. If you use VS Code, Cursor, or any editor: choose File, New File, paste this in, and save it as my_first_agent.py inside the my-first-agent folder.
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.")No editor open? On Mac or Linux you can create the file straight from the terminal by pasting this whole block at once and pressing Enter:
$ 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."})
run.record_decision("grounded; returning to user", confidence="high")
print("Done. The run was captured and sealed off-box.")
EOFThis one command runs your script. The uv run --with provenrail part means uv quietly fetches what the script needs into a throwaway environment, so you never install or manage Python yourself.
$ uv run --with provenrail python my_first_agent.py
Installed 26 packages in 19ms
Done. The run was captured and sealed off-box.That is a real, signed, tamper-evident record of your run, sealed and stored by the recorder. "Off-box" means it is written somewhere your agent code cannot quietly rewrite, which is the whole point of an independent record.
Now close the loop on your own data. pr export pulls your sealed run out of the recorder into a bundle; pr verify then recomputes every hash and signature and confirms it is intact, trusting nobody.
$ pr export my-run.json
wrote my-run.json (4 records, 1 anchors). Verify it yourself with:
pr verify my-run.json
$ pr verify my-run.json
RESULT: VERIFIEDThat is the whole promise, on your own machine, for free: a record of what your agent did that you can prove was not altered after the fact. Tamper with one character of my-run.json and re-verify to watch it fail.
A green VERIFIED is the proof. The value is what you do with it. Two commands turn your run into a deliverable, both free and on your own machine.
A readable report for a client or auditor:
$ pr report --regime eu-ai-act my-run.json --md > report.mdThat writes a plain-English report.md: what was recorded, whether integrity verified, a breakdown of the events, and how they map to EU AI Act Article 12. Swap in --regime hipaa or --regime generic for other contexts. On this free local setup the report honestly notes that the recorded times are self-asserted; the Builder plan adds RFC 3161 trusted time so an auditor can rely on the timing too.
A self-contained evidence package for an auditor:
$ pr pack my-run.json --out evidence.zip
Wrote 12893 byte evidence pack to evidence.zip (regime=generic) # exact size varies by run
Contents: bundle.json, attestation, VERIFY.txt, MANIFEST.jsonHand over evidence.zip. It carries the run, a written attestation, and a VERIFY.txt that tells the recipient exactly how to check it themselves with the open-source verifier, trusting nothing you say. That is the whole pitch: you do not ask them to trust you, you hand them proof they can verify.
$ pr quickstart --stop
stopped the local Provenrail sinkThe 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 linesAnthropic 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.
Everything so far ran free on your own machine. When you want a teammate, a client, or an auditor to verify a run without installing anything, Provenrail can host the record behind a shareable proof link and add a trusted timestamp from an independent authority. That is the paid tier.
prl_live_.$ pr activate prl_live_your_key_here
License valid: builder tier (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.
Almost every first-time snag is one of these. Find your message on the left.
| What you see | What to do |
|---|---|
command not found: uv or pr | The terminal has not picked up the newly installed command yet. Close the window completely and open a brand-new one, then try again. This fixes it the vast majority of the time. |
command not found: python or python3 | You do not need a system Python. Use the uv run --with provenrail python ... command exactly as written; uv supplies Python for you. |
| You installed Python with Homebrew and tools broke | Use the uv tool install provenrail path on this page instead of pip. uv keeps its own Python, so a brew upgrade can never orphan it. |
permission denied during install | Do not add sudo. The uv and uv tool install commands here install into your own user space and never need administrator rights. |
pr verify says TAMPERING DETECTED | If you edited the bundle on purpose, that is the correct answer. If not, re-run pr demo to make a fresh, unaltered bundle and verify that. |
The cat > ... EOF block did nothing or hangs | That shortcut is for Mac and Linux only. On Windows, create the file in Notepad or VS Code instead (step 3, first method). |
| Nothing happens after I paste | You probably did not press Enter. The command only runs when you press Enter. Paste one command at a time. |
Still stuck? Email [email protected] with the exact command you ran and the exact message you saw, and we will get you moving.
uv run command uses it. You never install or manage Python yourself.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.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.