Install options

Ways to install, the optional extras, detector weights, where state lives, and how to upgrade or remove AgentFox.

Install

AgentFox needs Python 3.11 or newer. The core install has no model weights and nothing that downloads them.

How	Command
pip, in a virtual environment	`pip install agentfox`
uv, in a project	`uv add agentfox`
As a tool, on the PATH everywhere (needed for Claude Code and Codex hooks)	`uv tool install agentfox` or `pipx install agentfox`
From source, latest commit	`pip install "git+https://github.com/architsharm/agentfox.git"`

The package installs one command, agentfox. agentfox --version prints the version.

Extras

Add extras in brackets: pip install "agentfox[pii,sql]". 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, on by default once it can run), 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.
`openai-agents`	openai-agents	The OpenAI Agents SDK adapter. Not in all, because it pulls in the openai client, which changes what auto() patches.
`postgres`	psycopg[binary]	A Postgres database_url (postgresql+psycopg://…).
`otel`	opentelemetry-api, -sdk, -exporter-otlp-proto-http	OpenTelemetry trace export, and decoding protobuf OTLP on ingest.
`rails`	nemoguardrails	The rails.nemo detector, once nemo_rails_config_path points at a NeMo Guardrails config.
`validators`	guardrails-ai	rails.guardrails_ai, to run your own Guard. The Guardrails AI validators themselves are built in and need no extra.
`redteam`	garak, pyrit	The wrapped Garak and PyRIT runners next to 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, openai-agents 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, pytest-xdist, ruff, mypy, import-linter	Working on AgentFox itself.

Enabled by default: injection.heuristic, injection.classifier, pii.native, secrets.native, safety.lexicon, schema.json, unicode.tags, custom.lists and code.insecure. All but injection.classifier need no extra; without the classifiers extra and its weights, the classifier is skipped and agentfox doctor says so. agentfox.auto() needs no extra: it patches whichever of openai, anthropic, litellm and langchain are installed.

Detector weights

No detector downloads anything while handling a request. A model-backed detector without its weights reports itself unavailable. Fetch weights once, on purpose:

bash

agentfox admin detectors pull injection.classifier
python -m spacy download en_core_web_lg   # for pii.presidio, about 400MB

The classifier detectors load from Hugging Face (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 inside. agentfox admin detectors list shows what can run here.

Where state lives

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`
Source checkout	`agentfox.db` at the repository root	`var/evidence` at the repository root

State is per installation, not per directory: agentfox findings shows the same findings from anywhere. Give each project its own AGENTFOX_STATE_DIR to keep them apart. AGENTFOX_DATABASE_URL and AGENTFOX_EVIDENCE_DIR override the two locations one at a time.

Postgres

SQLite is fine for one process. For a server or more than one worker, use Postgres with the postgres extra, and create the database with UTF-8 encoding:

bash

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

agentfox init and agentfox.toml

Without --key, agentfox init sets up a local install. It is offline and safe to run twice.

bash

agentfox init

Output

Setting up AgentFox
  ✓ database ready  sqlite:////…/agentfox.db
  ✓ 44 controls across 7 frameworks  v0.1.0-draft (draft)
  ✓ 4 policy pack(s) loaded
      agent-integrity          observe  recorded, nothing blocked
      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 the control catalog and the policy packs in the mode each declares, and writes agentfox.toml in the current directory (or --path, which must be an existing directory). A second run leaves an existing agentfox.toml alone. The fifth pack, coding-agent, applies only once a coding agent has hooks installed (Claude Code and Codex). --demo also loads three demo agents and an eval suite.

The generated file:

agentfox.toml

[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.
taint_scope = "session"

Settings are read in this order, first match wins:

AGENTFOX_* environment variables.
The [agentfox] table of $AGENTFOX_CONFIG if set (it must exist), otherwise of ./agentfox.toml.
Built-in defaults.

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

Check it: agentfox doctor

agentfox doctor grades the configuration, not the traffic, and changes nothing. ! lines are warnings and ✗ lines are failures. On a fresh install expect warnings for no traffic yet, development authentication, no declared tools, no row scoping, fail-open detectors and no knowledge boundary. agentfox doctor --json prints 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

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

Uninstall

pip uninstall agentfox removes the code and keeps your data: the database and evidence in the state directory, and each project's agentfox.toml. The audit chain is evidence, so removing it is a separate step:

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 agentfox.auto() from your entry point, and any hooks written into .claude/settings.json by agentfox admin hooks install --write.

Troubleshooting

You see	Do this
`ConfigFileError: AGENTFOX_CONFIG=… does not point at a readable file.`	Fix the path, or set it to `none`.
`taint_scope … must be one of session, argument`	Fix the typo. Validated settings stop startup rather than fall 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.

Install options

Ways to install, the optional extras, detector weights, where state lives, and how to upgrade or remove AgentFox.

Install

AgentFox needs Python 3.11 or newer. The core install has no model weights and nothing that downloads them.

How	Command
pip, in a virtual environment	`pip install agentfox`
uv, in a project	`uv add agentfox`
As a tool, on the PATH everywhere (needed for Claude Code and Codex hooks)	`uv tool install agentfox` or `pipx install agentfox`
From source, latest commit	`pip install "git+https://github.com/architsharm/agentfox.git"`

The package installs one command, agentfox. agentfox --version prints the version.

Extras

Add extras in brackets: pip install "agentfox[pii,sql]". 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, on by default once it can run), 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.
`openai-agents`	openai-agents	The OpenAI Agents SDK adapter. Not in all, because it pulls in the openai client, which changes what auto() patches.
`postgres`	psycopg[binary]	A Postgres database_url (postgresql+psycopg://…).
`otel`	opentelemetry-api, -sdk, -exporter-otlp-proto-http	OpenTelemetry trace export, and decoding protobuf OTLP on ingest.
`rails`	nemoguardrails	The rails.nemo detector, once nemo_rails_config_path points at a NeMo Guardrails config.
`validators`	guardrails-ai	rails.guardrails_ai, to run your own Guard. The Guardrails AI validators themselves are built in and need no extra.
`redteam`	garak, pyrit	The wrapped Garak and PyRIT runners next to 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, openai-agents 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, pytest-xdist, ruff, mypy, import-linter	Working on AgentFox itself.

Detector weights

No detector downloads anything while handling a request. A model-backed detector without its weights reports itself unavailable. Fetch weights once, on purpose:

bash

agentfox admin detectors pull injection.classifier
python -m spacy download en_core_web_lg   # for pii.presidio, about 400MB

Where state lives

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`
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, and create the database with UTF-8 encoding:

bash

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

agentfox init and agentfox.toml

Without --key, agentfox init sets up a local install. It is offline and safe to run twice.

bash

agentfox init

Output

Setting up AgentFox
  ✓ database ready  sqlite:////…/agentfox.db
  ✓ 44 controls across 7 frameworks  v0.1.0-draft (draft)
  ✓ 4 policy pack(s) loaded
      agent-integrity          observe  recorded, nothing blocked
      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:

agentfox.toml

[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.
taint_scope = "session"

Settings are read in this order, first match wins:

AGENTFOX_* environment variables.
The [agentfox] table of $AGENTFOX_CONFIG if set (it must exist), otherwise of ./agentfox.toml.
Built-in defaults.

Check it: agentfox doctor

Upgrade

bash

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

Uninstall

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 agentfox.auto() from your entry point, and any hooks written into .claude/settings.json by agentfox admin hooks install --write.

Troubleshooting

You see	Do this
`ConfigFileError: AGENTFOX_CONFIG=… does not point at a readable file.`	Fix the path, or set it to `none`.
`taint_scope … must be one of session, argument`	Fix the typo. Validated settings stop startup rather than fall 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.