Privacy infrastructure for the modern web
A self-hosted, multi-tenant cookie consent management platform.
Source-available alternative to OneTrust, Cookiebot and CookieYes.
ConsentOS gives you a single <script> tag to embed on your site and a self-hosted dashboard to manage everything behind it: consent collection, cookie blocking, scanning, compliance checking, and audit trails. The full surface — banner, API, scanner, admin UI — is in this repository, with no SaaS lock-in.
Why ConsentOS
- Privacy by design, not by default. Consent is given, not assumed. Auto-blocking is on by default; visitors don't get tracked until they opt in.
- Standards-complete. IAB TCF v2.2, GPP v1 (six US state sections), Google Consent Mode v2, GPC, Shopify Customer Privacy API.
- Yours to host. Source-available under the Elastic Licence 2.0 — you can self-host indefinitely, modify freely, and run it on your own infrastructure.
- Built for compliance teams. Rule-based compliance checks for GDPR, CNIL, CCPA/CPRA, ePrivacy and LGPD, plus a tamper-evident consent record audit trail.
- Multi-tenant from day one. Organisations, sites, role-based access. Configuration cascades System → Org → Site Group → Site → Region.
Features
- Consent banner — ~2KB loader + ~26KB bundle, gzipped, rendered in a Shadow DOM root for total style isolation
- Auto-blocking — intercepts script creation, cookie writes, and storage API calls until consent is granted; releases per-category
- Cookie scanner — Playwright-driven crawl with auto-categorisation against the Open Cookie Database (2,200+ patterns)
- Dark pattern detection — flags pre-ticked boxes, missing reject buttons, button asymmetry, scroll-based dismissal
- Compliance engine — rules for GDPR, CNIL, CCPA/CPRA, ePrivacy, LGPD with severity scoring
- Configuration cascade — defaults → org → site group → site → regional override
- Display modes — bottom banner, top banner, overlay modal, corner popup, inline
- Consent withdrawal — persistent floating button so visitors can change their mind (GDPR Art. 7(3))
- i18n-ready banner — translations API per site, locale auto-detection
- GeoIP-aware — region-specific consent modes (opt-in for EU, opt-out for US-CA, etc.)
Architecture
┌─────────────────────────────────────────────────────┐
│ Client Browser │
│ ┌─────────────┐ ┌──────────┐ ┌───────────────┐ │
│ │ Consent │ │ Script │ │ Banner UI │ │
│ │ Loader (2KB)│→ │ Blocker │ │ (Shadow DOM) │ │
│ └──────┬──────┘ └──────────┘ └───────────────┘ │
│ │ TCF v2.2 · GCM v2 · GPP v1 · GPC │
└─────────┼───────────────────────────────────────────┘
│
▼
┌─────────────────────┐ ┌──────────────────────┐
│ FastAPI Backend │ │ Scanner Service │
│ · Config API │ │ · Playwright crawler│
│ · Consent API │ │ · Auto-categoriser │
│ · Compliance API │ │ · Celery worker │
└─────────┬───────────┘ └──────────────────────┘
│
┌─────┴──────┐
│ PostgreSQL │ Redis (cache + queue)
└────────────┘
Quick start
Prerequisites
- Docker and Docker Compose v2.15+
- Node.js 20+ and npm
- Python 3.12+ and uv
Setup
# Clone and configure
git clone https://github.com/consentos/consentos.git
cd consentos
cp .env.example .env
# Start the dev environment
make up
# Run migrations and seed cookie categories
make seed
| Service | URL |
|---|---|
| API docs | http://localhost:8000/docs |
| Admin UI | http://localhost:5173 |
The admin UI dog-foods the banner script at http://localhost:5173/banner/consent-loader.js. In production you'd publish those files to a CDN and point CDN_BASE_URL at it.
Bootstrapping the first organisation
The POST /api/v1/organisations/ endpoint is gated behind a static admin token by default. To create your initial organisation:
- Set
ADMIN_BOOTSTRAP_TOKENin.envto a strong random value (openssl rand -hex 32) - Restart the API
curl -X POST http://localhost:8000/api/v1/organisations/ -H "X-Admin-Bootstrap-Token: <your-token>" -H "Content-Type: application/json" -d '{"name": "Acme", "slug": "acme"}'- Unset or rotate
ADMIN_BOOTSTRAP_TOKENonce your org is created — leaving it set means anyone with the value can keep creating tenants.
Running tests
make test-infra-up # Start test PostgreSQL + Redis
make test # Run API tests
make test-cov # With coverage
make test-infra-down # Tear down
Banner and admin UI tests:
cd apps/banner && npm test
cd apps/admin-ui && npm test
Project structure
consentos/
├── apps/
│ ├── api/ # FastAPI backend (Python)
│ ├── scanner/ # Playwright cookie scanner (Python)
│ ├── banner/ # Consent banner script (TypeScript)
│ └── admin-ui/ # Admin dashboard (React + TypeScript)
├── assets/brand/ # Logo, palette, brand guidelines
├── helm/ # Kubernetes Helm chart
├── sdks/ # Mobile SDKs (iOS, Android)
├── docker-compose.yml # Development environment
└── Makefile
Technology
| Layer | Stack |
|---|---|
| API | Python 3.12, FastAPI, SQLAlchemy 2.0 (async), Alembic |
| Scanner | Python 3.12, Playwright, Celery |
| Banner | TypeScript, Rollup, Shadow DOM |
| Admin UI | React 19, Vite, shadcn/ui, TailwindCSS, TanStack Query |
| Database | PostgreSQL 16 |
| Cache | Redis 7 |
| Infra | Docker Compose, Kubernetes (Helm), Ansible |
Known cookies database
ConsentOS ships with the Open Cookie Database — a community-maintained catalogue of 2,200+ cookie patterns used for auto-categorisation during scans. To update:
curl -L https://raw.githubusercontent.com/jkwakman/Open-Cookie-Database/master/open-cookie-database.csv \
-o apps/api/data/open-cookie-database.csv
make seed
Contributing
See CONTRIBUTING.md for setup instructions, coding standards, and PR guidelines. We follow Conventional Commits and write everything in British English.
Security
To report a vulnerability, see SECURITY.md. Please do not open public issues for security reports.
Licence
ConsentOS is licensed under the Elastic Licence 2.0 (ELv2) — a source-available licence.
You may use, copy, distribute, and modify the software freely, with two restrictions:
- You may not provide it to third parties as a hosted or managed service
- You may not circumvent any licence key functionality
This means: self-host it on your own infrastructure as much as you like; offer it to your customers as part of a wider product; modify it to your heart's content. You just can't resell ConsentOS itself as a SaaS — that's how the project sustains itself.
The known cookies database (apps/api/data/open-cookie-database.csv) is sourced from the Open Cookie Database under CC BY 4.0.
See the LICENSE file for the full licence text and copyright notice.