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 (350+ Patterns, EU-27 + EWR)                  │
│  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: keine Inhalte, niemals. Einziger Kontakt zum Saklam-Server ist der Lizenz-Token-Abruf (beim Start und danach periodisch) — dabei geht ausschließlich euer Lizenz-Key raus, nie Prompts oder Kundendaten. Nachmessbar: tcpdump am Container zeigt genau zwei Ziele — saklam.com (Lizenz) und euren LLM-Provider. 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.

Im Prozess: pip und npm

Gleiche Engine, gleiches Platzhalter-Format, gleicher Lizenzschlüssel, ohne Container: pip install saklam und npm install saklam erkennen und maskieren im eigenen Prozess. Aktuelle Version ist 0.1.1 (10.09.2026).

0.1.0 bitte nicht verwenden: die dort gebündelte Modell-Fassung lieferte auf x86-Prozessoren ohne VNNI-Befehlssatz (AMD EPYC/Zen 3–4, Intel vor Ice Lake) keine KI-Treffer und fiel dabei still auf die Regex-Schicht zurück. 0.1.1 behebt das.

Die Bridge nehmt ihr, wenn die Maskierung vor einem fertigen Werkzeug sitzen muss (Claude Code, Cursor, n8n, ein ganzes Team) oder wenn der Stack weder Python noch Node ist. Das Paket nehmt ihr, wenn ihr den Code, der mit dem Modell spricht, ohnehin selbst schreibt und keinen Container betreiben wollt.

Installation

pip install saklam     # Python ≥ 3.10
npm install saklam     # Node ≥ 20
# geprüft auf macOS arm64, Linux amd64/arm64, Windows amd64

Drei Zeilen, Python

from saklam import Saklam

pii = Saklam(license_key="sk-lic-…")                     # oder SAKLAM_LICENSE_KEY
r = pii.mask("Philip Müller aus Zürich, philip@example.org")
r.masked        # '[PER_1864ad4c] aus [LOC_2350dca1], [EMA_c85d5952]'
pii.unmask(r.masked, r.mapping)   # Klartext zurück

Drei Zeilen, Node

import { Saklam } from 'saklam';

const s = new Saklam({ licenseKey: process.env.SAKLAM_LICENSE_KEY });
await s.ready();

const { masked, mapping } = await s.mask(
  'Philip Müller aus Zürich, philip@example.org'
);
// masked  → '[PER_651b852a] aus [LOC_ae6c7a68], [EMA_203cfcd0]'

const antwort = await llm(masked);           // maskiert raus
const klartext = s.unmask(antwort, mapping); // Klartext zurück

Beide Pakete installieren zusätzlich das Kommando saklam:

saklam mask   "Philip Müller, philip@example.org"
saklam detect "…" --json
saklam license

Modelle

Das gebündelte Modell ist seit 0.1.1 U8U8-quantisiert (87.791.681 Byte) und rechnet damit auf x86-64 mit und ohne VNNI-Befehlssatz korrekt; default ist eine fp32-Fassung. Geprüfte Plattformen: macOS arm64, Linux amd64 und arm64, Windows amd64 — belegt durch die CI-Matrix auf echten Wirten (GitHub Actions ubuntu/macos/windows, darunter AMD-EPYC-Runner ohne VNNI). Der Download für default braucht ein gültiges Lizenz-Token, wird gegen im Paket gepinnte Prüfsummen gehalten und landet atomisch im Cache.

Selbsttest beim Start: sobald das KI-Modell geladen ist, schickt das Paket einmal einen festen Kontrollsatz durch die Erkennung. Kommt dabei keine Person zurück, bricht der Start laut ab (SelfTestError in Python, ready() wirft in Node, CLI-Exit-Code 4), statt still mit halbierter Erkennung weiterzulaufen. Notausgang für bewusste Sonderfälle: SAKLAM_SKIP_SELFTEST=1.

Ist kein Modell ladbar, brechen die Pakete nicht ab: sie laufen mit der Regex-Schicht allein weiter und sagen es (ready().mode in Node, MaskResult.engine und status() in Python). Die Regex-Schicht findet strukturierte PII (E-Mail, Telefon, IBAN, Steuer-ID, Ausweis- und Kreditkartennummern, Adressen), aber keine freien Namen, Orte oder Organisationen.

Abgeschottete Hosts: ein vorbereitetes Modell-Verzeichnis auf die Platte legen und SAKLAM_MODEL_DIR daraufzeigen lassen (model_dir= in Python, modelDir in Node). Dann wird nichts geladen.

Lizenz und Zero-Knowledge

• Der Schlüssel ist derselbe sk-lic-… wie bei der Bridge, aus der Aktivierungs-Mail oder dem Dashboard. Ein Schlüssel deckt alle Formfaktoren ab: Bridge, pip, npm. Entweder an den Konstruktor übergeben oder SAKLAM_LICENSE_KEY setzen.
• Er wird einmal gegen ein kurzlebiges, Ed25519-signiertes Token getauscht (POST https://saklam.com/v1/license/token) und in ~/.cache/saklam/license/<sha256(key)[:16]>.token abgelegt. Jeder weitere Aufruf prüft dieses Token offline gegen den im Paket eingebetteten Public Key. Kein Phone-Home pro Aufruf. Ist saklam.com nicht erreichbar, gilt das gecachte Token bis zu seinem exp (Gnadenfrist). pip und npm nutzen dieselbe Cache-Datei: eine Aktivierung bedient beide.
• Dateirechte nur unter macOS und Linux: dort liegt die Token-Datei mit 0600 in einem Verzeichnis mit 0700. Windows kennt diese Bits nicht — dort liegt sie unter C:\Users\<name>\.cache\saklam\ wie jede andere Datei im Nutzerprofil und erbt dessen Rechte; Empfehlung entsprechend: Profilrechte und BitLocker.
• Es verlässt nur der Schlüssel den Host, dazu zwei Betriebsangaben: client (pip oder npm) und client_version (die Paketversion). Nie Text, nie Erkennungsergebnisse, keine Hostnamen, keine Nutzungszahlen.
• Hard-Gate: ohne gültiges Token verweigern detect, mask und unmask die Arbeit (LicenseError, CLI-Exit-Code 2). Es gibt keinen Env-Schalter, der die Prüfung abschaltet. Der keylose 7-Tage-Trial der Browser-Erweiterung gilt hier nicht; diese Pakete wollen einen echten Schlüssel.

Platzbedarf

Das Modell zu laden dauert einmalig 1 bis 4 Sekunden, danach kostet ein kurzer Satz rund 20 bis 25 ms (macOS arm64).

Ehrlicher Preis des Fixes: auf x86-Prozessoren mit VNNI kostet die U8U8-Fassung rund die doppelte KI-Rechenzeit gegenüber 0.1.0 (gemessen auf einem Xeon: 37 → 72 ms für drei Texte). Auf arm64 und auf x86 ohne VNNI ist der Unterschied Rauschen. Eine Fassung, die auf einem Teil der Rechner gar nichts findet, ist kein Geschwindigkeits-, sondern ein Korrektheitsproblem.

Grenzen

• Die Pakete fahren ein destilliertes Studenten-Modell, die Bridge ihr Produktionsmodell. Spans können an den Rändern abweichen (die Bridge zieht die Anrede in den Personen-Span, das Paket beginnt beim Titel). Der Name selbst ist in beiden Fällen maskiert.
• Healthcare-Texte bleiben bei der Bridge: auf klinischem Material übermaskieren die Studenten-Modelle (Präparatenamen als PERSON). Für pip/npm gibt es kein Healthcare-Versprechen.
• Die Pakete maskieren in eurem Prozess, sie sprechen aber mit keinem Provider. Routing, Streaming, Audit-Trail und das Hybrid-Setup sind Bridge-Funktionen.

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.

Arzneimittel-Wache (Opt-in, ab v0.2.18)

Für Klinik-, Praxis- und Arztbrieftexte: Die Erkennung hält Präparatenamen (Ramipril, Xarelto, Rocephin …) sonst gelegentlich für Personen. Die Arzneimittel-Wache verwirft solche Treffer anhand eines Gazetteers mit 5.746 Namen (Wirkstoffe aus ATC/Wikidata plus DACH-Handelsnamen). Sie erkennt nichts Neues und fasst weder Regex-Treffer noch Anreden („Frau Dr. med. …") an.

Aktivieren in der .env, dann Container neu erzeugen (docker compose up -d):

SAKLAM_DOMAIN_MODULES=klinik,kanzlei,generisch,kern,medneg

Im Start-Log erscheint dann Arzneimittel-Wache (medneg): AN (5746 Namen). Ohne die Zeile bleibt das Verhalten unverändert. Die ganze deterministische Domänen-Schicht lässt sich mit SAKLAM_DOMAIN_LAYER=0 abschalten.

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 350+ 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

Derselbe Schlüssel gilt in jedem Formfaktor: Bridge, pip install saklam und npm install saklam (siehe Im Prozess: pip und npm). Gezählt werden Nutzer, nicht Container: die Zahl der Instanzen ist in jeder Stufe unbegrenzt.

Ein Team oder mehr als ein Nutzer? 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.