Skip to main content

Documentation Index

Fetch the complete documentation index at: https://cognisafeltd.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

Docker Compose is the fastest way to get the full stack running. All six services start with a single command.

​
Prerequisites

  • Docker Engine 24+ and Docker Compose v2
  • Git

​
Steps

1

Clone the repository

git clone https://github.com/cognisafe/cognisafe.git
cd cognisafe
2

Configure environment variables

cp .env.example .env
Open .env and fill in the required values:
# Required
PROXY_API_KEY=csk_your_key_here          # auth key for the proxy
OPENAI_API_KEY=sk-...                    # used by PyRIT safety scorers
STRIPE_SECRET_KEY=sk_live_...            # Stripe API key
STRIPE_WEBHOOK_SECRET=whsec_...          # Stripe webhook signing secret
STRIPE_PRICE_PRO=price_...               # Stripe price ID for Pro tier
STRIPE_PRICE_TEAM=price_...              # Stripe price ID for Team tier

# Pre-filled with sensible defaults — change if needed
POSTGRES_URL=postgresql+asyncpg://postgres:postgres@postgres:5432/cognisafe
REDIS_URL=redis://redis:6379
For local development without Stripe, leave the Stripe vars blank — billing routes will return errors but all other functionality works.
3

Start the stack

docker compose -f infra/docker-compose.yml up
On first run, Docker pulls the images and the migrate service runs alembic upgrade head to initialise the database schema before the API starts.
The migrate service is a one-shot container. It runs database migrations and exits with code 0. If you see it listed as “exited” in docker compose ps, that is expected — it completed successfully.
4

Open the dashboard

Navigate to http://localhost:3000.The proxy is available at http://localhost:8080 and the API at http://localhost:8000.
5

Point your SDK at the local stack

import cognisafe

cognisafe.configure(
    api_key="csk_your_key_here",  # same as PROXY_API_KEY in .env
    project_id="my-app",
    proxy_url="http://localhost:8080",
    api_url="http://localhost:8000",
)
cognisafe.patch_openai()

​
Services

ServicePortRole
postgres5432TimescaleDB — primary datastore
redis6379Job queue (safety_score_jobs)
migrate—One-shot: runs alembic upgrade head and exits
api8000FastAPI backend — REST API and Stripe webhooks
safety_worker—PyRIT scoring worker
proxy8080Go LLM reverse proxy
web3000Next.js dashboard

​
Scaling safety workers

The safety_worker is stateless and horizontally scalable. Increase throughput by running multiple instances: 
docker compose -f infra/docker-compose.yml up --scale safety_worker=3
Each worker independently reads from the Redis queue. Three workers process three scoring jobs concurrently.

​
Updating

git pull
docker compose -f infra/docker-compose.yml up --build
Database migrations run automatically via the migrate service on startup.

​
Stripe local webhook forwarding

To test billing flows locally, forward Stripe webhooks to your local API: 
stripe listen --forward-to localhost:8000/webhook/stripe
Copy the webhook signing secret printed by the CLI into STRIPE_WEBHOOK_SECRET in .env, then restart the API service.

​
Running in detached mode

docker compose -f infra/docker-compose.yml up -d
docker compose -f infra/docker-compose.yml logs -f api safety_worker