Architecture

Ki! is a multi-process sovereign proxy. Three layers work together; each has a clearly bounded responsibility. Understanding the architecture helps you audit what Ki! does — and verify that sensitive data cannot leave via any code path.

The Three Layers

┌──────────────────────────────────────────────────────────┐
│  Layer 1 — Frontend (React 19 + Vite)                    │
│  Chat UI, Vault viewer, Egress Log, Settings             │
└─────────────────────────┬────────────────────────────────┘
                          │  Tauri JSON-RPC commands
┌─────────────────────────▼────────────────────────────────┐
│  Layer 2 — Orchestrator (Rust / Tauri v2)                │
│  State, OS Keychain, SQLite vault, sidecar lifecycle     │
│  Custom rules engine, allowlist protection               │
└──────────┬──────────────────────────────┬────────────────┘
           │ HTTP  POST /api/refine        │ HTTP  POST /slm
┌──────────▼──────────┐       ┌───────────▼────────────────┐
│  Layer 3a           │       │  Layer 3b                  │
│  Ocultar Sidecar    │       │  SLM Engine (Sovereign)    │
│  (Go binary)        │       │  Local NER model           │
│  Tier 0–1.5 NER     │       │  Tier 2 AI scan            │
└─────────────────────┘       └────────────────────────────┘

---

Request Lifecycle

When you send a message, the Rust command cmd_send_message runs this pipeline:

Stage 1 — Custom Rules

Your user-defined regex patterns are applied first. Matches produce [CUSTOM_xxxxxxxx] tokens. Rule names are recorded in the audit log for compliance evidence.

Stage 2 — Allowlist Protection

Terms on your Never-Mask List are replaced with opaque internal sentinels (__KII_{tag}_{idx}__) so the Ocultar sidecar never processes them. This prevents Ki! from accidentally masking a term you’ve explicitly whitelisted.

Stage 3 — Ocultar NER (Go Sidecar)

The protected text is posted to the local Go sidecar at POST /api/refine. The sidecar runs the full six-tier detection pipeline and returns:

• masked_prompt — text with PII replaced by tokens
• pii_report — list of detected entity types and positions

The sidecar runs on a random ephemeral port assigned at launch. It listens only on 127.0.0.1 — no LAN or external network access.

Stage 4 — Allowlist Restore

Internal sentinels are replaced with the original protected terms.

Vault Write

The Rust layer writes every token → original value mapping to vault.db (SQLite, WAL mode). Simultaneously, a signed chat_egress entry is appended to audit.log.

Egress

The fully masked prompt is sent to your configured LLM provider over HTTPS. This is the only outbound network call Ki! makes per message — and it contains no original PII.

Ingress (Streaming Unmask)

As the LLM streams chunks back (SSE), the Rust backend performs sliding-window regex replacement: [PERSON_a1b2] → Alice Johnson. The frontend never sees raw tokens.

---

Persistence

Store	Format	Contents
vault.db	SQLite (WAL)	Token mappings, chat history, egress log
audit.log	NDJSON (append-only)	Ed25519-signed compliance trail

The audit log is never mutated — only appended. Each entry is signed with your policy key (Ed25519). The hash chain means any tampering is detectable.

Action types in the audit log:

Action	Written by
vaulted, matched, revealed, blocked	Ocultar sidecar
chat_egress, document_scrub, batch_scrub	Ki! Rust layer

---

Sidecar Security

Both sidecars run as child processes with restricted privileges:

• Port: Random ephemeral (49152–65535), bound to 127.0.0.1 only
• Keys: OCU_MASTER_KEY and OCU_SALT passed via environment variables — never written to disk in plaintext
• Teardown: Both processes are terminated on app exit via explicit stop commands
• Health check: Ki! polls /api/health before processing any prompt. Failure → prompt blocked

---

Keychain & Secret Storage

Your LLM provider API key is stored in your OS native keychain:

• macOS — Keychain Access
• Windows — Windows Credential Manager
• Linux — libsecret / Secret Service API (GNOME Keyring, KWallet)

The key is never stored in a config file, environment variable, or the SQLite database.

---

Why This Architecture Guarantees Zero Egress

The design is not a policy promise — it is an architectural constraint:

1. Detection is local: The Go sidecar and SLM run on your device. No prompt text is sent to a detection cloud.
2. Only the masked prompt is sent: The Rust orchestrator never forwards the pre-mask text to any provider.
3. Fail-closed: Every error path blocks the outbound call. There is no fallback to sending unmasked text.
4. Auditable: The Ed25519-signed audit log provides cryptographic proof of what was and was not sent. A DPO or HIPAA auditor can verify the claim without trusting Ki!‘s marketing.

The parallel to network security: this is not a firewall rule (a policy that could be misconfigured) — it is a physically separate path (the only path to the network goes through the masker).

---

For Teams & Enterprise — Sombra Gateway

Ki! Desktop solves the problem for individual developers. When your entire organisation needs zero-egress enforcement — across every API call, every service, every team — the answer is Sombra Gateway.

┌─────────────────────────────────────────────────────────┐
│  Your services / SaaS apps / internal tools             │
│  (OpenAI SDK, LangChain, custom code)                   │
└────────────────────┬────────────────────────────────────┘
                     │  POST /v1/chat/completions
                     │  (OpenAI-compatible endpoint)
┌────────────────────▼────────────────────────────────────┐
│  Sombra Gateway (on-premise or private cloud)           │
│  ┌───────────────────────────────────────────────────┐  │
│  │  Ocultar Refinery (full 8-tier PII detection)     │  │
│  │  Policy engine   │  JWT auth   │  Audit log       │  │
│  └───────────────────────────────────────────────────┘  │
│  Multi-model router: OpenAI · Claude · Gemini · Mistral │
│  Connectors: SharePoint OAuth2, Slack, S3               │
└────────────────────┬────────────────────────────────────┘
                     │  Only masked prompt reaches cloud
                     ▼
             Cloud LLM provider

One configuration change, zero-egress for your entire organisation:

# Before
OPENAI_BASE_URL=https://api.openai.com/v1

# After — all prompts scrubbed before leaving your network
OPENAI_BASE_URL=https://sombra.your-org.com/v1

Sombra inherits every detection capability in the Ki! architecture — same Ocultar Refinery, same token format, same audit log schema — with the addition of:

• Organisation-wide policy definitions (which PII types to mask, which to block)
• JWT-based team authentication and per-team audit trails
• File connectors (SharePoint, Slack) that ingest documents into the Refinery before tokenisation
• Dashboard for DPO/CISO review of masking patterns and egress activity

Learn more about Sombra at ocultar.dev · Contact for a pilot