Configuration

What you'll learn

• the two ways to give the SDK a setting, and which one wins;
• every FOXY_* setting, in one table;
• the settings you can only give in code;
• how to keep your settings when you close the terminal;
• recipes for common setups.

Two ways to give a setting

You can give most settings in two ways:

1. In code, as an argument: FoxyClient(mode="block").
2. In the environment, as an environment variable: FOXY_MODE=block.

When both are given, the code wins. When neither is given, the SDK uses the default. So the order is: argument, then environment variable, then default.

A setting the SDK cannot read, such as a misspelled value in the environment, falls back to its default, and your program starts as usual. Two things do stop a client from being made, with an error at once:

• a mistake in code, such as a plain http:// address to another machine passed as endpoint;
• with an API key set, a spool file in a folder your program cannot write to.

Every setting

Case and spaces around the value do not matter, but the words do:

• FOXY_AUDIT_REQUIRED is on for 1, true, yes or on, and off for 0, false, no, off or nothing. Any other value leaves it off, and says so in the log.
• FOXY_ALLOW_INSECURE is off unless the value is 1, true or yes. Any other value, even on, leaves it off.
• FOXY_ORG_POLICY and FOXY_INJECTION_CLASSIFIER are on unless the value is 0, false, no or off. Any other value leaves them on.

Your commitment key. Your hashes are made with a key of your own, which Foxy Audit never sees. If you set none, the SDK makes one when a client first starts with an API key. It keeps the key in a file called commitment.key, next to the spool, and only you can read it. Every program that shares the spool uses the same key.

Back that file up. foxy explain needs the key to prove a record later. Without it, you cannot prove which text a record's hashes came from. The chain still checks out without it.

In a container or a serverless function, the disk does not last, so a new key would be made at each start. There, set FOXY_COMMITMENT_KEY from your secret store, or mount the key file from a volume that lasts.

If the key file can be neither read nor made, the SDK uses your API key, and logs a warning. It also warns when FOXY_COMMITMENT_KEY is your API key, because Foxy Audit receives that key with every request.

With audit_required=True in your code, the SDK is strict about this. If the key file can be neither read nor made, the client does not start: it raises an error that says why and how to fix it. With FOXY_AUDIT_REQUIRED instead, the SDK logs an error and goes on with your API key.

Settings you give in code only

A few settings have no environment variable. You pass them to FoxyClient(...):

The environment settings above can also be given in code, with the same names in lower case: api_key, endpoint (for the backend URL), mode, response_scan, audit_required, commitment_key, commitment_key_path (for the key file), salt_sidecar_path, spool_path, client_id, system_id and injection_classifier.

Five environment settings have no argument on FoxyClient: FOXY_ALLOW_INSECURE, FOXY_ORG_POLICY, FOXY_ORG_POLICY_TTL, FOXY_SPOOL_MAX_ROWS and FOXY_SPOOL_RECEIPT_TTL. They belong to whoever runs the machine, not to the code, so you set them in the environment. FOXY_OLD_API_KEY is read only by foxy spool rekey.

Step 1: Keep your settings

A setting you type in a terminal lasts until you close it. To keep it, put it where your program starts:

• On a server, set it in the service's own settings, for example the environment section of a service file or a container's environment.
• On your own computer, add the export lines to your shell's start-up file. On Windows, open Start and search for "Edit environment variables for your account".

Keep your API key out of your code and out of version control. Anyone who has it can write records into your ledger.

Step 2: See what the SDK is using

from foxy_audit import FoxyClient

foxy = FoxyClient()
print(foxy.enabled, foxy.cfg.endpoint, foxy.cfg.mode)

What you should see, with nothing set:

False http://127.0.0.1:8000 observe

foxy.enabled is True when an API key is set, which means records will be sent. foxy.cfg holds every resolved setting. It is read-only. To change a setting, make a new client.

The backend address, in detail

The SDK sends your API key with every request, so it is careful about where the key goes:

• An https:// address is fine, to any machine.
• A plain http:// address is allowed only to this machine: 127.0.0.1, ::1, or localhost. A name that happens to point at this machine is not enough; write 127.0.0.1.
• A plain http:// address to any other machine is refused, unless you set FOXY_ALLOW_INSECURE=1.
• An address that two parts of Python would read in two different ways is always refused, even with FOXY_ALLOW_INSECURE.

Where the address came from changes what a refusal looks like:

The SDK never follows a redirect when it sends your key. If your backend answers with a redirect, set the address to the place it redirects to.

Records are kept for the address they were made for. After you change the address, records made for the old one stay in the spool, and a notice in foxy doctor counts them. Move them to the new address with foxy spool rekey --from-backend <the old address>, with FOXY_OLD_API_KEY set to your key. See If your API key changes.

The response scan and regulated data

FOXY_RESPONSE_SCAN controls the check on the model's answers. It is observe by default, so it records findings and never stops an answer. For PHI and other regulated data, set block: then an answer the scan flags never reaches your code. The scan is a set of patterns, so an answer that does harm in a way no rule matches still gets through. What block costs is explained under Which to choose in Response scanning.

The injection classifier's cost

The classifier runs on your machine, before the model call, and its cost grows with the length of the prompt. Here is how long the whole prompt check took, measured on one development laptop on 2026-09-30, with Python 3.13, best of three:

These numbers are from one machine on one day, so measure your own. There is no length limit, on purpose: a limit would give an attacker a place to hide. If your prompts are very long and speed matters more than this check, set FOXY_INJECTION_CLASSIFIER=off. The six pattern rules keep running.

The setting belongs to each client. check() and the foxy command read the environment variable.

Recipes

Trying it out, with no account: set nothing. Checks and hashes run on your machine, and nothing is sent.

Connected, for a first test:

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

Regulated work, where every call must be recorded:

export FOXY_API_KEY="YOUR_API_KEY"
export FOXY_BACKEND_URL="https://app.foxyaudit.tech"
export FOXY_MODE=block
export FOXY_RESPONSE_SCAN=block
export FOXY_AUDIT_REQUIRED=true

In a container: add a lasting volume, and point the spool at it.

export FOXY_SPOOL_PATH=/data/foxy/spool.sqlite3

No internet, or only your code decides:

export FOXY_ORG_POLICY=off

If it goes wrong