Your first 10 minutes

What you'll learn

• how to install the SDK in its own space and check that it works;
• how to write and run your first program with it, offline;
• how to ask the SDK what it thinks of a prompt;
• how to get an API key and connect to Foxy Audit;
• how to see your records in the dashboard;
• how to check the proof yourself, without trusting us.

Steps 1 to 4 need no account and no internet, once the SDK is installed. Steps 5 to 8 need a Foxy Audit account.

What you need

• A computer with Python 3.9 to 3.13. To check, open a terminal and type python3 --version on a Mac or Linux, or py --version on Windows. On Windows, typing python when Python is not installed may open the Microsoft Store instead.
• A terminal. On Windows, use PowerShell. On a Mac, use the Terminal app.
• For steps 5 to 8, an internet connection and a Foxy Audit account. A free one is fine.

The package lists Python 3.9 to 3.13. A newer Python, such as 3.14, can install it too, but it is not tested there yet. If something fails on a newer Python, use one from the list.

In this chapter, lines that start with python, py or foxy are commands. Type them in the terminal and press Enter.

Step 1: Make a space for the SDK, and install it

Give the SDK its own Python space, called a virtual environment. Many systems refuse to install packages into their own Python, with the message externally-managed-environment. A virtual environment avoids that, and it keeps this test apart from your other work.

Make a new folder for this test, open a terminal in it, and type these commands.

On a Mac or Linux:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install foxy-audit

On Windows, in PowerShell:

py -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install foxy-audit

If PowerShell says that running scripts is disabled on this system, type Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass, then the activate line again. That change lasts only for this terminal window.

Once the space is active, python and foxy in this terminal use it. If you open a new terminal, run the activate line again.

Pip downloads the package and the few small packages it needs. Near the end it prints a line that starts with Successfully installed. It may print a notice about a newer pip after that, which you can leave for now.

Now check which version you have:

python -c "import foxy_audit; print(foxy_audit.__version__)"

What you should see:

1.18.0

This manual is for version 1.18.0. If you see a lower number, read Installing and upgrading before you go on.

Step 2: Write your first program

In the same folder, make a file called hello_foxy.py. Copy this code into the file and save it:

from foxy_audit import FoxyClient, FoxyPolicyBlocked

# No API key yet, so nothing goes over the network. "block" means: stop a risky prompt.
foxy = FoxyClient(mode="block")


def show(receipt):
    print("Recorded:", receipt["event_type"], "- queued for the ledger:", receipt["submitted"])


foxy.on_event = show


@foxy.audit(policy="hipaa")
def ask_model(prompt):
    # A stand-in for your real model call. It repeats the prompt back.
    return "You said: " + prompt


print(ask_model("What is the capital of France?"))

try:
    ask_model("My social security number is 123-45-6789")
except FoxyPolicyBlocked as error:
    print("Blocked:", error)

Here is what each part does:

1. FoxyClient(mode="block") makes a client. The client holds your settings. There is no API key yet, so the SDK saves nothing and sends nothing over the network.
2. show is a small function of yours. The SDK calls it after each call to the model, with a receipt. The receipt says what was recorded.
3. @foxy.audit(policy="hipaa") is the decorator. Because the client's mode is block, it checks the prompt of every call to ask_model before the call. The hipaa tag means it also looks for personal data.
4. ask_model stands in for your real model call. In your own program, this function would call your AI model.
5. The last lines call ask_model twice: once with a safe question, and once with a social security number.

Step 3: Run it

python hello_foxy.py

What you should see:

Recorded: interaction - queued for the ledger: False
You said: What is the capital of France?
Recorded: blocked - queued for the ledger: False
Blocked: Foxy Audit blocked a prompt under policy 'hipaa' (reason: phi). The wrapped function was not called.

Here is what happened:

1. The safe question went through. The SDK recorded it as an interaction, and your function returned its answer.
2. The second prompt had a social security number in it. The SDK stopped it before ask_model could run, so your "model" never saw it.
3. The SDK recorded the stop as blocked, then raised FoxyPolicyBlocked. Your except line caught it and printed the message.
4. Both receipts say queued for the ledger: False, because there is no API key yet.

Step 4: Ask the SDK about a prompt

You can ask the SDK what it thinks of a prompt without calling any model. The foxy command came with the package:

foxy check "My social security number is 123-45-6789" --policy hipaa

What you should see:

[X] policy=hipaa  ruleset=2026.09.3
  triggered : True
  reason    : phi
  rules     : phi.ssn_pattern
  signals   : ssn_pattern

The rule phi.ssn_pattern fired. foxy check never prints your prompt back, and it sends nothing anywhere.

On most terminals the first mark is a red cross, and a clean prompt gets a green tick. This manual prints the plain forms, [X] and [OK], which the SDK uses where a terminal cannot show those symbols. Arrows work the same way: -> stands for an arrow.

Step 5: Get your API key

To send records to Foxy Audit, you need an API key. An API key is a secret that tells Foxy Audit which workspace a record belongs to.

• If you are new: sign up at foxyaudit.tech. After sign-up, the welcome page shows your key. It is shown only once, so copy it somewhere safe right away.
• If you already have an account: sign in to the dashboard at app.foxyaudit.tech. Choose Access in the menu, then + new key. The new key is also shown only once.

A new workspace may need to be reviewed before it can record anything. If the welcome page says your workspace is being reviewed, your key works from the moment it is approved. You get an email then.

Treat the key like a password. Do not put it in your code, and do not share it. In this manual it is written as YOUR_API_KEY.

Step 6: Connect the SDK

The SDK reads two settings from your terminal: your key and the address of the Foxy Audit backend. Put your own key where it says YOUR_API_KEY.

On a Mac or Linux:

export FOXY_API_KEY="YOUR_API_KEY"
export FOXY_BACKEND_URL="https://app.foxyaudit.tech"

On Windows, in PowerShell:

$env:FOXY_API_KEY = "YOUR_API_KEY"
$env:FOXY_BACKEND_URL = "https://app.foxyaudit.tech"

These settings last until you close the terminal. Configuration shows how to keep them.

Now ask the SDK to check the whole path:

foxy doctor

What you should see: lines like these. The parts in angle brackets depend on your workspace.

Foxy Audit · doctor
  backend : https://app.foxyaudit.tech
  pet     : 127.0.0.1:9999
  [OK] Local delivery: 0 event(s) pending in the spool.
  -> Deep PII detection (presidio): not installed, regex detection only. `pip install foxy-audit[pii]` adds it.
  -> Commitment key: none yet. Your program makes one at <home>/.foxy-audit/commitment.key when it starts with your API key. Back that file up.
  [OK] Backend reachable + authenticated: test log accepted (HTTP 202).
  -> Evaluator configured: <provider> (<model>); verdicts are advisory.
  -> No desktop pet is listening on 127.0.0.1:9999. That is fine: the app is optional.
  [OK] Server reports its ledger intact: <count> entries. That is the server's own check, not an independent one: export the ledger and run foxy_verify.py (in the export bundle) to verify it yourself.

All set: your calls are flowing end-to-end.

foxy doctor sends one real test record, with the tag foxy_doctor, so you will see it in your ledger. On a terminal that can show it, the last line ends with a small fox.

Some lines may differ, and that is fine:

• The commitment key line says where the key for your hashes is kept. Your program makes that file the first time it runs with your API key. Back it up. Without it, you cannot prove later which text a record came from.
• Arrow lines under the delivery line are notices. For up to an hour after the first run of version 1.18.0, one may say that the spool still holds old keys in its unused space until it is cleaned. Another may say that records are waiting under a different key. Notices need no action, and they never change the exit code.
• With no AI judge set up in your workspace, the evaluator line reads [X] Evaluator unavailable; graded fallback results remain unknown. Your records are then graded by fixed rules. This line never changes the exit code either.
• The desktop pet line says that no desktop pet is listening when the optional desktop app is not running. With the app open, it says to watch the fox, and a second line says a capture signal was sent. On Windows it can also say that with no app running, because Windows does not always send the refusal that tells the SDK nothing is there. Nothing depends on it.

Now run your program again:

python hello_foxy.py

The first time, the SDK also prints a warning first. It says that it made your commitment key, and where. That happens only once.

The four lines are the same as before, except that both receipts now say queued for the ledger: True. That means each record was saved on your disk and queued for sending. The next chapter explains what happens if the network is down.

Step 7: See your records in the dashboard

1. Open app.foxyaudit.tech and sign in.
2. Choose Ledger in the menu.
3. Look for your new records: the test record from foxy doctor, the interaction from the safe question, and the blocked one.

The dashboard shows the hashes and labels. It cannot show your prompts, because it never had them.

Step 8: Check the proof yourself

Now check your records with the free verifier. You do not have to trust the dashboard for this.

1. In the dashboard, choose Export in the menu.
2. Pick Verification bundle · ZIP, then choose Generate export.
3. Save the file. It is called foxy-audit-export.zip.
4. Unzip it. The folder holds your ledger (foxy-audit-logs.json) and the verifier (foxy_verify.py), with a short guide and the verifier's licence.
5. Open a terminal in that folder and run the verifier:

python foxy_verify.py foxy-audit-logs.json

What you should see: lines like these. Your numbers and hash will differ.

[OK]   chain intact - <rows> rows verified from genesis
       head @ seq <rows> = <hash>
[--]   no anchor receipt in this export

If your workspace publishes an anchor, the last line instead says that the anchor receipt matches the chain.

Then keep the head. Copy the head line into a note you keep, away from Foxy Audit. Do it each time you check.

"Chain intact" means every record still links to the one before it, all the way back to the first. The links use no secret, though. Someone who could rewrite the whole stored ledger could also work out new links, and a fresh export would still say "chain intact". What catches that is the head you kept: next time, the record with the same number must still have the same hash. The evidence model shows how to check it.

The verifier needs no internet and no account. You can give the same folder to an auditor, and they can run the same check.

If it goes wrong

What's next

• The decorator and the client shows how to add the SDK to your real model call.
• Modes explains observe, block and redact in detail.
• Troubleshooting helps when something else goes wrong.