Start

Install and configure

Install the package, add only the extras you need, decide where the database lives, and check the result with agentfox doctor.

When to use this

Before you put AgentFox in front of a real agent, and whenever you add a detector, move the database, or upgrade. For a first look, the Quickstart is enough. For a server, read Self-hosting after this page.

Install

AgentFox needs Python 3.11 or newer (requires-python = ">=3.11"). The core install is deliberately light: a web framework, SQLAlchemy, Alembic, Typer, and nothing that downloads model weights.

bash

python3 -m venv .venv && source .venv/bin/activate
pip install agentfox
agentfox --version

Output

agentfox 0.3.1

With uv, in a project:

bash

uv add agentfox

From source, for the latest commit:

bash

pip install "git+https://github.com/architsharm/agentfox.git"

The package installs one command, agentfox.

Extras

Each extra wraps a third-party engine, and each is optional. Add them in brackets: pip install "agentfox[pii,sql]". Installing an extra makes a detector available; it runs only once it is also listed in enabled_detectors (Configuration).

Extra	Installs	Enables
`pii`	presidio-analyzer, presidio-anonymizer	The pii.presidio detector. Also needs a spaCy model (below).
`classifiers`	transformers, torch	injection.classifier (PIGuard with a backstop model), injection.similarity (embedding match), safety.granite (Granite Guardian). Each needs its weights.
`sql`	sqlglot	SQL blast-radius and data-access analysis. Without it, SQL analysis fails closed rather than passing statements through.
`langgraph`	langgraph	The AgentFoxGuard node wrappers in agentfox.frameworks.langgraph.
`postgres`	psycopg[binary]	A Postgres database_url (postgresql+psycopg://…).
`otel`	opentelemetry-api, -sdk, -exporter-otlp-proto-http	OpenTelemetry trace export.
`rails`	nemoguardrails	The rails.nemo detector, once nemo_rails_config_path points at a NeMo Guardrails config.
`validators`	guardrails-ai	rails.guardrails_ai and the rails.hub.* detectors, once guardrails_ai_validators names installed Hub validators.
`redteam`	garak, pyrit	The wrapped Garak and PyRIT runners alongside the built-in probes (agentfox test probes lists them).
`bedrock`	boto3	The Amazon Bedrock model provider.
`vertex`	google-auth	The Google Vertex model provider.
`prometheus`	prometheus-client	Pushing metrics to a Prometheus push gateway. Scraping needs no extra.
`ragas`	ragas	Ragas scorers in evaluation suites.
`all`	pii, classifiers, rails, validators, redteam, otel, postgres, langgraph, sql	Every permissive extra. Excludes the cloud provider SDKs and restricted-classifiers.
`restricted-classifiers`	transformers, torch	safety.restricted (Llama Guard). Non-OSI licence: it also refuses to load unless AGENTFOX_ACCEPT_RESTRICTED_MODEL_LICENSES=1.
`dev`	pytest, pytest-asyncio, ruff, mypy	Working on AgentFox itself.

Five detectors need no extra and are on by default: injection.heuristic, pii.native, secrets.native, safety.lexicon and schema.json. agentfox.auto() needs no extra either; it patches whichever of openai, anthropic, litellm and langchain are already installed.

Detector weights

No detector downloads anything while handling a request. A model-backed detector whose weights are absent reports itself unavailable instead of reaching the network mid-decision. Fetch weights on purpose, once:

bash

python -m spacy download en_core_web_lg

That is the spaCy model for pii.presidio, about 400MB. The classifier detectors load from Hugging Face the same way (leolee99/PIGuard, protectai/deberta-v3-base-prompt-injection-v2, sentence-transformers/all-MiniLM-L6-v2, ibm-granite/granite-guardian-3.0-2b); the model names are settings. The gateway Docker image ships with the permissive ones already inside.

Then check which detectors this process can actually run:

bash

agentfox doctor

Output

…
  ✓    detectors           5 running: injection.heuristic, pii.native, safety.lexicon,
                           schema.json, secrets.native
…

Where state lives

AgentFox keeps a database and a directory of evidence packages. Where they go depends on how it is installed:

Situation	Database	Evidence packages
`AGENTFOX_STATE_DIR` is set	`$AGENTFOX_STATE_DIR/agentfox.db`	`$AGENTFOX_STATE_DIR/var/evidence`
Installed package (pip, uv)	`~/.agentfox/agentfox.db`, or `$XDG_DATA_HOME/agentfox/agentfox.db` when that is set	`~/.agentfox/var/evidence`
Running from a source checkout	`agentfox.db` at the repository root	`var/evidence` at the repository root

State is per installation, not per directory, so agentfox findings shows the same findings from wherever you type it. To keep two projects apart, give each its own AGENTFOX_STATE_DIR. AGENTFOX_DATABASE_URL and AGENTFOX_EVIDENCE_DIR override the two locations individually.

Postgres

SQLite is fine for one process. For a server, or more than one worker, use Postgres with the postgres extra:

bash

pip install "agentfox[postgres]"
export AGENTFOX_DATABASE_URL="postgresql+psycopg://agentfox:PASSWORD@db.internal:5432/agentfox"
agentfox init

Output

Setting up AgentFox
  ✓ database ready  postgresql+psycopg://agentfox@127.0.0.1:55439/agentfox
  ✓ 43 controls across 7 frameworks  v0.1.0-draft (draft)
  ✓ 3 policy pack(s) loaded
…

That output is from a local Postgres 16 cluster; use your own host and credentials. Create the database with UTF-8 encoding.

agentfox init and agentfox.toml

bash

agentfox init

Output

Setting up AgentFox
  ✓ database ready
sqlite:////…/agentfox.db
  ✓ 43 controls across 7 frameworks  v0.1.0-draft (draft)
  ✓ 3 policy pack(s) loaded
      baseline                 observe  recorded, nothing blocked
      eu-ai-act-high-risk      observe  recorded, nothing blocked
      tool-containment         enforce  violations are blocked now
      coding-agent not enabled — no coding-agent hooks in this repo. `agentfox admin hooks install
--agent <slug> --write` turns it on for that agent.
      tool-containment blocks from the start — demote with `agentfox policy observe <key>`.
  ✓ wrote agentfox.toml
…

It creates and migrates the database, loads 43 controls and the policy packs, and writes agentfox.toml in the current directory (or --path). Run it again and it changes nothing it does not need to: · agentfox.toml already exists, left alone. Three packs load in a plain repository; the fourth, coding-agent, applies only once a coding agent has hooks installed (Coding agents).

The generated file, exactly:

agentfox.toml

# AgentFox configuration.
# Everything here has a safe default; this file exists so the defaults are visible
# rather than implicit. The [agentfox] table is read from the working directory;
# environment variables (AGENTFOX_*) override it.

[agentfox]
environment = "development"

# Default mode for a policy that does not declare its own. Packs that declare a mode
# keep it (the shipped tool-containment pack declares enforce).
default_policy_mode = "observe"

# Zero egress: no model call leaves this machine unless you turn it on.
allow_egress = false

# The whole pre-flight pipeline's latency ceiling, in milliseconds.
enforcement_budget_ms = 300

# Where a tool call's provenance is read from, for the taint rules.
#   "session"  - the worst untrusted content anywhere in the run so far, or in the
#                call's own arguments. Contains more; escalates more benign calls.
#   "argument" - only what the call's own arguments were copied from.
# Every published number was measured under "session". docs/getting-started.md, step 5b.
taint_scope = "session"

How settings are read, highest precedence first:

AGENTFOX_* environment variables;
the [agentfox] table of $AGENTFOX_CONFIG if set (it must exist), otherwise of ./agentfox.toml in the working directory;
built-in defaults.

Keys are the setting names without the prefix. An unknown key is ignored with a warning that names it. AGENTFOX_CONFIG=none turns file loading off. Every key is on Configuration. Settings are read once per process, so restart after a change.

Check it: agentfox doctor

doctor grades the configuration, not the traffic. It changes nothing. On a fresh install:

bash

agentfox doctor

Output

Runtime check
  ✓    database            reachable — 0 agent(s), 0 trace(s)
  !    traffic             no decisions recorded — nothing has been governed yet. Add
                           `agentfox.auto()` to your entry point.
  !    authentication      the X-AgentFox-User header is accepted (environment=development,
                           auth_mode=auto) — anyone who can reach this port is any user they name.
                           Fine locally, unacceptable anywhere else.
  !    containment         no tools declared — nothing constrains what an agent may do when a
                           detector misses. Declare them with `agentfox declare tool <key>
                           --impact ...`.
  !    data scope          no table row-scoping declared — a query across every customer's rows
                           reads as ordinary. Declare with `agentfox declare scope <table>
                           --column ...`.
  ✓    detectors           5 running: injection.heuristic, pii.native, safety.lexicon,
                           schema.json, secrets.native
  ✓    providers           offline only (echo). No model call can leave this machine — set
                           AGENTFOX_ALLOW_EGRESS=1 and a key to change that.
  !    detector failure    fail-open: a detector that times out lets the request through and
                           records the gap
  !    answerability       no knowledge boundary declared — nothing stops an agent answering a
                           question it has no data for.
  ✓    findings            none open

! lines are warnings, ✗ lines are failures. Two are about AgentFox itself rather than your agents: development authentication, and a detector that fails open. agentfox doctor --json emits one record per check and exits non-zero on a failed check, for CI.

Upgrade

bash

pip install --upgrade agentfox
agentfox admin db upgrade
agentfox admin db current

Output

…
migrated b8d3f6a2c915 → b8d3f6a2c915
schema revision: b8d3f6a2c915

admin db upgrade applies any new migrations and is safe to run when there are none. Run it before you restart a server on new code. agentfox init also migrates. agentfox admin db downgrade exists and can drop columns and data; take a backup first.

Uninstall and clean up

bash

pip uninstall agentfox

Uninstalling removes the code and leaves your data: the database and evidence in the state directory, and each project's agentfox.toml. That is deliberate, because the audit chain is evidence. To remove them too:

bash

rm -rf ~/.agentfox        # or $AGENTFOX_STATE_DIR / $XDG_DATA_HOME/agentfox
rm agentfox.toml          # in each project where you ran agentfox init

Also remove the two lines of agentfox.auto() from your entry point, and any hooks written into .claude/settings.json by agentfox admin hooks install --write.

Troubleshooting

Symptom	Cause and fix
`ConfigFileError: AGENTFOX_CONFIG=… does not point at a readable file.`	The file you named explicitly does not exist. Fix the path, or set it to `none`.
`taint_scope … must be one of session, argument`	A typo in a validated setting stops startup on purpose, rather than falling back.
A setting in `agentfox.toml` has no effect	An environment variable overrides it, the key is misspelled (look for the warning), or the process started in another directory.
Postgres: `TypeError: cannot use a string pattern on a bytes-like object`	The database uses `SQL_ASCII`. Create it with UTF-8 encoding.
`agentfox init --path` to a directory that does not exist raises `FileNotFoundError`	Create the directory first.

Start

Install and configure

Install the package, add only the extras you need, decide where the database lives, and check the result with agentfox doctor.

When to use this

Install

AgentFox needs Python 3.11 or newer (requires-python = ">=3.11"). The core install is deliberately light: a web framework, SQLAlchemy, Alembic, Typer, and nothing that downloads model weights.

bash

python3 -m venv .venv && source .venv/bin/activate
pip install agentfox
agentfox --version

Output

agentfox 0.3.1

With uv, in a project:

bash

uv add agentfox

From source, for the latest commit:

bash

pip install "git+https://github.com/architsharm/agentfox.git"

The package installs one command, agentfox.

Extras

Extra	Installs	Enables
`pii`	presidio-analyzer, presidio-anonymizer	The pii.presidio detector. Also needs a spaCy model (below).
`classifiers`	transformers, torch	injection.classifier (PIGuard with a backstop model), injection.similarity (embedding match), safety.granite (Granite Guardian). Each needs its weights.
`sql`	sqlglot	SQL blast-radius and data-access analysis. Without it, SQL analysis fails closed rather than passing statements through.
`langgraph`	langgraph	The AgentFoxGuard node wrappers in agentfox.frameworks.langgraph.
`postgres`	psycopg[binary]	A Postgres database_url (postgresql+psycopg://…).
`otel`	opentelemetry-api, -sdk, -exporter-otlp-proto-http	OpenTelemetry trace export.
`rails`	nemoguardrails	The rails.nemo detector, once nemo_rails_config_path points at a NeMo Guardrails config.
`validators`	guardrails-ai	rails.guardrails_ai and the rails.hub.* detectors, once guardrails_ai_validators names installed Hub validators.
`redteam`	garak, pyrit	The wrapped Garak and PyRIT runners alongside the built-in probes (agentfox test probes lists them).
`bedrock`	boto3	The Amazon Bedrock model provider.
`vertex`	google-auth	The Google Vertex model provider.
`prometheus`	prometheus-client	Pushing metrics to a Prometheus push gateway. Scraping needs no extra.
`ragas`	ragas	Ragas scorers in evaluation suites.
`all`	pii, classifiers, rails, validators, redteam, otel, postgres, langgraph, sql	Every permissive extra. Excludes the cloud provider SDKs and restricted-classifiers.
`restricted-classifiers`	transformers, torch	safety.restricted (Llama Guard). Non-OSI licence: it also refuses to load unless AGENTFOX_ACCEPT_RESTRICTED_MODEL_LICENSES=1.
`dev`	pytest, pytest-asyncio, ruff, mypy	Working on AgentFox itself.

Detector weights

bash

python -m spacy download en_core_web_lg

Then check which detectors this process can actually run:

bash

agentfox doctor

Output

…
  ✓    detectors           5 running: injection.heuristic, pii.native, safety.lexicon,
                           schema.json, secrets.native
…

Where state lives

AgentFox keeps a database and a directory of evidence packages. Where they go depends on how it is installed:

Situation	Database	Evidence packages
`AGENTFOX_STATE_DIR` is set	`$AGENTFOX_STATE_DIR/agentfox.db`	`$AGENTFOX_STATE_DIR/var/evidence`
Installed package (pip, uv)	`~/.agentfox/agentfox.db`, or `$XDG_DATA_HOME/agentfox/agentfox.db` when that is set	`~/.agentfox/var/evidence`
Running from a source checkout	`agentfox.db` at the repository root	`var/evidence` at the repository root

Postgres

SQLite is fine for one process. For a server, or more than one worker, use Postgres with the postgres extra:

bash

pip install "agentfox[postgres]"
export AGENTFOX_DATABASE_URL="postgresql+psycopg://agentfox:PASSWORD@db.internal:5432/agentfox"
agentfox init

Output

Setting up AgentFox
  ✓ database ready  postgresql+psycopg://agentfox@127.0.0.1:55439/agentfox
  ✓ 43 controls across 7 frameworks  v0.1.0-draft (draft)
  ✓ 3 policy pack(s) loaded
…

That output is from a local Postgres 16 cluster; use your own host and credentials. Create the database with UTF-8 encoding.

agentfox init and agentfox.toml

bash

agentfox init

Output

Setting up AgentFox
  ✓ database ready
sqlite:////…/agentfox.db
  ✓ 43 controls across 7 frameworks  v0.1.0-draft (draft)
  ✓ 3 policy pack(s) loaded
      baseline                 observe  recorded, nothing blocked
      eu-ai-act-high-risk      observe  recorded, nothing blocked
      tool-containment         enforce  violations are blocked now
      coding-agent not enabled — no coding-agent hooks in this repo. `agentfox admin hooks install
--agent <slug> --write` turns it on for that agent.
      tool-containment blocks from the start — demote with `agentfox policy observe <key>`.
  ✓ wrote agentfox.toml
…

The generated file, exactly:

agentfox.toml

# AgentFox configuration.
# Everything here has a safe default; this file exists so the defaults are visible
# rather than implicit. The [agentfox] table is read from the working directory;
# environment variables (AGENTFOX_*) override it.

[agentfox]
environment = "development"

# Default mode for a policy that does not declare its own. Packs that declare a mode
# keep it (the shipped tool-containment pack declares enforce).
default_policy_mode = "observe"

# Zero egress: no model call leaves this machine unless you turn it on.
allow_egress = false

# The whole pre-flight pipeline's latency ceiling, in milliseconds.
enforcement_budget_ms = 300

# Where a tool call's provenance is read from, for the taint rules.
#   "session"  - the worst untrusted content anywhere in the run so far, or in the
#                call's own arguments. Contains more; escalates more benign calls.
#   "argument" - only what the call's own arguments were copied from.
# Every published number was measured under "session". docs/getting-started.md, step 5b.
taint_scope = "session"

How settings are read, highest precedence first:

AGENTFOX_* environment variables;
the [agentfox] table of $AGENTFOX_CONFIG if set (it must exist), otherwise of ./agentfox.toml in the working directory;
built-in defaults.

Check it: agentfox doctor

doctor grades the configuration, not the traffic. It changes nothing. On a fresh install:

bash

agentfox doctor

Output

Runtime check
  ✓    database            reachable — 0 agent(s), 0 trace(s)
  !    traffic             no decisions recorded — nothing has been governed yet. Add
                           `agentfox.auto()` to your entry point.
  !    authentication      the X-AgentFox-User header is accepted (environment=development,
                           auth_mode=auto) — anyone who can reach this port is any user they name.
                           Fine locally, unacceptable anywhere else.
  !    containment         no tools declared — nothing constrains what an agent may do when a
                           detector misses. Declare them with `agentfox declare tool <key>
                           --impact ...`.
  !    data scope          no table row-scoping declared — a query across every customer's rows
                           reads as ordinary. Declare with `agentfox declare scope <table>
                           --column ...`.
  ✓    detectors           5 running: injection.heuristic, pii.native, safety.lexicon,
                           schema.json, secrets.native
  ✓    providers           offline only (echo). No model call can leave this machine — set
                           AGENTFOX_ALLOW_EGRESS=1 and a key to change that.
  !    detector failure    fail-open: a detector that times out lets the request through and
                           records the gap
  !    answerability       no knowledge boundary declared — nothing stops an agent answering a
                           question it has no data for.
  ✓    findings            none open

Upgrade

bash

pip install --upgrade agentfox
agentfox admin db upgrade
agentfox admin db current

Output

…
migrated b8d3f6a2c915 → b8d3f6a2c915
schema revision: b8d3f6a2c915

Uninstall and clean up

bash

pip uninstall agentfox

bash

rm -rf ~/.agentfox        # or $AGENTFOX_STATE_DIR / $XDG_DATA_HOME/agentfox
rm agentfox.toml          # in each project where you ran agentfox init

Also remove the two lines of agentfox.auto() from your entry point, and any hooks written into .claude/settings.json by agentfox admin hooks install --write.

Troubleshooting

Symptom	Cause and fix
`ConfigFileError: AGENTFOX_CONFIG=… does not point at a readable file.`	The file you named explicitly does not exist. Fix the path, or set it to `none`.
`taint_scope … must be one of session, argument`	A typo in a validated setting stops startup on purpose, rather than falling back.
A setting in `agentfox.toml` has no effect	An environment variable overrides it, the key is misspelled (look for the warning), or the process started in another directory.
Postgres: `TypeError: cannot use a string pattern on a bytes-like object`	The database uses `SQL_ASCII`. Create it with UTF-8 encoding.
`agentfox init --path` to a directory that does not exist raises `FileNotFoundError`	Create the directory first.