OpenComplAI — Quickstart Guide¶

Get EU AI Act compliance checks running in under 5 minutes.

Prerequisites¶

Docker & Docker Compose ≥ 2.20
curl and bash (for the compliance check script)
Git

1. Clone & start the stack¶

git clone https://github.com/opencomplai/opencomplai.git
cd opencomplai
docker compose up -d

Verify all services are healthy:

curl http://localhost:3000/health
# {"status":"ok","service":"gateway-api"}

2. Run a sample compliance check¶

cd examples/sample-system
./run-compliance-check.sh

You should see:

[PASS]  EU AI Act compliance check PASSED
  System:    sample-credit-scoring-v1
  Badge ID:  sha256:...
  SVG badge: http://localhost:3000/v1/pro/badges/sha256:.../svg

3. Add your own system¶

Copy the manifest template to your AI system repository:

cp examples/sample-system/manifest.yaml /path/to/your-ai-system/

Edit manifest.yaml — update system.id, system.name, system.risk_class, and add your controls.
Copy the compliance check script:

cp examples/sample-system/run-compliance-check.sh /path/to/your-ai-system/
chmod +x run-compliance-check.sh

Run it:

OPENCOMPLAI_GATEWAY_URL=http://localhost:3000 ./run-compliance-check.sh

4. Add to CI/CD¶

Copy the GitHub Actions workflow template into your repository:

cp .github/workflows/compliance-gate.yml.example \
   /path/to/your-ai-system/.github/workflows/compliance-gate.yml

Set the OPENCOMPLAI_GATEWAY_URL secret in your repository settings:

GitHub → Settings → Secrets and variables → Actions → New repository secret

5. Embed the compliance badge in your README¶

After a successful check, add the SVG badge to your README.md:

![EU AI Act Compliant](https://your-opencomplai.example.com/v1/pro/badges/<badge_id>/svg)

6. Verify ledger integrity¶

Run the standalone ledger verifier (no dependencies required):

python3 tools/verify-ledger/verify_ledger.py \
  --gateway-url http://localhost:3000

Expected output:

[INFO]  Checking ledger integrity at: http://localhost:3000/v1/evidence/verify-chain
[PASS]  Evidence ledger chain is valid — no tampering detected

Architecture overview¶

Your AI System
      │ manifest.yaml + run-compliance-check.sh
      ▼
┌─────────────────┐
│  gateway-api    │ :3000  ─── all external traffic
└────────┬────────┘
         │
    ┌────┴──────┬────────────────┐
    ▼           ▼                ▼
evidence-   egress-proxy    (other services)
vault :8002   :8004
    │           │
    │      DLP allowlist
    │      (REQ-ARC-001)
    ▼
Merkle ledger + badge store

Service ports (default)¶

Service	Port	Description
gateway-api	3000	Main entry point — all client traffic
evidence-vault	8002	Ledger, badges, CAS storage
egress-proxy	8004	DLP enforcement for outbound sync

Next steps¶

Read the PRD for full requirements coverage
Run the full test suite: uv run pytest
Benchmark TTFS: ./scripts/benchmark-ttfs.sh
Browse the API docs: http://localhost:3000/docs (when running locally)