Saklam Bridge — Setup Guide

Drop-in LLM proxy with automatic PII masking. On-premises in your own infra, zero-knowledge towards Saklam, GDPR-compliant — sensitive data stays on-prem.

This guide walks you through installing and running the Saklam Bridge container inside your own network. You keep full data sovereignty: plaintext never leaves your infrastructure unmasked.

Architecture at a glance

App servers / Workstations / CI
  Claude Code · Cursor · Your own apps
    │
    │  ANTHROPIC_BASE_URL=http://bridge.internal.example.com
    │  ANTHROPIC_API_KEY=sk-bridge-<your-master-key>
    ▼
┌─ Saklam Bridge (Docker in your infra) ──────────────────────────┐
│  1. Incoming request with sensitive plaintext                    │
│  2. PII masking (350+ patterns, EU-27 + EEA)                     │
│  3. Forward to Anthropic/OpenAI/Mistral with your API key (BYOK) │
│  4. Unmask the response                                          │
└──────────────────────────────────────────────────────────────────┘
    │
    │  Masked tokens, your API key
    ▼
Anthropic / OpenAI / Mistral

What Saklam sees: no content, ever. The only contact with the Saklam server is the license-token fetch (on startup, then periodically) — nothing but your license key leaves the host, never prompts or customer data. Verifiable: tcpdump on the container shows exactly two destinations — saklam.com (license) and your LLM provider. What the LLM provider sees: masked tokens, never plaintext.

Requirements

Quick install (5 minutes)

# 1. Create a directory
mkdir -p /opt/saklam-bridge && cd /opt/saklam-bridge

# 2. Download docker-compose.yml + .env.example
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. Prepare .env
cp .env.example .env
$EDITOR .env
#   - SAKLAM_LICENSE_KEY=sk-lic-…                          (required — from your activation email/dashboard)
#   - ANTHROPIC_API_KEY=sk-ant-api03-…                     (pay-as-you-go key)
#   - BRIDGE_MASTER_KEY=$(openssl rand -hex 32)            (optional, see auth modes below)

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

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

Auth modes (master key)

Expected response: {"status":"connected"} (HTTP 200).

Tool integration

Claude Code (CLI)

export ANTHROPIC_BASE_URL=http://localhost:4000
export ANTHROPIC_API_KEY=<your BRIDGE_MASTER_KEY from .env>
claude

In the started Claude session, test any prompt containing plaintext PII:

> "Write a payment reminder to Max Mustermann, Musterstr. 12, 80331 Munich, amount due 1,245.50 €."

The Bridge masks Max Mustermann → [PER_a1b2c3d4], Musterstr. 12, 80331 Munich → [LOC_…], sends the masked version to Anthropic, and unmasks the response before returning it.

Cursor

Cursor Settings → Models → API Keys:

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

Your own scripts (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": "Customer: Müller, case 2025/4711, amount 18k €."}]
)

n8n (self-hosted)

Dedicated guide with chat workflow, credential setup and how this relates to n8n's Guardrails node: Saklam Bridge + n8n. Short version: OpenAI credential with Base URL = http://saklam-bridge:4000/v1 — for Claude too (n8n's Anthropic credential has no base-URL field).

LAN access for team workstations

By default the Bridge binds to 127.0.0.1:4000. For network-wide access:

1. In .env: BRIDGE_BIND_ADDR=0.0.0.0
2. Put a reverse proxy (nginx/Caddy/Traefik) with TLS in front — never plain HTTP over the LAN, because sensitive plaintext travels between the workstation and the Bridge.
3. Restart with docker compose up -d.

In-process: pip and npm

Same engine, same placeholder format, same license key, without a container: pip install saklam and npm install saklam run detection and masking inside your own process. The current version is 0.1.1 (10.09.2026).

Do not use 0.1.0: the model it bundled produced no AI detections at all on x86 CPUs without the VNNI instruction set (AMD EPYC/Zen 3–4, Intel before Ice Lake) and silently fell back to the regex layer. 0.1.1 fixes that.

Take the Bridge when the masking has to sit in front of an existing tool (Claude Code, Cursor, n8n, a whole team) or when your stack is neither Python nor Node. Take the package when you are writing the code that talks to the model anyway and would rather not operate a container.

Install

pip install saklam     # Python ≥ 3.10
npm install saklam     # Node ≥ 20
# verified on macOS arm64, Linux amd64/arm64, Windows amd64

Three lines, Python

from saklam import Saklam

pii = Saklam(license_key="sk-lic-…")                     # or 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)   # plaintext back

Three lines, 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 answer = await llm(masked);          // masked text goes out
const plaintext = s.unmask(answer, mapping); // plaintext comes back

Both packages also install a saklam command:

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

Models

Since 0.1.1 the bundled model is U8U8-quantized (87,791,681 bytes), which computes correctly on x86-64 with and without the VNNI instruction set; default is an fp32 build. Verified platforms: macOS arm64, Linux amd64 and arm64, Windows amd64 — proven by the CI matrix on real hosts (GitHub Actions ubuntu/macos/windows, including AMD EPYC runners without VNNI). The download for default needs a valid license token, is checked against checksums pinned in the package, and is moved into the cache atomically.

Self-test at startup: once the AI model is loaded, the package runs one fixed control sentence through detection. If no person comes back, startup fails loudly (SelfTestError in Python, ready() throws in Node, CLI exit code 4) instead of quietly continuing with half the detection. Escape hatch for deliberate special cases: SAKLAM_SKIP_SELFTEST=1.

If no model can be loaded, the packages do not fail: they keep running with the regex layer alone and say so (ready().mode in Node, MaskResult.engine and status() in Python). The regex layer finds structured PII (email, phone, IBAN, tax IDs, ID and card numbers, addresses), but no free names, locations or organizations.

Air-gapped hosts: put a prepared model directory on disk and point SAKLAM_MODEL_DIR at it (model_dir= in Python, modelDir in Node). Nothing is downloaded then.

License and zero-knowledge

• The key is the same sk-lic-… that the Bridge uses, from your activation email or the dashboard. One key covers every form factor: Bridge, pip, npm. Pass it to the constructor or set SAKLAM_LICENSE_KEY.
• It is exchanged once for a short-lived, Ed25519-signed token (POST https://saklam.com/v1/license/token) and cached in ~/.cache/saklam/license/<sha256(key)[:16]>.token. Every later call verifies that token offline against the public key embedded in the package. No phone-home per call. If saklam.com is unreachable, the cached token stays valid until its exp (grace period). pip and npm use the same cache file, so one activation serves both.
• File permissions on macOS and Linux only: there the token file is 0600 inside a 0700 directory. Windows has no such bits — there the file lives in C:\Users\<name>\.cache\saklam\ like any other file in the user profile and inherits its permissions; the recommendation there is profile permissions and BitLocker.
• Only the key leaves the host, plus two operational fields: client (pip or npm) and client_version (the package version). Never text, never detections, never hostnames or usage counters.
• Hard gate: without a valid token, detect, mask and unmask refuse to work (LicenseError, CLI exit code 2). There is no env switch that turns the check off. The keyless 7-day trial of the browser extension does not apply here; these packages want a real key.

Footprint

Loading the model takes 1 to 4 seconds once; after that a short sentence costs roughly 20 to 25 ms (macOS arm64).

The honest price of the fix: on x86 CPUs with VNNI the U8U8 build costs about twice the AI compute time of 0.1.0 (measured on a Xeon: 37 → 72 ms for three texts). On arm64 and on x86 without VNNI the difference is noise. A build that finds nothing at all on part of the fleet is a correctness problem, not a speed problem.

Limits

• The packages run a distilled student model, the Bridge runs its production model. Spans can differ at the edges (the Bridge pulls a salutation into the person span, the package starts at the title). The name itself is masked either way.
• Healthcare texts stay with the Bridge: on clinical material the student models over-mask (drug names as PERSON). No healthcare promise for pip/npm.
• The packages mask in your process, but they do not talk to any provider. Routing, streaming, audit trail and the hybrid setup are Bridge features.

Custom detection

The Bridge ships with 335+ built-in PII patterns. Organization-specific sensitive data — project names, case numbers, domain terms — goes into a ./custom folder next to your docker-compose.yml (uncomment the custom volume in the compose file, restart the container). No code, no training, no image rebuild. Three file kinds:

# custom/labels.yaml
labels:
  medication: MEDICATION
  diagnosis: DIAGNOSIS
ner_threshold: 0.5   # optional; higher = stricter

Everything is additive to the built-in patterns and flows through the same mask/unmask roundtrip and audit trail. Note: with AI entities configured, every request runs the full NER analysis (~1–2 s/request on CPU) — term lists and regex patterns don't have that effect. Test zero-shot labels with real sample texts before production; for enumerable terms, a term list is always the more precise choice.

Medication guard (opt-in, since v0.2.18)

For clinical, practice and discharge-letter texts: the detector occasionally treats drug names (Ramipril, Xarelto, Rocephin …) as persons. The medication guard drops such hits against a gazetteer of 5,746 names (active substances from ATC/Wikidata plus DACH brand names). It detects nothing new and never touches regex hits or salutations ("Frau Dr. med. …").

Enable it in .env, then recreate the container (docker compose up -d):

SAKLAM_DOMAIN_MODULES=klinik,kanzlei,generisch,kern,medneg

The start log then shows Arzneimittel-Wache (medneg): AN (5746 Namen). Without the line, behaviour is unchanged. The whole deterministic domain layer can be switched off with SAKLAM_DOMAIN_LAYER=0.

Updates

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

We recommend a weekly maintenance window or one tied to Saklam release notes. Patch releases are compatible; major versions are announced on the release channel.

Auth note (important before setup)

Saklam Bridge works only with classic API keys (pay-as-you-go), not with subscription OAuth.

Does not work:

• Anthropic Max / Pro / Team OAuth subscription tokens
• ChatGPT Plus / Team web sessions

Supported providers (all BYOK = Bring Your Own Key, Saklam does not act as a reseller):

You pick one or more providers and add the corresponding env variables to .env. Only ANTHROPIC_API_KEY is required (the default provider on first start) — everything else is optional. Config routing happens automatically based on the model-name prefix:

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

Hybrid routing: local model + masked frontier (one gateway)

You don't have to choose between "local model" and "frontier quality" — the Bridge routes both:

• Routine tasks → local model (ollama/…): the request never leaves your host. Summaries, classification, simple drafts.
• Complex tasks → frontier, masked (claude-…, gpt-…): PII is replaced before the request goes out, the response is unmasked locally.

Both paths go through the same masking and the same audit trail — one policy, one record, regardless of model.

Run Ollama inside the same compose stack (optional profile):

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

Call it like any other model, just with the ollama/ prefix (OpenAI wire):

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

If Ollama already runs elsewhere on your network, OLLAMA_API_BASE=http://ollama.internal:11434/v1 is all you need — the profile is just the compose convenience variant. Set expectations honestly: local models on CPU servers are noticeably slower and weaker than frontier — the hybrid pattern deliberately reads "routine locally, complex masked to frontier", not "local does everything".

FAQ

Do the [XXX_yyyyyyyy] placeholders confuse the LLM or make it refuse to answer?

No. The Bridge automatically injects a system instruction into every request (wire-aware for both the Anthropic and OpenAI formats) that explains to the LLM: tokens in the format [PER_a1b2c3d4], [EMA_…], [TEL_…], etc. are masked personal data — copy them verbatim, don't change them, don't invent new ones, and treat them "as if they were the real data."

For normal tasks (summarizing, drafting text, email drafts, analysis) output quality is fully preserved — the placeholder stands semantically in place of the real person/IBAN/address. In the response, the placeholders are automatically unmasked before they reach your app/client: you see the real values, the LLM never does.

Intentional edge case: for tasks that need the exact original value of a masked field — e.g. "verify the checksum of this IBAN" or "how many digits does this phone number have?" — the LLM correctly notes that it only sees a placeholder. Such format/validation checks belong on your side (before or after the Bridge), not inside the masked AI request.

Handy side effect for your own testing: if you ask the LLM whether a masked field is "real," it replies "that's a placeholder" — direct, visible proof that plaintext never reaches the provider.

Troubleshooting

unhealthy in docker ps

docker compose logs bridge

Typical causes:

• First ~10–30s after start: the GLiNER model is loaded from the image into RAM (warmup, no download — the model is in the image) — start_period: 60s in the healthcheck covers this. If it's still unhealthy after 90s: check the logs.
• ANTHROPIC_API_KEY invalid → 401 from Anthropic → the Bridge reports no error at start, but every request fails. Test: curl …/health/liveness (should be 200 even without Anthropic).

401 Unauthorized on Anthropic calls

Your API key is a Max/Team OAuth token instead of a classic sk-ant-… key. See the Auth note above.

Latency

The model is pre-installed in the image and loaded into RAM on container start (no runtime download, air-gap capable). The first PII request is therefore not delayed by a download; requests land at ~<100 ms (CPU).

PII is not being masked

Check the logs: docker compose logs bridge | grep -i 'mask'. Common causes:

• MASK_API_URL is set but the target is unreachable → remove the variable from .env. The default is in-process (no external mask service, no network hop).
• The prompt only contains domain-specific abbreviations that aren't in the 350+ patterns → custom patterns on request.

"Disclosure": the Bridge buffers PII while processing a request

Yes, this is architecturally unavoidable (RAM-only, no disk persistence). A malicious container admin could inspect the process. That's exactly why the Bridge belongs in your infra, not at Saklam.

no valid license / requests rejected with 5xx

The Bridge needs a valid license (active subscription). Check:

• SAKLAM_LICENSE_KEY set correctly in .env (sk-lic-… from your activation email/dashboard)?
• Subscription active? See your dashboard.
• On startup the Bridge automatically fetches a signed license token (only the key leaves the host — never customer data). Logs: docker compose logs bridge | grep -i licen.
• Network is needed once to activate; afterwards a cached token bridges short outages (grace period).

Logs & privacy

• Default logging: structured JSON logs (json-file driver), rotated at 50 MB.
• PII in logs: the Bridge logs request metadata (model, token counts, latency), not prompt plaintext.
• External log forwarding (Splunk, ELK, Loki): standard Docker logging mechanisms.
• Auditability: audit-trail export (CSV) + tamper-evident hashing on request — coming in Phase 2 (see roadmap).

Pricing & license

The same key works in every form factor: Bridge, pip install saklam and npm install saklam (see In-process: pip and npm). We count users, not containers, so the number of instances is unlimited in every tier.

A team, or more than one user? Write me (stefan@saklam.com) — we'll sort it out individually.

Data processing: Saklam does not act as a data processor, because Saklam never receives personal data — the Bridge runs on-premises in your infrastructure. We provide a site-license agreement + a technical whitepaper for your data-protection documentation.

Support

Setup help: hands-on with Stefan over a screen share if you want it — you're live in 15–20 min.