Reference

Configuration

Every setting AgentFox reads: its environment variable, its agentfox.toml key, its default, and what it changes.

When to use this

Look a setting up here when Install and configure or a guide names one, and before you deploy (Self-hosting). The defaults are offline-first: no egress, the echo provider, five dependency-free detectors, and detector packs in observe.

How a setting is resolved

AGENTFOX_<KEY> in the environment.
The [agentfox] table of the file named by AGENTFOX_CONFIG, or of ./agentfox.toml in the working directory.
The default in the tables below.

The key in the file is the setting name: taint_scope = "argument" in the file is AGENTFOX_TAINT_SCOPE=argument in the environment. Lists are TOML arrays in the file and JSON in the environment. Unknown keys are ignored with a warning naming them. Values are validated, and some (taint_scope, webhook_min_severity) stop startup on a typo rather than falling back. Settings are read once per process.

bash

export AGENTFOX_FAIL_MODE=closed
export AGENTFOX_ENABLED_DETECTORS='["pii.native","secrets.native"]'
python -c "from agentfox.core.config import Settings as S; s = S(); print(s.fail_mode, s.enabled_detectors)"

Output

closed ['pii.native', 'secrets.native']

Database, state and deployment

Key and variable	Default	What it does
`database_url` `AGENTFOX_DATABASE_URL`	`sqlite:///<state dir>/agentfox.db`	Where everything is stored. SQLite by default; postgresql+psycopg://… with the postgres extra. A multi-worker server refuses SQLite at startup.
`sql_echo` `AGENTFOX_SQL_ECHO`	`false`	Log every SQL statement. For debugging only.
`evidence_dir` `AGENTFOX_EVIDENCE_DIR`	`<state dir>/var/evidence`	Where agentfox report evidence writes packages.
`org_id` `AGENTFOX_ORG_ID`	`org_default`	The organisation (tenant) records belong to when no token says otherwise.
`environment` `AGENTFOX_ENVIRONMENT`	`development`	development, staging, production, … Decides whether the development identity header is accepted when auth_mode is auto; anything not recognised as development counts as production.
`console_url` `AGENTFOX_CONSOLE_URL`	`""`	Your dashboard's address, used to turn a decision id in a refusal into a link. Never guessed; empty omits the link.
`compliance_dir` `AGENTFOX_COMPLIANCE_DIR`	`unset: the compliance packs`	A directory to read controls.yaml, obligations.yaml and threats.yaml from instead of the capability packs. Set only to load your own catalog.
`policies_dir` `AGENTFOX_POLICIES_DIR`	`unset: the built-in packs`	A directory to read the shipped policy files from instead of the built-in capability packs.
`pack_maturity` `AGENTFOX_PACK_MATURITY`	`stable`	Which capability packs load: stable, incubating (stable and incubating) or sandbox (all). See agentfox policy packs list --all.

Authentication and secrets

Key and variable	Default	What it does
`auth_mode` `AGENTFOX_AUTH_MODE`	`auto`	auto follows environment; development accepts the X-AgentFox-User header; token requires API tokens; oidc is reserved. Check with agentfox admin auth status.
`service_auth_secret` `AGENTFOX_SERVICE_AUTH_SECRET`	`dev-insecure-service-secret`	Shared between the gateway and the dashboard for the GitHub sign-in provisioning call, which mints owner tokens. Must be identical on both. Outside development the gateway refuses to start while it is the published default.
`token_encryption_key` `AGENTFOX_TOKEN_ENCRYPTION_KEY`	`unset`	Fernet key that encrypts every secret stored at rest: GitHub tokens, source credentials, alert URLs, probe auth headers, agent signing keys. Unset: those features fail closed.
`token_encryption_key_previous` `AGENTFOX_TOKEN_ENCRYPTION_KEY_PREVIOUS`	`unset`	Retired encryption keys, comma-separated. They still decrypt and never encrypt; agentfox admin keys rotate moves everything to the current key, then remove them.
`cron_secret` `AGENTFOX_CRON_SECRET`	`unset`	Bearer secret for /api/internal/jobs/run. Unset: the route refuses every call. CRON_SECRET is also read.
`playground_cors_origin` `AGENTFOX_PLAYGROUND_CORS_ORIGIN`	`unset`	Comma-separated browser origins allowed to call the public playground, added to localhost.

Policy and enforcement

Key and variable	Default	What it does
`default_policy_mode` `AGENTFOX_DEFAULT_POLICY_MODE`	`observe`	The mode of a policy that does not declare one. Packs that declare a mode keep it: tool-containment declares enforce.
`fail_mode` `AGENTFOX_FAIL_MODE`	`open`	What happens when a detector errors or exceeds its budget: open lets the request through and records the gap; closed refuses.
`taint_scope` `AGENTFOX_TAINT_SCOPE`	`session`	session: a call's provenance is the worst untrusted content in the run so far. argument: only what its own arguments were copied from. Any other value is an error. See Concepts.
`enforcement_budget_ms` `AGENTFOX_ENFORCEMENT_BUDGET_MS`	`300`	Latency ceiling for the whole pre-flight pipeline on one surface.
`detector_timeout_ms` `AGENTFOX_DETECTOR_TIMEOUT_MS`	`40`	Default per-detector budget.
`request_budget_ms` `AGENTFOX_REQUEST_BUDGET_MS`	`350`	Ceiling across every surface one governed call touches. Kept above enforcement_budget_ms.
`policy_engine` `AGENTFOX_POLICY_ENGINE`	`native`	native, or opa to evaluate through an Open Policy Agent sidecar (falls back to native if it is unreachable).
`opa_url` `AGENTFOX_OPA_URL`	`http://localhost:8181`	The OPA sidecar, when policy_engine is opa.
`streaming_mode` `AGENTFOX_STREAMING_MODE`	`buffered`	buffered enforces streamed output exactly like non-streamed, at the cost of first-token latency; windowed forwards as it goes and cannot recall what it already sent.
`stream_window_chars` `AGENTFOX_STREAM_WINDOW_CHARS`	`200`	Window size for windowed streaming.

Detectors

Key and variable	Default	What it does
`enabled_detectors` `AGENTFOX_ENABLED_DETECTORS`	`["injection.heuristic", "pii.native", "secrets.native", "safety.lexicon", "schema.json"]`	Which detectors run. A listed detector whose extra or weights are missing is unavailable and does not run.
`accept_restricted_model_licenses` `AGENTFOX_ACCEPT_RESTRICTED_MODEL_LICENSES`	`false`	Required (1/true) before safety.restricted (Llama Guard, non-OSI licence) will load.
`prompt_injection_classifier_model` `AGENTFOX_PROMPT_INJECTION_CLASSIFIER_MODEL`	`leolee99/PIGuard`	Primary model for injection.classifier.
`prompt_injection_classifier_secondary_model` `AGENTFOX_PROMPT_INJECTION_CLASSIFIER_SECONDARY_MODEL`	`protectai/deberta-v3-base-prompt-injection-v2`	Backstop model consulted only when the primary finds nothing. Empty disables it.
`prompt_injection_classifier_secondary_threshold` `AGENTFOX_PROMPT_INJECTION_CLASSIFIER_SECONDARY_THRESHOLD`	`0.92`	The backstop's score bar.
`embedding_similarity_model` `AGENTFOX_EMBEDDING_SIMILARITY_MODEL`	`sentence-transformers/all-MiniLM-L6-v2`	Embedding model for injection.similarity.
`embedding_similarity_attack_threshold` `AGENTFOX_EMBEDDING_SIMILARITY_ATTACK_THRESHOLD`	`0.6`	Cosine similarity to the nearest known attack before injection.similarity fires.
`embedding_similarity_benign_margin` `AGENTFOX_EMBEDDING_SIMILARITY_BENIGN_MARGIN`	`0.05`	How far above the nearest benign example that similarity must be.
`granite_guardian_model` `AGENTFOX_GRANITE_GUARDIAN_MODEL`	`ibm-granite/granite-guardian-3.0-2b`	Model for safety.granite.
`nemo_rails_config_path` `AGENTFOX_NEMO_RAILS_CONFIG_PATH`	`unset`	A NeMo Guardrails config directory. rails.nemo is unavailable until this is set (rails extra).
`guardrails_ai_validators` `AGENTFOX_GUARDRAILS_AI_VALIDATORS`	`[]`	Guardrails AI Hub validator slugs for rails.guardrails_ai (validators extra). Each must be installed separately.

Judgment tiers and egress

Key and variable	Default	What it does
`allow_egress` `AGENTFOX_ALLOW_EGRESS`	`false`	Master switch for anything leaving the machine: hosted model providers, hosted judgment tiers, webhooks, write-back to LangSmith or Langfuse. Off by default.
`judgment_backend` `AGENTFOX_JUDGMENT_BACKEND`	`local`	local keeps every judgment in-process; remote and auto may call a hosted judgment model, only with allow_egress on.
`judgment_tiers` `AGENTFOX_JUDGMENT_TIERS`	`["deterministic"]`	Evaluators that may be consulted: deterministic (always on), local_model, local_llm, jev, llm. Each tier is forbidden from the decisions it measured worse on.
`judgment_redact_before_egress` `AGENTFOX_JUDGMENT_REDACT_BEFORE_EGRESS`	`true`	Redact locally detected personal data before a judgment leaves.
`judgment_fail_closed` `AGENTFOX_JUDGMENT_FAIL_CLOSED`	`true`	Refuse to send a judgment if the local redactor cannot load.
`judgment_pii_egress` `AGENTFOX_JUDGMENT_PII_EGRESS`	`redact`	block, redact or allow: what to do when a payload bound for a hosted tier contains personal data. Only block guarantees none leaves.
`judgment_llm_provider` `AGENTFOX_JUDGMENT_LLM_PROVIDER`	`""`	Provider for the llm and local_llm tiers. Empty uses default_provider.
`judgment_llm_model` `AGENTFOX_JUDGMENT_LLM_MODEL`	`""`	Model for those tiers. Empty uses the provider's default.

Model providers

Key and variable	Default	What it does
`default_provider` `AGENTFOX_DEFAULT_PROVIDER`	`echo`	echo is the offline provider: deterministic, no key, no network. Others: openai, anthropic, azure, bedrock, vertex, litellm.
`openai_api_key` `AGENTFOX_OPENAI_API_KEY`	`unset`	Key for the openai provider (gateway proxy and judgment tiers).
`openai_base_url` `AGENTFOX_OPENAI_BASE_URL`	`https://api.openai.com`	OpenAI-compatible endpoint.
`anthropic_api_key` `AGENTFOX_ANTHROPIC_API_KEY`	`unset`	Key for the anthropic provider.
`anthropic_base_url` `AGENTFOX_ANTHROPIC_BASE_URL`	`https://api.anthropic.com`	Anthropic endpoint.
`azure_openai_endpoint` `AGENTFOX_AZURE_OPENAI_ENDPOINT`	`unset`	Azure OpenAI resource endpoint.
`azure_openai_api_key` `AGENTFOX_AZURE_OPENAI_API_KEY`	`unset`	Azure OpenAI key.
`azure_openai_api_version` `AGENTFOX_AZURE_OPENAI_API_VERSION`	`2024-10-21`	Azure OpenAI API version.
`azure_openai_deployment` `AGENTFOX_AZURE_OPENAI_DEPLOYMENT`	`unset`	Azure OpenAI deployment name.
`aws_region` `AGENTFOX_AWS_REGION`	`unset`	Region for Bedrock (bedrock extra).
`bedrock_model` `AGENTFOX_BEDROCK_MODEL`	`anthropic.claude-sonnet-4-20250514-v1:0`	Bedrock model id.
`vertex_project` `AGENTFOX_VERTEX_PROJECT`	`unset`	Google Cloud project for Vertex (vertex extra).
`vertex_location` `AGENTFOX_VERTEX_LOCATION`	`us-central1`	Vertex region.
`vertex_model` `AGENTFOX_VERTEX_MODEL`	`gemini-2.0-flash`	Vertex model.
`litellm_base_url` `AGENTFOX_LITELLM_BASE_URL`	`unset`	A LiteLLM proxy to route through. On loopback it counts as local and does not egress.
`litellm_api_key` `AGENTFOX_LITELLM_API_KEY`	`unset`	Key for that proxy.

Budgets, loops and reliability

Key and variable	Default	What it does
`loop_max_steps` `AGENTFOX_LOOP_MAX_STEPS`	`25`	Most steps one run may take before loop.runaway blocks it.
`loop_max_repeats` `AGENTFOX_LOOP_MAX_REPEATS`	`2`	Identical re-issued calls tolerated.
`loop_max_cycle_length` `AGENTFOX_LOOP_MAX_CYCLE_LENGTH`	`4`	Longest alternating cycle detected.
`loop_max_steps_without_progress` `AGENTFOX_LOOP_MAX_STEPS_WITHOUT_PROGRESS`	`5`	Steps that produce no new observation before the run counts as stuck.
`fallback_chain` `AGENTFOX_FALLBACK_CHAIN`	`[]`	Model degradation ladder, preferred first. Empty means fail rather than serve from a model the agent was not evaluated on.
`breaker_failure_threshold` `AGENTFOX_BREAKER_FAILURE_THRESHOLD`	`5`	Provider failures before the circuit breaker opens.
`breaker_recovery_seconds` `AGENTFOX_BREAKER_RECOVERY_SECONDS`	`30.0`	How long it stays open.
`admission_rate_per_second` `AGENTFOX_ADMISSION_RATE_PER_SECOND`	`200.0`	Admission control on /v1/*: sustained rate.
`admission_burst` `AGENTFOX_ADMISSION_BURST`	`400`	Burst allowance.
`admission_max_concurrent` `AGENTFOX_ADMISSION_MAX_CONCURRENT`	`256`	Concurrent requests admitted.
`admission_shed_below_priority` `AGENTFOX_ADMISSION_SHED_BELOW_PRIORITY`	`normal`	Under saturation, work below this priority is shed first.
`service_probe_interval_seconds` `AGENTFOX_SERVICE_PROBE_INTERVAL_SECONDS`	`5.0`	How long a dependency health probe is reused. Status endpoints always probe fresh.
`verified_state_max_age_seconds` `AGENTFOX_VERIFIED_STATE_MAX_AGE_SECONDS`	`300`	How fresh a state read must be to authorise an irreversible act.
`data_access_strictness` `AGENTFOX_DATA_ACCESS_STRICTNESS`	`standard`	standard escalates a query on an undeclared table; strict blocks it.
`sql_dialect` `AGENTFOX_SQL_DIALECT`	`postgres`	Dialect SQL artefacts are parsed in (sql extra). A wrong parse fails closed.
`memory_unverified_ttl_seconds` `AGENTFOX_MEMORY_UNVERIFIED_TTL_SECONDS`	`86400`	How long an unverified memory entry survives before it decays.
`agent_message_validity_seconds` `AGENTFOX_AGENT_MESSAGE_VALIDITY_SECONDS`	`300`	Oldest an inter-agent message signature may be and still verify.

Entitlement

Key and variable	Default	What it does
`entitlement_engine` `AGENTFOX_ENTITLEMENT_ENGINE`	`native`	native, or openfga. The OpenFGA adapter is a declared seam, not an implementation yet.
`openfga_url` `AGENTFOX_OPENFGA_URL`	`unset`	OpenFGA endpoint.
`openfga_store_id` `AGENTFOX_OPENFGA_STORE_ID`	`unset`	OpenFGA store.
`k_anonymity_threshold` `AGENTFOX_K_ANONYMITY_THRESHOLD`	`5`	Smallest group an aggregate answer may describe.

Audit and evidence

Key and variable	Default	What it does
`audit_signing_key` `AGENTFOX_AUDIT_SIGNING_KEY`	`dev-insecure-checkpoint-key`	Signs audit-chain checkpoints. Keep it outside the database. Outside development the gateway refuses to start while it is the published default.
`audit_signing_key_previous` `AGENTFOX_AUDIT_SIGNING_KEY_PREVIOUS`	`unset`	Retired signing keys, comma-separated. Checkpoints they signed still verify; agentfox admin keys rotate verifies the chain and re-signs them with the current key, then remove them.
`audit_checkpoint_interval` `AGENTFOX_AUDIT_CHECKPOINT_INTERVAL`	`100`	Chain entries between signed checkpoints.
`redact_at_capture` `AGENTFOX_REDACT_AT_CAPTURE`	`true`	Redact detected sensitive values before they are written to the audit log.

Improvement loop and scheduler

Key and variable	Default	What it does
`improvement_frozen` `AGENTFOX_IMPROVEMENT_FROZEN`	`false`	Kill switch for the improvement loop: nothing is applied automatically; proposals are still filed.
`improvement_actor_id` `AGENTFOX_IMPROVEMENT_ACTOR_ID`	`agentfox-improver`	The identity automated changes are recorded under.
`improvement_max_auto_changes_per_day` `AGENTFOX_IMPROVEMENT_MAX_AUTO_CHANGES_PER_DAY`	`20`	Cap on automated applies per tenant per day.
`improvement_rollback_budget` `AGENTFOX_IMPROVEMENT_ROLLBACK_BUDGET`	`0.05`	A change class rolled back more often than this drops an autonomy level.
`canary_min_dwell_seconds` `AGENTFOX_CANARY_MIN_DWELL_SECONDS`	`3600`	Minimum time a canaried change runs before it can be settled.
`canary_max_block_rate_drop` `AGENTFOX_CANARY_MAX_BLOCK_RATE_DROP`	`0.15`	How much less the candidate may block before the canary rolls it back.
`scheduler_enabled` `AGENTFOX_SCHEDULER_ENABLED`	`true`	Whether scheduled jobs are queued.
`monitor_batch_limit` `AGENTFOX_MONITOR_BATCH_LIMIT`	`5`	Most due monitors one monitors.run job runs; the rest wait for the next runner call.
`monitor_failure_threshold` `AGENTFOX_MONITOR_FAILURE_THRESHOLD`	`3`	Failed runs in a row before a monitor raises a monitor_failing finding.
`job_stuck_after_seconds` `AGENTFOX_JOB_STUCK_AFTER_SECONDS`	`900`	A running job older than this counts as crashed and is recovered.
`job_backoff_base_seconds` `AGENTFOX_JOB_BACKOFF_BASE_SECONDS`	`60`	Base of the exponential retry delay.
`live_probes_enabled` `AGENTFOX_LIVE_PROBES_ENABLED`	`true`	Kill switch for scheduled probes against deployed agents. Each target also needs its own recorded opt-in.
`showcase_enabled` `AGENTFOX_SHOWCASE_ENABLED`	`false`	Probe the demo support agent in its own tenant every hour and publish the counts at GET /api/public/showcase.
`showcase_org_id` `AGENTFOX_SHOWCASE_ORG_ID`	`org_showcase`	The tenant the showcase lives in. The public endpoint reads nothing else.

Evaluation

Key and variable	Default	What it does
`eval_runner` `AGENTFOX_EVAL_RUNNER`	`native`	native, or promptfoo.
`promptfoo_bin` `AGENTFOX_PROMPTFOO_BIN`	`promptfoo`	The promptfoo executable.
`online_eval_sample_rate` `AGENTFOX_ONLINE_EVAL_SAMPLE_RATE`	`0.25`	Share of production traffic agentfox test online samples.
`drift_psi_threshold` `AGENTFOX_DRIFT_PSI_THRESHOLD`	`0.2`	Population stability index above which agentfox report drift reports drift.

Integrations: webhooks and trace correlation

Key and variable	Default	What it does
`webhook_url` `AGENTFOX_WEBHOOK_URL`	`unset`	Each new finding at or above webhook_min_severity is POSTed here. Needs allow_egress.
`webhook_secret` `AGENTFOX_WEBHOOK_SECRET`	`unset`	Adds X-AgentFox-Signature: sha256=<HMAC of the body>.
`webhook_timeout_seconds` `AGENTFOX_WEBHOOK_TIMEOUT_SECONDS`	`3.0`	Per-delivery timeout; one retry on 5xx or timeout.
`webhook_min_severity` `AGENTFOX_WEBHOOK_MIN_SEVERITY`	`high`	critical, high, medium or low.
`slack_webhook_url` `AGENTFOX_SLACK_WEBHOOK_URL`	`unset`	Slack incoming webhook for monitor findings opened, reopened or closed. Needs allow_egress. A tenant can also set its own (PUT /api/alerts/slack).
`slack_min_severity` `AGENTFOX_SLACK_MIN_SEVERITY`	`medium`	critical, high, medium or low.
`github_webhook_secret` `AGENTFOX_GITHUB_WEBHOOK_SECRET`	`unset`	Verifies X-Hub-Signature-256 on /api/integrations/github/webhook. A connection may carry its own instead; with neither, push deliveries are refused.
`correlation_push` `AGENTFOX_CORRELATION_PUSH`	`false`	Write the verdict back onto the LangSmith or Langfuse run. Correlation itself needs no setting.
`correlation_timeout_seconds` `AGENTFOX_CORRELATION_TIMEOUT_SECONDS`	`2.0`	Timeout for that write-back.
`langsmith_api_key` `AGENTFOX_LANGSMITH_API_KEY`	`unset`	LangSmith key for write-back.
`langsmith_project` `AGENTFOX_LANGSMITH_PROJECT`	`unset`	LangSmith project.
`langsmith_api_url` `AGENTFOX_LANGSMITH_API_URL`	`https://api.smith.langchain.com`	LangSmith API.
`langsmith_ui_url` `AGENTFOX_LANGSMITH_UI_URL`	`https://smith.langchain.com`	LangSmith UI, for links.
`langfuse_public_key` `AGENTFOX_LANGFUSE_PUBLIC_KEY`	`unset`	Langfuse public key.
`langfuse_secret_key` `AGENTFOX_LANGFUSE_SECRET_KEY`	`unset`	Langfuse secret key.
`langfuse_project` `AGENTFOX_LANGFUSE_PROJECT`	`unset`	Langfuse project.
`langfuse_host` `AGENTFOX_LANGFUSE_HOST`	`https://cloud.langfuse.com`	Langfuse host.

Read outside Settings

A few variables are read straight from the environment, because they decide where settings come from or are used by a separate program. None of them can go in agentfox.toml.

Variable	What it does
`AGENTFOX_STATE_DIR`	Directory for the default database and evidence. It decides the defaults of database_url and evidence_dir, so it is not itself a setting.
`AGENTFOX_CONFIG`	Path to the TOML file to read. It must exist. none, off or - turns file loading off.
`AGENTFOX_AGENT`	Agent slug for agentfox.auto() when none is passed. Then OTEL_SERVICE_NAME, SERVICE_NAME, APP_NAME, K_SERVICE, the script name, and finally default-agent.
`AGENTFOX_API_URL, AGENTFOX_API_TOKEN, AGENTFOX_USER`	Where agentfox scan --submit sends a redacted summary, and the credential it uses.
`AGENTFOX_AUDIT_KEY`	Then AGENTFOX_AUDIT_SIGNING_KEY. Read by the verify_chain.py inside an evidence package to check checkpoint signatures.
`AGENTFOX_MCP_LOG_LEVEL`	Log level of agentfox serve mcp. Default WARNING.
`CRON_SECRET`	Accepted in addition to cron_secret by /api/internal/jobs/run (Vercel Cron sets it).
`JEV_API_KEY`	Key for the hosted jev judgment tier. Without it that tier is unavailable.

Dashboard

The web app is a separate Next.js process with its own variables. Each AGENTFOX_ name below falls back to its AGENTFOX_ spelling (for example AGENTFOX_API_URL) when unset. They are read at request time, so one image can point at any gateway.

Variable	Default	What it does
`AGENTFOX_API_URL`	http://127.0.0.1:8080	The gateway the dashboard calls, server to server. Include the scheme.
`AGENTFOX_API_TOKEN`	unset	A static operator token for the dashboard's own calls. A signed-in user's token takes precedence.
`AGENTFOX_USER`	admin@example.com	The development identity header value, used when there is no token. A gateway outside development refuses it.
`AGENTFOX_PLAYGROUND_API_URL`	AGENTFOX_API_URL	The gateway address the visitor's browser uses on the public playground page.
`AGENTFOX_SERVICE_AUTH_SECRET`	unset	Must equal the gateway's service_auth_secret, or GitHub sign-in fails at provisioning.
`AGENTFOX_SITE_URL`	the public site	Canonical URL used in page metadata.
`AGENTFOX_SELF_HOSTED`	unset	Marks a self-hosted dashboard in the interface.
`GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET`	unset	The GitHub OAuth app for sign-in. Unset: sign-in is unavailable.

What can go wrong

A hosted provider or webhook does nothing. allow_egress is false. A configured key or URL with egress off sends nothing.
A detector you enabled never fires. Its extra or weights are missing, so it is unavailable and skipped. agentfox doctor lists the available ones.
The development header is refused. environment is not a development name, so auth_mode = auto requires tokens. agentfox admin auth status says which.
GitHub sign-in fails at provisioning. service_auth_secret differs between the gateway and the dashboard.

Reference

Configuration

Every setting AgentFox reads: its environment variable, its agentfox.toml key, its default, and what it changes.

When to use this

How a setting is resolved

AGENTFOX_<KEY> in the environment.
The [agentfox] table of the file named by AGENTFOX_CONFIG, or of ./agentfox.toml in the working directory.
The default in the tables below.

bash

export AGENTFOX_FAIL_MODE=closed
export AGENTFOX_ENABLED_DETECTORS='["pii.native","secrets.native"]'
python -c "from agentfox.core.config import Settings as S; s = S(); print(s.fail_mode, s.enabled_detectors)"

Output

closed ['pii.native', 'secrets.native']

Database, state and deployment

Key and variable	Default	What it does
`database_url` `AGENTFOX_DATABASE_URL`	`sqlite:///<state dir>/agentfox.db`	Where everything is stored. SQLite by default; postgresql+psycopg://… with the postgres extra. A multi-worker server refuses SQLite at startup.
`sql_echo` `AGENTFOX_SQL_ECHO`	`false`	Log every SQL statement. For debugging only.
`evidence_dir` `AGENTFOX_EVIDENCE_DIR`	`<state dir>/var/evidence`	Where agentfox report evidence writes packages.
`org_id` `AGENTFOX_ORG_ID`	`org_default`	The organisation (tenant) records belong to when no token says otherwise.
`environment` `AGENTFOX_ENVIRONMENT`	`development`	development, staging, production, … Decides whether the development identity header is accepted when auth_mode is auto; anything not recognised as development counts as production.
`console_url` `AGENTFOX_CONSOLE_URL`	`""`	Your dashboard's address, used to turn a decision id in a refusal into a link. Never guessed; empty omits the link.
`compliance_dir` `AGENTFOX_COMPLIANCE_DIR`	`unset: the compliance packs`	A directory to read controls.yaml, obligations.yaml and threats.yaml from instead of the capability packs. Set only to load your own catalog.
`policies_dir` `AGENTFOX_POLICIES_DIR`	`unset: the built-in packs`	A directory to read the shipped policy files from instead of the built-in capability packs.
`pack_maturity` `AGENTFOX_PACK_MATURITY`	`stable`	Which capability packs load: stable, incubating (stable and incubating) or sandbox (all). See agentfox policy packs list --all.

Authentication and secrets

Key and variable	Default	What it does
`auth_mode` `AGENTFOX_AUTH_MODE`	`auto`	auto follows environment; development accepts the X-AgentFox-User header; token requires API tokens; oidc is reserved. Check with agentfox admin auth status.
`service_auth_secret` `AGENTFOX_SERVICE_AUTH_SECRET`	`dev-insecure-service-secret`	Shared between the gateway and the dashboard for the GitHub sign-in provisioning call, which mints owner tokens. Must be identical on both. Outside development the gateway refuses to start while it is the published default.
`token_encryption_key` `AGENTFOX_TOKEN_ENCRYPTION_KEY`	`unset`	Fernet key that encrypts every secret stored at rest: GitHub tokens, source credentials, alert URLs, probe auth headers, agent signing keys. Unset: those features fail closed.
`token_encryption_key_previous` `AGENTFOX_TOKEN_ENCRYPTION_KEY_PREVIOUS`	`unset`	Retired encryption keys, comma-separated. They still decrypt and never encrypt; agentfox admin keys rotate moves everything to the current key, then remove them.
`cron_secret` `AGENTFOX_CRON_SECRET`	`unset`	Bearer secret for /api/internal/jobs/run. Unset: the route refuses every call. CRON_SECRET is also read.
`playground_cors_origin` `AGENTFOX_PLAYGROUND_CORS_ORIGIN`	`unset`	Comma-separated browser origins allowed to call the public playground, added to localhost.

Policy and enforcement

Key and variable	Default	What it does
`default_policy_mode` `AGENTFOX_DEFAULT_POLICY_MODE`	`observe`	The mode of a policy that does not declare one. Packs that declare a mode keep it: tool-containment declares enforce.
`fail_mode` `AGENTFOX_FAIL_MODE`	`open`	What happens when a detector errors or exceeds its budget: open lets the request through and records the gap; closed refuses.
`taint_scope` `AGENTFOX_TAINT_SCOPE`	`session`	session: a call's provenance is the worst untrusted content in the run so far. argument: only what its own arguments were copied from. Any other value is an error. See Concepts.
`enforcement_budget_ms` `AGENTFOX_ENFORCEMENT_BUDGET_MS`	`300`	Latency ceiling for the whole pre-flight pipeline on one surface.
`detector_timeout_ms` `AGENTFOX_DETECTOR_TIMEOUT_MS`	`40`	Default per-detector budget.
`request_budget_ms` `AGENTFOX_REQUEST_BUDGET_MS`	`350`	Ceiling across every surface one governed call touches. Kept above enforcement_budget_ms.
`policy_engine` `AGENTFOX_POLICY_ENGINE`	`native`	native, or opa to evaluate through an Open Policy Agent sidecar (falls back to native if it is unreachable).
`opa_url` `AGENTFOX_OPA_URL`	`http://localhost:8181`	The OPA sidecar, when policy_engine is opa.
`streaming_mode` `AGENTFOX_STREAMING_MODE`	`buffered`	buffered enforces streamed output exactly like non-streamed, at the cost of first-token latency; windowed forwards as it goes and cannot recall what it already sent.
`stream_window_chars` `AGENTFOX_STREAM_WINDOW_CHARS`	`200`	Window size for windowed streaming.

Detectors

Key and variable	Default	What it does
`enabled_detectors` `AGENTFOX_ENABLED_DETECTORS`	`["injection.heuristic", "pii.native", "secrets.native", "safety.lexicon", "schema.json"]`	Which detectors run. A listed detector whose extra or weights are missing is unavailable and does not run.
`accept_restricted_model_licenses` `AGENTFOX_ACCEPT_RESTRICTED_MODEL_LICENSES`	`false`	Required (1/true) before safety.restricted (Llama Guard, non-OSI licence) will load.
`prompt_injection_classifier_model` `AGENTFOX_PROMPT_INJECTION_CLASSIFIER_MODEL`	`leolee99/PIGuard`	Primary model for injection.classifier.
`prompt_injection_classifier_secondary_model` `AGENTFOX_PROMPT_INJECTION_CLASSIFIER_SECONDARY_MODEL`	`protectai/deberta-v3-base-prompt-injection-v2`	Backstop model consulted only when the primary finds nothing. Empty disables it.
`prompt_injection_classifier_secondary_threshold` `AGENTFOX_PROMPT_INJECTION_CLASSIFIER_SECONDARY_THRESHOLD`	`0.92`	The backstop's score bar.
`embedding_similarity_model` `AGENTFOX_EMBEDDING_SIMILARITY_MODEL`	`sentence-transformers/all-MiniLM-L6-v2`	Embedding model for injection.similarity.
`embedding_similarity_attack_threshold` `AGENTFOX_EMBEDDING_SIMILARITY_ATTACK_THRESHOLD`	`0.6`	Cosine similarity to the nearest known attack before injection.similarity fires.
`embedding_similarity_benign_margin` `AGENTFOX_EMBEDDING_SIMILARITY_BENIGN_MARGIN`	`0.05`	How far above the nearest benign example that similarity must be.
`granite_guardian_model` `AGENTFOX_GRANITE_GUARDIAN_MODEL`	`ibm-granite/granite-guardian-3.0-2b`	Model for safety.granite.
`nemo_rails_config_path` `AGENTFOX_NEMO_RAILS_CONFIG_PATH`	`unset`	A NeMo Guardrails config directory. rails.nemo is unavailable until this is set (rails extra).
`guardrails_ai_validators` `AGENTFOX_GUARDRAILS_AI_VALIDATORS`	`[]`	Guardrails AI Hub validator slugs for rails.guardrails_ai (validators extra). Each must be installed separately.

Judgment tiers and egress

Key and variable	Default	What it does
`allow_egress` `AGENTFOX_ALLOW_EGRESS`	`false`	Master switch for anything leaving the machine: hosted model providers, hosted judgment tiers, webhooks, write-back to LangSmith or Langfuse. Off by default.
`judgment_backend` `AGENTFOX_JUDGMENT_BACKEND`	`local`	local keeps every judgment in-process; remote and auto may call a hosted judgment model, only with allow_egress on.
`judgment_tiers` `AGENTFOX_JUDGMENT_TIERS`	`["deterministic"]`	Evaluators that may be consulted: deterministic (always on), local_model, local_llm, jev, llm. Each tier is forbidden from the decisions it measured worse on.
`judgment_redact_before_egress` `AGENTFOX_JUDGMENT_REDACT_BEFORE_EGRESS`	`true`	Redact locally detected personal data before a judgment leaves.
`judgment_fail_closed` `AGENTFOX_JUDGMENT_FAIL_CLOSED`	`true`	Refuse to send a judgment if the local redactor cannot load.
`judgment_pii_egress` `AGENTFOX_JUDGMENT_PII_EGRESS`	`redact`	block, redact or allow: what to do when a payload bound for a hosted tier contains personal data. Only block guarantees none leaves.
`judgment_llm_provider` `AGENTFOX_JUDGMENT_LLM_PROVIDER`	`""`	Provider for the llm and local_llm tiers. Empty uses default_provider.
`judgment_llm_model` `AGENTFOX_JUDGMENT_LLM_MODEL`	`""`	Model for those tiers. Empty uses the provider's default.

Model providers

Key and variable	Default	What it does
`default_provider` `AGENTFOX_DEFAULT_PROVIDER`	`echo`	echo is the offline provider: deterministic, no key, no network. Others: openai, anthropic, azure, bedrock, vertex, litellm.
`openai_api_key` `AGENTFOX_OPENAI_API_KEY`	`unset`	Key for the openai provider (gateway proxy and judgment tiers).
`openai_base_url` `AGENTFOX_OPENAI_BASE_URL`	`https://api.openai.com`	OpenAI-compatible endpoint.
`anthropic_api_key` `AGENTFOX_ANTHROPIC_API_KEY`	`unset`	Key for the anthropic provider.
`anthropic_base_url` `AGENTFOX_ANTHROPIC_BASE_URL`	`https://api.anthropic.com`	Anthropic endpoint.
`azure_openai_endpoint` `AGENTFOX_AZURE_OPENAI_ENDPOINT`	`unset`	Azure OpenAI resource endpoint.
`azure_openai_api_key` `AGENTFOX_AZURE_OPENAI_API_KEY`	`unset`	Azure OpenAI key.
`azure_openai_api_version` `AGENTFOX_AZURE_OPENAI_API_VERSION`	`2024-10-21`	Azure OpenAI API version.
`azure_openai_deployment` `AGENTFOX_AZURE_OPENAI_DEPLOYMENT`	`unset`	Azure OpenAI deployment name.
`aws_region` `AGENTFOX_AWS_REGION`	`unset`	Region for Bedrock (bedrock extra).
`bedrock_model` `AGENTFOX_BEDROCK_MODEL`	`anthropic.claude-sonnet-4-20250514-v1:0`	Bedrock model id.
`vertex_project` `AGENTFOX_VERTEX_PROJECT`	`unset`	Google Cloud project for Vertex (vertex extra).
`vertex_location` `AGENTFOX_VERTEX_LOCATION`	`us-central1`	Vertex region.
`vertex_model` `AGENTFOX_VERTEX_MODEL`	`gemini-2.0-flash`	Vertex model.
`litellm_base_url` `AGENTFOX_LITELLM_BASE_URL`	`unset`	A LiteLLM proxy to route through. On loopback it counts as local and does not egress.
`litellm_api_key` `AGENTFOX_LITELLM_API_KEY`	`unset`	Key for that proxy.

Budgets, loops and reliability

Key and variable	Default	What it does
`loop_max_steps` `AGENTFOX_LOOP_MAX_STEPS`	`25`	Most steps one run may take before loop.runaway blocks it.
`loop_max_repeats` `AGENTFOX_LOOP_MAX_REPEATS`	`2`	Identical re-issued calls tolerated.
`loop_max_cycle_length` `AGENTFOX_LOOP_MAX_CYCLE_LENGTH`	`4`	Longest alternating cycle detected.
`loop_max_steps_without_progress` `AGENTFOX_LOOP_MAX_STEPS_WITHOUT_PROGRESS`	`5`	Steps that produce no new observation before the run counts as stuck.
`fallback_chain` `AGENTFOX_FALLBACK_CHAIN`	`[]`	Model degradation ladder, preferred first. Empty means fail rather than serve from a model the agent was not evaluated on.
`breaker_failure_threshold` `AGENTFOX_BREAKER_FAILURE_THRESHOLD`	`5`	Provider failures before the circuit breaker opens.
`breaker_recovery_seconds` `AGENTFOX_BREAKER_RECOVERY_SECONDS`	`30.0`	How long it stays open.
`admission_rate_per_second` `AGENTFOX_ADMISSION_RATE_PER_SECOND`	`200.0`	Admission control on /v1/*: sustained rate.
`admission_burst` `AGENTFOX_ADMISSION_BURST`	`400`	Burst allowance.
`admission_max_concurrent` `AGENTFOX_ADMISSION_MAX_CONCURRENT`	`256`	Concurrent requests admitted.
`admission_shed_below_priority` `AGENTFOX_ADMISSION_SHED_BELOW_PRIORITY`	`normal`	Under saturation, work below this priority is shed first.
`service_probe_interval_seconds` `AGENTFOX_SERVICE_PROBE_INTERVAL_SECONDS`	`5.0`	How long a dependency health probe is reused. Status endpoints always probe fresh.
`verified_state_max_age_seconds` `AGENTFOX_VERIFIED_STATE_MAX_AGE_SECONDS`	`300`	How fresh a state read must be to authorise an irreversible act.
`data_access_strictness` `AGENTFOX_DATA_ACCESS_STRICTNESS`	`standard`	standard escalates a query on an undeclared table; strict blocks it.
`sql_dialect` `AGENTFOX_SQL_DIALECT`	`postgres`	Dialect SQL artefacts are parsed in (sql extra). A wrong parse fails closed.
`memory_unverified_ttl_seconds` `AGENTFOX_MEMORY_UNVERIFIED_TTL_SECONDS`	`86400`	How long an unverified memory entry survives before it decays.
`agent_message_validity_seconds` `AGENTFOX_AGENT_MESSAGE_VALIDITY_SECONDS`	`300`	Oldest an inter-agent message signature may be and still verify.

Entitlement

Key and variable	Default	What it does
`entitlement_engine` `AGENTFOX_ENTITLEMENT_ENGINE`	`native`	native, or openfga. The OpenFGA adapter is a declared seam, not an implementation yet.
`openfga_url` `AGENTFOX_OPENFGA_URL`	`unset`	OpenFGA endpoint.
`openfga_store_id` `AGENTFOX_OPENFGA_STORE_ID`	`unset`	OpenFGA store.
`k_anonymity_threshold` `AGENTFOX_K_ANONYMITY_THRESHOLD`	`5`	Smallest group an aggregate answer may describe.

Audit and evidence

Key and variable	Default	What it does
`audit_signing_key` `AGENTFOX_AUDIT_SIGNING_KEY`	`dev-insecure-checkpoint-key`	Signs audit-chain checkpoints. Keep it outside the database. Outside development the gateway refuses to start while it is the published default.
`audit_signing_key_previous` `AGENTFOX_AUDIT_SIGNING_KEY_PREVIOUS`	`unset`	Retired signing keys, comma-separated. Checkpoints they signed still verify; agentfox admin keys rotate verifies the chain and re-signs them with the current key, then remove them.
`audit_checkpoint_interval` `AGENTFOX_AUDIT_CHECKPOINT_INTERVAL`	`100`	Chain entries between signed checkpoints.
`redact_at_capture` `AGENTFOX_REDACT_AT_CAPTURE`	`true`	Redact detected sensitive values before they are written to the audit log.

Improvement loop and scheduler

Key and variable	Default	What it does
`improvement_frozen` `AGENTFOX_IMPROVEMENT_FROZEN`	`false`	Kill switch for the improvement loop: nothing is applied automatically; proposals are still filed.
`improvement_actor_id` `AGENTFOX_IMPROVEMENT_ACTOR_ID`	`agentfox-improver`	The identity automated changes are recorded under.
`improvement_max_auto_changes_per_day` `AGENTFOX_IMPROVEMENT_MAX_AUTO_CHANGES_PER_DAY`	`20`	Cap on automated applies per tenant per day.
`improvement_rollback_budget` `AGENTFOX_IMPROVEMENT_ROLLBACK_BUDGET`	`0.05`	A change class rolled back more often than this drops an autonomy level.
`canary_min_dwell_seconds` `AGENTFOX_CANARY_MIN_DWELL_SECONDS`	`3600`	Minimum time a canaried change runs before it can be settled.
`canary_max_block_rate_drop` `AGENTFOX_CANARY_MAX_BLOCK_RATE_DROP`	`0.15`	How much less the candidate may block before the canary rolls it back.
`scheduler_enabled` `AGENTFOX_SCHEDULER_ENABLED`	`true`	Whether scheduled jobs are queued.
`monitor_batch_limit` `AGENTFOX_MONITOR_BATCH_LIMIT`	`5`	Most due monitors one monitors.run job runs; the rest wait for the next runner call.
`monitor_failure_threshold` `AGENTFOX_MONITOR_FAILURE_THRESHOLD`	`3`	Failed runs in a row before a monitor raises a monitor_failing finding.
`job_stuck_after_seconds` `AGENTFOX_JOB_STUCK_AFTER_SECONDS`	`900`	A running job older than this counts as crashed and is recovered.
`job_backoff_base_seconds` `AGENTFOX_JOB_BACKOFF_BASE_SECONDS`	`60`	Base of the exponential retry delay.
`live_probes_enabled` `AGENTFOX_LIVE_PROBES_ENABLED`	`true`	Kill switch for scheduled probes against deployed agents. Each target also needs its own recorded opt-in.
`showcase_enabled` `AGENTFOX_SHOWCASE_ENABLED`	`false`	Probe the demo support agent in its own tenant every hour and publish the counts at GET /api/public/showcase.
`showcase_org_id` `AGENTFOX_SHOWCASE_ORG_ID`	`org_showcase`	The tenant the showcase lives in. The public endpoint reads nothing else.

Evaluation

Key and variable	Default	What it does
`eval_runner` `AGENTFOX_EVAL_RUNNER`	`native`	native, or promptfoo.
`promptfoo_bin` `AGENTFOX_PROMPTFOO_BIN`	`promptfoo`	The promptfoo executable.
`online_eval_sample_rate` `AGENTFOX_ONLINE_EVAL_SAMPLE_RATE`	`0.25`	Share of production traffic agentfox test online samples.
`drift_psi_threshold` `AGENTFOX_DRIFT_PSI_THRESHOLD`	`0.2`	Population stability index above which agentfox report drift reports drift.

Integrations: webhooks and trace correlation

Key and variable	Default	What it does
`webhook_url` `AGENTFOX_WEBHOOK_URL`	`unset`	Each new finding at or above webhook_min_severity is POSTed here. Needs allow_egress.
`webhook_secret` `AGENTFOX_WEBHOOK_SECRET`	`unset`	Adds X-AgentFox-Signature: sha256=<HMAC of the body>.
`webhook_timeout_seconds` `AGENTFOX_WEBHOOK_TIMEOUT_SECONDS`	`3.0`	Per-delivery timeout; one retry on 5xx or timeout.
`webhook_min_severity` `AGENTFOX_WEBHOOK_MIN_SEVERITY`	`high`	critical, high, medium or low.
`slack_webhook_url` `AGENTFOX_SLACK_WEBHOOK_URL`	`unset`	Slack incoming webhook for monitor findings opened, reopened or closed. Needs allow_egress. A tenant can also set its own (PUT /api/alerts/slack).
`slack_min_severity` `AGENTFOX_SLACK_MIN_SEVERITY`	`medium`	critical, high, medium or low.
`github_webhook_secret` `AGENTFOX_GITHUB_WEBHOOK_SECRET`	`unset`	Verifies X-Hub-Signature-256 on /api/integrations/github/webhook. A connection may carry its own instead; with neither, push deliveries are refused.
`correlation_push` `AGENTFOX_CORRELATION_PUSH`	`false`	Write the verdict back onto the LangSmith or Langfuse run. Correlation itself needs no setting.
`correlation_timeout_seconds` `AGENTFOX_CORRELATION_TIMEOUT_SECONDS`	`2.0`	Timeout for that write-back.
`langsmith_api_key` `AGENTFOX_LANGSMITH_API_KEY`	`unset`	LangSmith key for write-back.
`langsmith_project` `AGENTFOX_LANGSMITH_PROJECT`	`unset`	LangSmith project.
`langsmith_api_url` `AGENTFOX_LANGSMITH_API_URL`	`https://api.smith.langchain.com`	LangSmith API.
`langsmith_ui_url` `AGENTFOX_LANGSMITH_UI_URL`	`https://smith.langchain.com`	LangSmith UI, for links.
`langfuse_public_key` `AGENTFOX_LANGFUSE_PUBLIC_KEY`	`unset`	Langfuse public key.
`langfuse_secret_key` `AGENTFOX_LANGFUSE_SECRET_KEY`	`unset`	Langfuse secret key.
`langfuse_project` `AGENTFOX_LANGFUSE_PROJECT`	`unset`	Langfuse project.
`langfuse_host` `AGENTFOX_LANGFUSE_HOST`	`https://cloud.langfuse.com`	Langfuse host.

Read outside Settings

A few variables are read straight from the environment, because they decide where settings come from or are used by a separate program. None of them can go in agentfox.toml.

Variable	What it does
`AGENTFOX_STATE_DIR`	Directory for the default database and evidence. It decides the defaults of database_url and evidence_dir, so it is not itself a setting.
`AGENTFOX_CONFIG`	Path to the TOML file to read. It must exist. none, off or - turns file loading off.
`AGENTFOX_AGENT`	Agent slug for agentfox.auto() when none is passed. Then OTEL_SERVICE_NAME, SERVICE_NAME, APP_NAME, K_SERVICE, the script name, and finally default-agent.
`AGENTFOX_API_URL, AGENTFOX_API_TOKEN, AGENTFOX_USER`	Where agentfox scan --submit sends a redacted summary, and the credential it uses.
`AGENTFOX_AUDIT_KEY`	Then AGENTFOX_AUDIT_SIGNING_KEY. Read by the verify_chain.py inside an evidence package to check checkpoint signatures.
`AGENTFOX_MCP_LOG_LEVEL`	Log level of agentfox serve mcp. Default WARNING.
`CRON_SECRET`	Accepted in addition to cron_secret by /api/internal/jobs/run (Vercel Cron sets it).
`JEV_API_KEY`	Key for the hosted jev judgment tier. Without it that tier is unavailable.

Dashboard

Variable	Default	What it does
`AGENTFOX_API_URL`	http://127.0.0.1:8080	The gateway the dashboard calls, server to server. Include the scheme.
`AGENTFOX_API_TOKEN`	unset	A static operator token for the dashboard's own calls. A signed-in user's token takes precedence.
`AGENTFOX_USER`	admin@example.com	The development identity header value, used when there is no token. A gateway outside development refuses it.
`AGENTFOX_PLAYGROUND_API_URL`	AGENTFOX_API_URL	The gateway address the visitor's browser uses on the public playground page.
`AGENTFOX_SERVICE_AUTH_SECRET`	unset	Must equal the gateway's service_auth_secret, or GitHub sign-in fails at provisioning.
`AGENTFOX_SITE_URL`	the public site	Canonical URL used in page metadata.
`AGENTFOX_SELF_HOSTED`	unset	Marks a self-hosted dashboard in the interface.
`GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET`	unset	The GitHub OAuth app for sign-in. Unset: sign-in is unavailable.

What can go wrong

A hosted provider or webhook does nothing. allow_egress is false. A configured key or URL with egress off sends nothing.
A detector you enabled never fires. Its extra or weights are missing, so it is unavailable and skipped. agentfox doctor lists the available ones.
The development header is refused. environment is not a development name, so auth_mode = auto requires tokens. agentfox admin auth status says which.
GitHub sign-in fails at provisioning. service_auth_secret differs between the gateway and the dashboard.