Docker Compose

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

Clone the repository

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

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 the 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.

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.

Open the dashboard

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

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

Service	Port	Role
`postgres`	5432	TimescaleDB — primary datastore
`redis`	6379	Job queue (`safety_score_jobs`)
`migrate`	—	One-shot: runs `alembic upgrade head` and exits
`api`	8000	FastAPI backend — REST API and Stripe webhooks
`safety_worker`	—	Safety scoring worker
`proxy`	8080	Go LLM reverse proxy
`web`	3000	Next.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

Getting Started

SDKs

LLM Providers

Self-hosted Models

Self-hosting

Integrations

Reference Architectures

Deployment Blueprints

Safety & Scoring

Prerequisites

Steps

Services

Scaling safety workers

Updating

Stripe local webhook forwarding

Running in detached mode

​Prerequisites

​Steps

​Services

​Scaling safety workers

​Updating

​Stripe local webhook forwarding

​Running in detached mode

Prerequisites

Steps

Services

Scaling safety workers

Updating

Stripe local webhook forwarding

Running in detached mode