Your first signed forensic report, one step at a time.
This guide assumes no coding experience. If you can copy a line of text and paste it, you can produce a real, cryptographically signed evidence chain on your own computer. Nothing is sent to us. Everything runs locally.
Pick your computer above. The instructions below update to match it.
What you are about to do, in plain words
A small, free, open-source program. You install it once. It adds a command named air to your computer.
One command, air demo, creates a realistic record of an AI agent doing something dangerous, and signs every step.
You get a tamper-evident file showing exactly what happened, in order, signed so no one can quietly change it later.
Project AIR ships 16 detectors (10 OWASP Agentic, 3 OWASP LLM, 3 AIR-native). The demo runs the detectors that work fully offline; two NemoGuard detectors need an NVIDIA NemoGuard NIM and stay off in the demo.
Open a terminal
A terminal is a window where you type commands instead of clicking buttons. It looks intimidating; it is just a text box. Here is how to open it.
- Press Command and the Space bar together. A search box appears.
- Type the word Terminal.
- Press Return. A window opens. That is your terminal.
Tip: to run any command below, click Copy, click inside your terminal window, paste (Command V), then press Return.
Make sure you have Python 3.12 or newer
Project AIR runs on Python, a free programming language your computer may already have. First, check. Copy this line into your terminal and press enter.
If you see a number like Python 3.12.4 or higher, you are set. Skip to Step 2. If you see an error, or a number below 3.12, install Python:
Install Homebrew if you do not have it, then run:
Or download the official installer from python.org/downloads/macos and double-click it.
Install Project AIR
We recommend a tool called pipx, which installs the air command cleanly without touching anything else on your computer. First install pipx:
Now install Project AIR itself:
Already comfortable with Python? Use pip instead.
Inside a virtual environment or project, you can run pip install projectair. The package name on PyPI is projectair; the command it gives you is air.
Check that it worked
Ask the tool for its version. You should see a version number, not an error.
Now run the demo. This is the moment it all becomes real.
If you see that last green line, congratulations. You just generated and verified a real signed evidence chain. No account, no internet required, no configuration.
Read what you produced
The demo wrote two files into the folder your terminal is currently in: a chain file and a report. Open the report to see a plain summary of what the agent did and what was flagged.
Want to prove the chain has not been tampered with, using only public infrastructure? Run:
Every record is hashed with BLAKE3 and signed with Ed25519 in-process, at the moment the action happens. Change any step after the fact and verification fails. That is what makes it evidence rather than a log.
Optional: record your own AI agent
This part is for people who write code. If that is not you, you are already done; the steps above are the whole guide. If you do build agents, instrumenting one is a few lines.
The manual way. Wrap your agent's actions with a recorder:
from airsdk import AIRRecorder
recorder = AIRRecorder("chain.jsonl")
recorder.llm_start(prompt="Analyze this data...")
recorder.llm_end(response="Here is the analysis...")
recorder.tool_start(tool_name="db_query", tool_args={"sql": "SELECT ..."})
recorder.tool_end(tool_output="42 rows returned")
recorder.agent_finish(final_output="Task complete")Already using a framework? One line connects it. Same signed chain, no boilerplate.
from airsdk import AIRRecorder
from airsdk.integrations.openai import instrument_openai
recorder = AIRRecorder("chain.jsonl", user_intent="Draft a report")
client = instrument_openai(OpenAI(), recorder)from airsdk import AIRRecorder
from airsdk.integrations.anthropic import instrument_anthropic
recorder = AIRRecorder("chain.jsonl", user_intent="Draft a report")
client = instrument_anthropic(Anthropic(), recorder)from airsdk import AIRRecorder, AIRCallbackHandler
recorder = AIRRecorder("chain.jsonl")
agent.run("task", callbacks=[AIRCallbackHandler(recorder)])from airsdk import AIRRecorder, instrument_gemini
recorder = AIRRecorder("chain.jsonl")
client = instrument_gemini(genai.Client(), recorder)from airsdk import AIRRecorder
from airsdk.integrations.llamaindex import instrument_llamaindex
recorder = AIRRecorder("chain.jsonl")
llm = instrument_llamaindex(LlamaOpenAI(model="gpt-4o"), recorder)Any OpenAI-compatible endpoint also works through instrument_openai, including NVIDIA NIM, vLLM, Together AI, Groq, and Fireworks.
The commands worth knowing
air demoRun the full demo. A real signed chain in about 30 seconds, no setup.air demo --scenario healthcareHIPAA-aligned clinical AI demo.air trace chain.jsonlReplay a chain, verify signatures, run detectors, export a report.air verify-public chain.jsonlVerify using only public infrastructure, zero Vindicara calls.air explain --finding ASI02Plain-language causal explanation for one finding.air verify-intent chain.jsonlDid the agent actually do what it declared it would?air report article72Generate an EU AI Act Article 72 report.If something goes wrong
air: command not found
Run pipx ensurepath, then close and reopen your terminal. As a fallback, run python3 -m projectair.cli demo.
Python version too old
Project AIR needs Python 3.12 or newer. Check with python3 --version. If you have several versions, target one explicitly, for example python3.13 -m pip install projectair.
Permission errors during install
Never use sudo pip install. Use pipx, or create a virtual environment: python3 -m venv .venv && source .venv/bin/activate && pip install projectair.
Still stuck
Open an issue on GitHub, or email support@vindicara.io. Tell us your operating system and paste the exact error.
That is the whole loop. Detect, sign, prove.
Read the full documentation and architecture on GitHub, or talk to us about putting signed evidence behind your production agents.