Saklam Bridge — Setup-Guide

Drop-in LLM-Proxy mit automatischer PII-Maskierung. On-Premises in eurer eigenen Infra, Zero-Knowledge gegenüber Saklam, DSGVO-konform — sensible Daten bleiben on-prem.

Diese Anleitung führt euch durch Installation und Inbetriebnahme des Saklam-Bridge-Containers in eurem eigenen Netz. Ihr behaltet die volle Datenhoheit: Klartext verlässt eure Infrastruktur nie unmaskiert.

Architektur in einem Bild

App-Server / Workstations / CI
  Claude Code · Cursor · Eigenanwendungen
    │
    │  ANTHROPIC_BASE_URL=http://bridge.intern.example.com
    │  ANTHROPIC_API_KEY=sk-bridge-<euer-master-key>
    ▼
┌─ Saklam Bridge (Docker in eurer Infra) ─────────────────────────┐
│  1. Eingehender Request mit sensiblem Klartext                   │
│  2. PII-Maskierung (300+ Patterns, EU-27, 20+ Sprachen)          │
│  3. Forward an Anthropic/OpenAI/Mistral mit eurem API-Key (BYOK) │
│  4. Response demaskieren                                         │
└──────────────────────────────────────────────────────────────────┘
    │
    │  Maskierte Tokens, euer API-Key
    ▼
Anthropic / OpenAI / Mistral

Was Saklam sieht: nichts. Der Saklam-Server hat keine Verbindung zu eurem Container. Was der LLM-Provider sieht: maskierte Tokens, niemals Klartext.

Voraussetzungen

Quick-Install (5 Minuten)

# 1. Verzeichnis anlegen
mkdir -p /opt/saklam-bridge && cd /opt/saklam-bridge

# 2. docker-compose.yml + .env.example herunterladen
curl -fsSL https://saklam.com/bridge/docker-compose.yml -o docker-compose.yml
curl -fsSL https://saklam.com/bridge/env.example -o .env.example

# 3. .env vorbereiten
cp .env.example .env
$EDITOR .env
#   - SAKLAM_LICENSE_KEY=sk-lic-…                          (Pflicht — aus Aktivierungs-Mail/Dashboard)
#   - ANTHROPIC_API_KEY=sk-ant-api03-…                     (Pay-as-you-go-Key)
#   - BRIDGE_MASTER_KEY=$(openssl rand -hex 32)            (optional, siehe Auth-Modi unten)

# 4. Start
docker compose pull
docker compose up -d

# 5. Smoke-Test
sleep 5
curl -fsS http://localhost:4000/health/readiness

Auth-Modi (Master-Key)

Erwartete Antwort: {"status":"connected"} (HTTP 200).

Tool-Integration

Claude Code (CLI)

export ANTHROPIC_BASE_URL=http://localhost:4000
export ANTHROPIC_API_KEY=<euer BRIDGE_MASTER_KEY aus .env>
claude

In der gestarteten Claude-Session beliebigen Prompt mit Klartext-PII testen:

> "Schreibe ein Mahnschreiben an Max Mustermann, Musterstr. 12, 80331 München, Forderung 1.245,50 €."

Die Bridge maskiert Max Mustermann → [PER_a1b2c3d4], Musterstr. 12, 80331 München → [LOC_…], sendet die maskierte Version an Anthropic und demaskiert die Antwort vor der Rückgabe.

Cursor

Cursor Settings → Models → API Keys:

• Anthropic API Key: <BRIDGE_MASTER_KEY>
• Anthropic Base URL: http://localhost:4000 (oder http://bridge.intern.example.com)

Eigene Skripte (Python anthropic SDK)

from anthropic import Anthropic

client = Anthropic(
    base_url="http://localhost:4000",
    api_key="<BRIDGE_MASTER_KEY>",
)

resp = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Kunde: Müller, Vorgang 2025/4711, Betrag 18k €."}]
)

n8n (self-hosted)

Eigene Anleitung mit Chat-Workflow, Credential-Setup und Abgrenzung zum n8n-Guardrails-Node: Saklam Bridge + n8n. Kurzform: OpenAI-Credential mit Base URL = http://saklam-bridge:4000/v1 — auch für Claude (n8ns Anthropic-Credential hat kein Base-URL-Feld).

LAN-Erreichbarkeit für Team-Workstations

Default bindet die Bridge auf 127.0.0.1:4000. Für netzweiten Zugriff:

1. In .env: BRIDGE_BIND_ADDR=0.0.0.0
2. Reverse-Proxy (nginx/Caddy/Traefik) mit TLS davor — niemals plain HTTP über LAN, weil sensibler Klartext zwischen Workstation und Bridge fließt.
3. docker compose up -d neu starten.

Eigene Erkennung (Custom Detection)

Die Bridge erkennt ab Werk 335+ PII-Muster. Eigene sensible Daten — Projektnamen, Vorgangsnummern, Fachbegriffe — ergänzt ihr über einen Ordner ./custom neben der docker-compose.yml (Volume in der Compose-Datei einkommentieren, Container neu starten). Kein Code, kein Training, kein Image-Neubau. Drei Dateiarten:

# custom/labels.yaml
labels:
  medikament: MEDIKAMENT
  diagnose: DIAGNOSE
ner_threshold: 0.5   # optional; höher = strenger

Alles ist additiv zu den eingebauten Mustern und läuft durch denselben Maskier-/Demaskier-Roundtrip und Audit-Trail. Hinweis: Mit konfigurierten KI-Entitäten läuft immer die volle NER-Analyse (~1–2 s/Request auf CPU) — Begriffslisten und Regex-Muster haben diesen Effekt nicht. Zero-Shot-Labels vor Produktivbetrieb mit echten Beispieltexten testen; für aufzählbare Begriffe ist die Liste immer die präzisere Wahl.

Updates

cd /opt/saklam-bridge
docker compose pull
docker compose up -d

Wir empfehlen ein Wartungsfenster wöchentlich oder nach Saklam-Release-Notes. Patch-Releases sind kompatibel; Major-Versionen werden im Release-Channel angekündigt.

Auth-Note (wichtig vor Setup)

Saklam Bridge funktioniert ausschließlich mit klassischen API-Keys (pay-as-you-go), nicht mit Subscription-OAuth.

Funktioniert nicht:

• Anthropic Max / Pro / Team OAuth-Subscription-Tokens
• ChatGPT Plus / Team Web-Sessions

Unterstützte Provider (alle BYOK = Bring Your Own Key, Saklam tritt nicht als Reseller auf):

Ihr wählt einen oder mehrere Provider und tragt die entsprechenden Env-Variablen in .env ein. Nur ANTHROPIC_API_KEY ist pflicht (Default-Provider beim ersten Start) — alle anderen optional. Config-Routing erfolgt automatisch über Modellname-Präfix:

• claude-* → Anthropic
• gpt-* / openai/* → OpenAI (direkt)
• azure/* → Azure OpenAI
• gemini/* → Google Gemini
• bedrock/* → AWS Bedrock
• mistral/* → Mistral
• ollama/* → Self-hosted

Hybrid-Routing: lokales Modell + maskiertes Frontier (ein Gateway)

Ihr müsst euch nicht zwischen „lokales Modell" und „Frontier-Qualität" entscheiden — die Bridge routet beides:

• Routine-Aufgaben → lokales Modell (ollama/…): Der Request verlässt den Host nie. Zusammenfassungen, Klassifikation, einfache Entwürfe.
• Komplexe Aufgaben → Frontier, maskiert (claude-…, gpt-…): PII wird ersetzt, bevor der Request rausgeht, die Antwort lokal demaskiert.

Beide Pfade laufen durch dieselbe Maskierung und denselben Audit-Trail — eine Policy, ein Nachweis, egal welches Modell.

Ollama direkt im selben Compose-Stack mitstarten (optionales Profil):

# .env:  OLLAMA_API_BASE=http://ollama:11434/v1
docker compose --profile local-llm up -d
docker compose exec ollama ollama pull llama3.2

Aufruf wie jedes andere Modell, nur mit ollama/-Präfix (OpenAI-Wire):

curl http://localhost:4000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model": "ollama/llama3.2", "messages": [{"role": "user", "content": "…"}]}'

Läuft Ollama schon woanders im Netz, reicht OLLAMA_API_BASE=http://ollama.intern:11434/v1 — das Profil ist nur die Compose-Bequemvariante. Realistische Erwartung: Lokale Modelle auf CPU-Servern sind spürbar langsamer und schwächer als Frontier — das Hybrid-Muster heißt bewusst „Routine lokal, Komplexes maskiert zu Frontier", nicht „lokal kann alles".

FAQ

Wird das LLM durch die [XXX_yyyyyyyy]-Platzhalter verwirrt oder verweigert es die Antwort?

Nein. Die Bridge injiziert automatisch eine System-Instruktion in jeden Request (wire-bewusst für Anthropic- und OpenAI-Format), die dem LLM erklärt: Tokens im Format [PER_a1b2c3d4], [EMA_…], [TEL_…] etc. sind maskierte personenbezogene Daten — exakt übernehmen, nicht verändern, nicht erfinden, und „wie die echten Daten" behandeln.

Für normale Aufgaben (Zusammenfassen, Texte, E-Mail-Entwürfe, Analysen) bleibt die Output-Qualität damit voll erhalten — der Platzhalter steht semantisch an Stelle der echten Person/IBAN/Adresse. In der Antwort werden die Platzhalter automatisch wieder demaskiert, bevor sie eure App/euren Client erreichen: Ihr seht die echten Werte, das LLM nie.

Grenzfall, der gewollt ist: Bei Aufgaben, die den exakten Originalwert eines maskierten Feldes brauchen — z.B. „prüfe die Prüfsumme dieser IBAN" oder „wie viele Ziffern hat diese Telefonnummer?" — merkt das LLM korrekt an, dass es nur einen Platzhalter sieht. Solche Format-/Validierungs-Prüfungen gehören auf eure Seite (vor oder nach der Bridge), nicht in die maskierte KI-Anfrage.

Praktischer Nebeneffekt für eigene Tests: Fragt ihr das LLM, ob ein maskiertes Feld „echt" ist, antwortet es mit „das ist ein Platzhalter" — ein direkter, sichtbarer Beleg, dass beim Provider nie Klartext ankommt.

Troubleshooting

unhealthy im docker ps

docker compose logs bridge

Typische Ursachen:

• Erste ~10–30s nach Start: GLiNER-Modell wird aus dem Image in den RAM geladen (Warmup, kein Download — Modell ist im Image) — start_period: 60s im Healthcheck deckt das. Wenn nach 90s noch unhealthy: Logs prüfen.
• ANTHROPIC_API_KEY ungültig → 401 von Anthropic → Bridge meldet keinen Fehler beim Start, aber jeder Request scheitert. Test: curl …/health/liveness (sollte 200 sein selbst ohne Anthropic).

401 Unauthorized bei Anthropic-Calls

Euer API-Key ist ein Max/Team-OAuth-Token statt klassischem sk-ant-…-Key. Siehe Auth-Note oben.

Latenz

Das Modell ist im Image vorinstalliert und wird beim Container-Start in den RAM geladen (kein Download zur Laufzeit, air-gapped-fähig). Der erste PII-Request ist daher nicht durch einen Download verzögert; Anfragen liegen bei ~<100 ms (CPU).

PII wird nicht maskiert

Logs prüfen: docker compose logs bridge | grep -i 'mask'. Häufige Ursachen:

• MASK_API_URL ist gesetzt, aber das Ziel ist nicht erreichbar → Variable in .env entfernen. Default ist in-process (kein externer Mask-Service, kein Netzwerk-Hop).
• Prompt enthält nur Domain-spezifische Kürzel die nicht in den 300+ Patterns sind → Custom-Patterns auf Anfrage

"Disclosure": Bridge zwischenspeichert PII während Request-Verarbeitung

Ja, das ist architektonisch zwangsläufig (RAM-only, kein Disk-Persistence). Ein böswilliger Container-Admin könnte den Prozess inspizieren. Daher: Bridge gehört in eure Infra, nicht zu Saklam.

keine gültige Lizenz / Requests werden mit 5xx abgelehnt

Die Bridge braucht eine gültige Lizenz (aktives Abo). Prüfen:

• SAKLAM_LICENSE_KEY in .env korrekt gesetzt (sk-lic-… aus Aktivierungs-Mail/Dashboard)?
• Abo aktiv? Status im Dashboard.
• Beim Start holt die Bridge automatisch ein signiertes Lizenz-Token (es verlässt nur der Key den Host, keine Kundendaten). Logs: docker compose logs bridge | grep -i lizenz.
• Einmalig Netz zur Aktivierung nötig; danach trägt ein gecachtes Token über kurze Ausfälle (Gnadenfrist).

Logs & Datenschutz

• Default-Logging: strukturierte JSON-Logs (json-file-Driver), rotiert nach 50 MB.
• PII in Logs: Bridge loggt Request-Metadaten (Model, Token-Counts, Latenz), nicht Prompt-Klartext.
• Externes Log-Forwarding (Splunk, ELK, Loki): Standard-Docker-Logging-Mechanismen.
• Auditfähigkeit (opt-in): Manipulationssicherer Audit-Trail als Nachweis gegenüber eurem DSB — DASS maskiert wurde, ohne Klartext.

Audit-Trail aktivieren (für regulierte Anwender)

In der .env:

SAKLAM_AUDIT_LOG=/var/audit/audit.jsonl

Danach schreibt die Bridge pro maskiertem Request einen klartextfreien Datensatz: Zeitstempel, Modell, Anzahl maskierter Entitäten je Typ (PERSON, GERMAN_IBAN, …), Gesamtzahl — verknüpft in einer Hash-Kette (jeder Datensatz sichert den Vorgänger, Manipulation wird erkennbar). Nie im Log: Klartext, Platzhalter-Mapping, Prompt-Inhalte.

Integrität prüfen:

docker compose exec bridge python bridge_audit.py verify /var/audit/audit.jsonl
# ✓ Audit-Kette intakt — N Datensätze, keine Manipulation erkennbar.

Zusammen mit dem Compliance-Paket (Whitepaper, DSFA-Baustein, Verschwiegenheitsverpflichtung) ist das der Nachweis für die Datenschutz-Dokumentation.

Pricing & Lizenz

Mehrere Instanzen oder ein Team? Schreib mir (stefan@saklam.com) — regeln wir individuell.

Datenverarbeitung: Saklam tritt nicht als Auftragsverarbeiter auf, weil Saklam keine personenbezogenen Daten empfängt — die Bridge läuft on-premise in eurer Infrastruktur. Wir liefern eine Site-License-Vereinbarung + technisches Whitepaper für eure Datenschutz-Dokumentation.

Support

Setup-Hilfe: hands-on mit Stefan per Screen-Share, wenn ihr wollt — in 15–20 Min live.