SDK download & install

CloakAPI distributes its SDKs, the MCP server and the conformance badge as downloadable artifacts hosted on the CloakAPI site — not through public code registries. This is consistent with CloakAPI’s local-first architecture and means you can build on CloakAPI without an npm / PyPI / crates.io / Packagist / RubyGems / NuGet account.

Need the browser extension or desktop app instead of an SDK? Sideload Chrome 0.1.23 from Downloads (install steps). Linux desktop 1.1.0 is on the same page (Desktop); macOS is still coming.

You may not need an SDK at all

Every SDK is a thin convenience wrapper over the REST API. You can call https://api.cloakapi.io directly with your cloak_ key — see Chat completions. The SDKs add client-side tokenisation helpers, receipt verification and the gateway lock.

Need a key first? No browser required

Get a free-tier cloak_ key from the command line — no portal, no GUI:

curl -sS -X POST https://api.cloakapi.io/api/v1/self-service/key \
  -H 'Content-Type: application/json' -d '{}'
export CLOAKAPI_API_KEY=cloak_…   # the SDKs and MCP server read this env var

On-device tokenisation works immediately; LLM relay is balance-gated. Full details: Authentication → Get an API key (headless / no browser).

Writing your own relay? residualRawPII() is mandatory

The browser SDK’s createFailClosedRelay() runs a residual raw-PII scan on the final egress bytes and refuses to send if any raw value survived tokenisation. If you hand-roll a relay (your own fetch, your own /api/chat proxy route, your own streaming transport), you opt out of that backstop — and nothing will tell you. You MUST run the scan yourself:

import { residualRawPII } from "@cloakapi/sdk/browser";

const bytes = JSON.stringify(payload);        // the EXACT bytes you will POST
if (residualRawPII(bytes, reviewedSpans).length > 0) {
  throw new Error("a sensitive value survived the on-device cloak; nothing was sent");
}
await fetch(endpoint, { method: "POST", body: bytes });

Scan the final serialised body (not one message’s content, not the pre-splice text), and refuse to send — a console.warn is not a privacy control. Full contract: Custom relays.

Read the manifest — some versioned filenames 404

The exact filenames/versions ship in manifest.json. A hard-coded curl -O of a versioned filename may 404. Pull current URLs from the manifest; do not assume a language listed in this page is in the manifest.

Not currently served (HTTP 404, measured 2026-08-20; bodies never git-tracked): the Python 0.4.0 wheels, sdist and src-zip, and cloakapi-sdk-typescript-1.2.2-src.zip. Sidecar .sha256 files for the Python four remain; the bodies do not. Install those languages from the source tree (sdk/python, sdk/typescript) until a file is listed in the manifest.

⛔ CORRECTION BESIDE THE PARAGRAPH ABOVE — 2026-08-24 (sak 2129). The 2026-08-20 measurement is not rewritten (Q64); it was true on its date. cloakapi-sdk-typescript-1.2.2-src.zip did not stay absent. Measured from the wire 2026-08-24: it answered HTTP 200, application/zip, 4 187 692 B — it had been republished at some point after 2026-08-20. It is now withdrawn on purpose and answers HTTP 410 Gone, because the engine bundled in it (cloakapi_tokeniser_wasm_bg.wasm, sha256 5590766a…) uses an ASCII-only class for personal names. It is named under the top-level withdrawn key of manifest.json, and there is no longer a typescript entry in that manifest. 410, not 404: the file was published and offered, so a stale link deserves a truthful answer rather than “you mistyped”. The Python 0.4.0 statement above is a different matter and is not re-measured here.

Where to download

All artifacts live under app.cloakapi.io/downloads/sdks/. Directory listing is off, so there is no browsable index page — use the machine-readable manifest.json, which lists every file, URL and sha256. The same files are linked from the portal Developers page. A machine-readable index with a sha256 for every file is at /downloads/sdks/manifest.json.

For each package there is a native installable (where the toolchain produces one cleanly) and a universal source .zip fallback. Verify any download against the sha256 in manifest.json:

sha256sum ./cloakapi-go-1.2.0-src.zip
# compare against the value in manifest.json — only hash a file you actually downloaded

Per-language install

TypeScript / Node.js

The TypeScript source zip /downloads/sdks/typescript/cloakapi-sdk-typescript-1.2.2-src.zip is withdrawn and answers HTTP 410 Gone (measured from the wire 2026-08-24). Do not curl -O that URL, and do not build from a copy you already have: the engine it bundles (sha256 5590766a…) uses an ASCII-only class for personal names. ⛔ The line that stood here said “HTTP 404, measured 2026-08-20”. That measurement is left standing rather than rewritten (Q64) — it was true on its date, and the file was republished and served 200 before it was withdrawn. It is not listed in manifest.json. Install from the source tree:

cd sdk/typescript && npm install && npm run build

Reference the built directory with npm install ./sdk/typescript.

Custom relays — the mandatory residual scan

The supported browser path is createFailClosedRelay(), which performs the whole Level-1 round-trip (tokenise/splice → cloak-disclosure → pre-tokenised MAC → blind relay → on-device detokenise) and, on the final egress bytes, runs residualRawPII() plus a raw-card backstop. If either finds something, the relay throws and nothing is sent.

import { createFailClosedRelay } from "@cloakapi/sdk/browser";

const relay = createFailClosedRelay({
  baseUrl: "https://api.cloakapi.io",
  apiKey: process.env.CLOAKAPI_API_KEY,
  engine,
  reviewedSpans, // the ONE reviewed detection pass
});
const reply = await relay.messages.create({ model: "claude-sonnet-4-6", messages });

Many real apps cannot use it verbatim — they stream SSE, or they POST to their own server route so the browser never holds the API key. That is fine, but the residual scan is not optional. Re-implement it explicitly, immediately before the send:

import { residualRawPII } from "@cloakapi/sdk/browser";

// `reviewedSpans`: the spans from the SAME detection pass whose surrogates you
// spliced — each carries its raw `original` and the reviewed `surrogate`.
const bytes = JSON.stringify({ model, messages });   // EXACTLY what you will POST

const residual = residualRawPII(bytes, reviewedSpans);
if (residual.length > 0) {
  // FAIL CLOSED — refuse the send, tell the user honestly.
  return { ok: false, reason: "A sensitive value survived the on-device cloak, so nothing was sent." };
}

const resp = await fetch("/api/chat", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: bytes,
});

Why this is the last line of defence: detection can miss a value, a value-based splice can fail to match after the text was re-framed, and a stale or half-loaded engine can leave a raw card in place. Every one of those failures is invisible at the UI layer and shows up only in the bytes that leave the device.

• Scan the final serialised body, not one message’s content and not the pre-splice text — a leak arriving via the system prompt, an attachment or a tool-call argument is only visible there.
• Refuse to send; do not warn and continue.
• Surrogates are masked out first, so a raw value that appears only inside a surrogate you just wrote is never a false positive.
• Pass the spans from the same reviewed pass — scanning against an empty span list proves nothing.

Python

The Python SDK is built as one wheel per platform, each carrying the native detection engine for exactly that platform. Those files are not currently served (HTTP 404, measured 2026-08-20, for cloakapi-0.4.0-py3-none-manylinux_2_39_{x86_64,aarch64}.whl, cloakapi-0.4.0.tar.gz and cloakapi-python-0.4.0-src.zip). They have never been git-tracked. Do not curl -O those URLs. Install from the source tree:

pip install -e sdk/python

pip refuses a wheel that is not for your platform — that is deliberate. On a platform with no wheel (macOS, Windows, musl/Alpine) a source install contains no engine; the first tokenisation raises ReducedCoverageError rather than silently running the reduced pure-Python lane (17 of 140 PII types). If you accept reduced coverage with open eyes, opt in explicitly with CLOAKAPI_ALLOW_REDUCED=1 or allow_reduced=True.

Current filenames that are served, and their sha256, live in /downloads/sdks/manifest.json. Python is not among them until a body is listed there.

Withdrawn: cloakapi-0.3.1-py3-none-any.whl and every earlier py3-none-any wheel are withdrawn and removed. They installed cleanly on macOS, Windows and Linux/ARM, could not load the engine there, and ran the reduced lane without saying so.

Go

Go is source-based — there is no binary artifact. Download the source zip and use a local module replace directive:

curl -O https://app.cloakapi.io/downloads/sdks/go/cloakapi-go-1.2.0-src.zip
unzip cloakapi-go-1.2.0-src.zip           # yields ./go

go.mod

require github.com/cloakapi/cloakapi-go v1.2.0
replace github.com/cloakapi/cloakapi-go => ./go

Then go mod tidy && go build. Vendoring the ./go directory works too.

Rust

The crate has a workspace path dependency, so it ships as a source zip and is used as a path dependency rather than a .crate:

curl -O https://app.cloakapi.io/downloads/sdks/rust/cloakapi-rust-1.2.0-src.zip
unzip cloakapi-rust-1.2.0-src.zip          # yields ./rust

Cargo.toml

[dependencies]
cloakapi = { path = "./rust" }

Java

Java ships as a source zip with the bundled build.gradle.kts. It depends on Jackson (databind) and JNA; build it with Gradle in your own environment:

curl -O https://app.cloakapi.io/downloads/sdks/java/cloakapi-java-1.2.0-src.zip
unzip cloakapi-java-1.2.0-src.zip          # yields ./java
cd java && ./gradlew build                 # produces the jar under build/libs/

(No pre-built jar is shipped because the box that packages the SDKs has no Gradle/Maven to resolve those third-party dependencies — build it where your toolchain lives.)

.NET

A .nupkg is shipped. Add the folder you downloaded it to as a local NuGet source:

curl -O https://app.cloakapi.io/downloads/sdks/dotnet/CloakAPI.Sdk.1.2.0.nupkg
dotnet add package CloakAPI.Sdk --source $(pwd)

Source fallback: cloakapi-dotnet-1.2.0-src.zip → unzip, then dotnet add reference dotnet/src/CloakAPI.Sdk/CloakAPI.Sdk.csproj.

PHP

Install via a Composer path repository:

curl -O https://app.cloakapi.io/downloads/sdks/php/cloakapi-php-1.3.1-src.zip
unzip cloakapi-php-1.3.1-src.zip           # yields ./php

{
  "repositories": [{ "type": "path", "url": "./php" }],
  "require": { "cloakapi/cloakapi-php": "*" }
}

Then composer install.

Ruby

curl -O https://app.cloakapi.io/downloads/sdks/ruby/cloakapi-1.3.0.gem
gem install ./cloakapi-1.3.0.gem

Source fallback: cloakapi-ruby-1.3.0-src.zip → unzip, then cd ruby && bundle install && gem build cloakapi.gemspec.

File & image tokenisation (on-device)

Every SDK can tokenise files and images entirely on your machine before anything egresses. A PDF, DOCX, XLSX, PPTX, CSV or HTML file is extracted; a PNG/JPEG/WebP/GIF/ BMP/TIFF image is OCR’d — all on-device, through the same shared engine (libcloak_engine) the desktop app and drop-in proxy use. Only the resulting tokenised text (<<CLOAK:…>> surrogates) is ever returned for you to relay; the gateway never receives the raw file or image bytes. The local token↔value map stays on your machine so the model’s reply is detokenised locally.

The method is fail-closed: if the on-device engine is not available it raises an error rather than falling back to uploading the raw file.

// TypeScript
const { text, tokenMap, meta } = client.tokenizeFile(bytes, { mime: 'image/png', filename: 'intake.png' });
// `text` is tokenised — feed it into messages.create / chat.completions.create as usual;
// the reply is auto-detokenised because tokenizeFile merged the map into the session.

# Python
res = client.tokenize_file(data, mime="application/pdf", filename="contract.pdf")
# res["text"] is tokenised; res["token_map"] is the local map. Send res["text"] via messages/chat.

The equivalent method exists in every SDK (Go TokenizeFile, Rust tokenize_file, Java/.NET tokenizeFile, PHP tokenizeFile, Ruby tokenize_file) and as the MCP tokenise_file / tokenise_image tools. Images/PDFs/office docs all go through the one method — the engine decides by MIME.

Requires the local engine

On-device file/image tokenisation needs the shared engine binary (libcloak_engine). The Python wheel/source bundles it; other SDKs load it from CLOAKAPI_ENGINE_LIB → a bundled _lib/ → an in-repo target/release/ build. Point CLOAKAPI_ENGINE_LIB at the engine if it is installed elsewhere. Image OCR uses a local OCR engine (RapidOCR, falling back to the tesseract binary).

Name detection: baseline list + the recommended neural model

CloakAPI’s structured detectors (email, phone, card, government IDs, …) are exact and always on. Person names are detected in two layers:

• Built-in name list (baseline, always on, free). The engine ships an embedded gazetteer of ~1,700 common given names with strict precision guards. On our benchmark it catches 52.2% of person names at 84.8% precision (it does not mis-tokenise capitalised non-names like “Monday”, “London” or “United Nations”). No model, no network, no download.
• Neural name model (recommended for best coverage). Loading the optional on-device NER model raises name recall to 95.3% (precision 88.9%), including many non-Latin and uncommon names the list misses. We recommend enabling it for any workload where names matter. It runs fully on-device (ONNX, ~135 MB, download-on-first- use); enable it by using an engine built with the ner_onnx feature / with the NER model present, and point CLOAKAPI_ENGINE_LIB at that engine.

Honest limits — tokenised is not “anonymous”

The baseline list is a floor, not a guarantee, and even the neural model is 95.3% name recall — some names will be missed. Tokenisation reduces exposure; it is not de-identification, not HIPAA Safe Harbor, and does not make data “PHI-free” or “anonymous”. Evaluate suitability for your use case (with counsel where regulated data is involved).

MCP server

The @cloakapi/mcp-server exposes CloakAPI’s tool surface to any MCP host (Claude Desktop, Cursor, agent frameworks). Install the packed tarball:

curl -O https://app.cloakapi.io/downloads/sdks/mcp/cloakapi-mcp-server-0.4.0.tgz
npm install -g ./cloakapi-mcp-server-0.4.0.tgz

Then reference it in claude_desktop_config.json (point command at the installed cloakapi-mcp-server binary, supply your CLOAKAPI_API_KEY). See Choose your integration for the config block. A source zip (cloakapi-mcp-server-0.4.0-src.zip) is also available.

Conformance badge

@cloakapi/conformance checks the receipts your integration emits so a build’s correctness is falsifiable before you display the “Verified by CloakAPI” badge:

curl -O https://app.cloakapi.io/downloads/sdks/conformance/cloakapi-conformance-0.1.0.tgz
npm install ./cloakapi-conformance-0.1.0.tgz

See Verify + get the badge for the governance rules.

Starter-kit

The forkable private-AI chat starter-kit (Apache-2.0) is intended to be distributed the same way — a self-contained tarball that vendors the WASM engine, the shared receipt + patterns packages and the TypeScript SDK, so npm install needs no registry.

Not published as a download yet

/downloads/sdks/starter-kit/ is empty. Any curl for cloakapi-starter-kit-*.tgz returns 404. The packaged, self-contained tarball is still being cut; it is not listed in manifest.json either. Use the SDK downloads above until it appears there.

See the quickstart in Choose your integration → Starter-kit.

The kit relays through its own /api/chat route rather than createFailClosedRelay(), so it ships the residual scan explicitly: src/lib/residual.ts (residualRawPII) is called in src/lib/relay.ts on the serialised body immediately before fetch, and a hit aborts the send. If you fork the kit and change the transport, keep that call — see Custom relays.

Veil review layer (review-core, review-ui, veil-tokens)

The pre-send cloaking review experience — “see exactly what leaves your machine, decide per span, then send” — is packaged as three small Apache-2.0 packages so an external app can offer the same review UX CloakAPI’s own surfaces use:

• @cloakapi/review-core — the framework-agnostic review state machine over @cloakapi/sdk’s browser lane: a source-segmented review manifest, per-source / per-span keep/reveal decisions, the “exact assembled prompt” projection, and a fail-closed confirm() that returns { body, map, receipt } and never egresses unsafe. Peer-depends on @cloakapi/sdk.
• @cloakapi/review-ui — pure view + event wiring over review-core: a <cloak-review> / <cloak-receipt> custom element plus React and Svelte reference components and the review-ui.css class contract. Ships as TypeScript source (compiled by your bundler — Vite, esbuild, webpack with a TS loader); React, Svelte and @cloakapi/sdk are optional peers, review-core + veil-tokens are required peers.
• @cloakapi/veil-tokens — the semantic colour-token layer (--veil-*) that keeps safety-critical states consistent on every surface: green = cloaked, amber = leaving in the clear, pink = secret/can’t-reveal, purple = your action. Plain CSS custom properties + a tiny JS manifest; usable with no build step at all.

curl -O https://app.cloakapi.io/downloads/sdks/review-core/cloakapi-review-core-0.1.0.tgz
curl -O https://app.cloakapi.io/downloads/sdks/review-ui/cloakapi-review-ui-0.1.1.tgz
curl -O https://app.cloakapi.io/downloads/sdks/veil-tokens/cloakapi-veil-tokens-0.1.0.tgz
# TypeScript src zip is not currently served (HTTP 404, measured 2026-08-20).
# CORRECTION BESIDE, 2026-08-25: that URL answers HTTP 410 Gone, not 404.
#   Measured from the wire (positive control 200 on manifest.json, negative
#   control 404 on a nonexistent name, so the check distinguishes the two).
#   410 is not a milder 404 here: the file WAS published, and the engine it
#   bundles (sha256 5590766a...) uses an ASCII-only class for personal names.
#   So do not reuse a copy you already downloaded either.
# Build from the source tree: cd sdk/typescript && npm install && npm run build

npm install ./sdk/typescript ./cloakapi-veil-tokens-0.1.0.tgz \
            ./cloakapi-review-core-0.1.0.tgz ./cloakapi-review-ui-0.1.1.tgz

import { createCloakReview } from '@cloakapi/review-core';
import '@cloakapi/veil-tokens/tokens.css';
import '@cloakapi/review-ui/review-ui.css';
// then mount <cloak-review> (element), <CloakReview> (react/) or (svelte/)

Only veil-tokens and review-core are needed if you build your own review UI — review-ui is the reference implementation. All three are listed with sha256 hashes in manifest.json.

Checking the SDK actually cloaks before egress

Do not take it on faith that a build tokenises before it sends — measure it. The same wire-level method we use on our own products, the results across every surface (SDK, local proxy, MCP server, gateway, products), the documented limits, and a defect the method caught are all written up in Verification & evidence.

Optional: public registries later

Publishing these packages to npm / PyPI / crates.io / etc. remains an optional future marketing/discoverability step. It is not required to build on CloakAPI today — the downloads above, plus the REST API, are the supported launch path.