Skip to main content

Configuration Directives

Core​

listen_addr 0.0.0.0:8080;
redis_url redis://redis:6379;

Upstream​

upstream_provider openai_compatible;
upstream_base_url https://api.openai.com;
upstream_api_key sk-xxxx;

upstream_base_url may be the provider root URL or its /v1 base path.

Correct:

upstream_base_url http://ollama:11434/v1;

Wrong:

upstream_base_url http://ollama:11434/v1/chat/completions;

Placeholder no-auth values:

dummy
none
null
-

Embeddings​

embedding_provider openai_compatible;
embedding_base_url https://api.openai.com;
embedding_api_key sk-xxxx;
embedding_model text-embedding-3-small;
embedding_price 0.020;

For local providers without authentication, use dummy, none, null, or -. Placeholder keys do not create upstream bearer auth headers.

Qdrant​

qdrant_url http://qdrant:6334;
qdrant_api_key your-qdrant-key;
qdrant_collection aif_semantic_cache;
qdrant_vector_size 1536;

qdrant_vector_size must match the embedding model. Existing collections are validated at startup.

Cache lifecycle​

cache_ttl_seconds 86400;
exact_cache_ttl_seconds 86400;
semantic_cache_retention_seconds 604800;

Request behavior​

request_timeout_seconds 120;
max_request_body_bytes 1M;

Request limits​

max_request_body_bytes 1M;

Supported formats:

1024
512K
1M
2M

Semantic cache​

semantic_cache_enabled true;
semantic_cache_fail_open true;
semantic_similarity_threshold 0.92;

semantic_cache_fail_open applies to runtime lookup failures only, not startup initialization.

Model pricing​

model_price gpt-4o-mini-2024-07-18 0.15 0.60;
allow_unknown_models_pass_through false;

For providers with variable model names, such as OpenRouter, use:

allow_unknown_models_pass_through true;

Guard orchestration directives​

security_guard_enabled​

Enable VCAL Security Guard orchestration.

security_guard_enabled true;

Default: false.

security_guard_url​

Base URL for VCAL Security Guard.

security_guard_url http://vcal-security-guard:8091;

Do not include /v1/scan; AI Firewall appends the endpoint internally.

security_guard_api_key​

Service-to-service API key for VCAL Security Guard.

security_guard_api_key your-security-guard-key;

security_guard_timeout_seconds​

Timeout for Security Guard calls.

security_guard_timeout_seconds 3;

privacy_guard_enabled​

Enable VCAL Privacy Guard orchestration.

privacy_guard_enabled true;

Default: false.

privacy_guard_url​

Base URL for VCAL Privacy Guard.

privacy_guard_url http://vcal-privacy-guard:8090;

Do not include /v1/scan or /v1/restore; AI Firewall appends endpoints internally.

privacy_guard_api_key​

Service-to-service API key for VCAL Privacy Guard.

privacy_guard_api_key your-privacy-guard-key;

privacy_guard_mode​

Privacy Guard scan mode.

privacy_guard_mode anonymize;

Common values are detect_only, redact, and anonymize.

privacy_guard_restore_enabled​

Enable Privacy Guard placeholder restoration on assistant responses.

privacy_guard_restore_enabled true;

privacy_guard_timeout_seconds​

Timeout for Privacy Guard scan and restore calls.

privacy_guard_timeout_seconds 3;

guard_fail_open​

Controls behavior when an enabled guard is unavailable, times out, or returns an invalid contract.

guard_fail_open false;

Recommended enterprise value: false.

ValueBehavior
trueContinue request processing when a guard fails
falseFail closed and reject the request when a guard fails

VCAL Audit evidence delivery​

AI Firewall v0.4.2 can deliver vcal.evidence.event schema version 1.1 batches to VCAL Audit.

audit_enabled false;
audit_url http://vcal-audit:8092;
# audit_api_key replace-with-shared-audit-token;
audit_producer_instance_id ai-firewall-01;
audit_queue_capacity 10000;
audit_batch_size 100;
audit_flush_interval_ms 1000;
audit_request_timeout_seconds 5;
audit_retry_max_attempts 5;
audit_retry_initial_backoff_ms 250;
DirectivePurpose
audit_enabledEnables buffered delivery to VCAL Audit.
audit_urlBase URL of VCAL Audit; batches are posted to /v1/events/batch.
audit_api_keyShared API key sent to VCAL Audit.
audit_producer_instance_idStable producer identifier recorded with delivered batches.
audit_queue_capacityMaximum number of evidence events held in the in-memory queue.
audit_batch_sizeMaximum number of events sent in one batch.
audit_flush_interval_msMaximum time before a partial batch is flushed.
audit_request_timeout_secondsHTTP request timeout for a batch delivery attempt.
audit_retry_max_attemptsMaximum delivery attempts for a failed batch.
audit_retry_initial_backoff_msInitial exponential retry backoff.

When enabled, delivery is asynchronous and uses a bounded in-memory queue. Batches are sent when the configured batch size is reached or the flush interval expires. Failed deliveries are retried with backoff. After retry exhaustion, the batch is dropped and the failure is logged rather than blocking the LLM request path.