Skip to main content

Quick Start with Docker

Docker Compose is the fastest way to run AI Cost Firewall.

The Compose stack includes AI Cost Firewall, Redis, Qdrant, Prometheus, and Grafana.

Prerequisites​

docker --version
docker compose version

Clone and configure​

git clone https://github.com/vcal-project/ai-firewall.git
cd ai-firewall
cp configs/ai-firewall.conf.example configs/ai-firewall.conf
nano configs/ai-firewall.conf

Configure your upstream API key, embedding API key if semantic cache is enabled, and exact model pricing:

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

Start the stack​

docker compose pull
docker compose up -d

Check services​

docker compose ps
docker compose logs -f firewall
ServiceURL
Firewall APIhttp://localhost:8080
Prometheushttp://localhost:9090
Grafanahttp://localhost:3000

Health and readiness​

curl -i http://localhost:8080/healthz
curl -i http://localhost:8080/readyz

Expected healthy result:

HTTP/1.1 200 OK

Validate configuration​

--test-config performs static validation only.

docker compose run --rm firewall \
  --config /configs/ai-firewall.conf \
  --test-config

Expected output:

configuration OK

This does not connect to Redis, Qdrant, embedding providers, or upstream LLM providers.

docker compose run --rm firewall \
  --config /configs/ai-firewall.conf \
  --print-config

Send a test request​

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini-2024-07-18",
    "messages": [
      {"role": "user", "content": "Say hello."}
    ]
  }'

View metrics​

curl http://localhost:8080/metrics