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.

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.

Version numbers below are illustrative — read the manifest for the live version

The exact filenames/versions ship in manifest.json and are bumped on every release, so a hard-coded curl -O …-0.1.0-… may 404. Pull the current version from the manifest instead, e.g.:

# Python wheel URL, always current:
curl -sS https://app.cloakapi.io/downloads/sdks/manifest.json \
  | python3 -c 'import sys,json; m=json.load(sys.stdin); print(next(a["url"] for a in m["languages"]["python"] if a["file"].endswith(".whl")))'

Where to download

All artifacts live under app.cloakapi.io/downloads/sdks/, also 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-0.1.0-py3-none-any.whl
# compare against the value in manifest.json

Per-language install

TypeScript / Node.js

curl -O https://app.cloakapi.io/downloads/sdks/typescript/cloakapi-sdk-1.0.0.tgz
npm install ./cloakapi-sdk-1.0.0.tgz

Source fallback: cloakapi-sdk-typescript-1.0.0-src.zip → unzip, then cd typescript && npm install && npm run build.

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

curl -O https://app.cloakapi.io/downloads/sdks/python/cloakapi-0.1.0-py3-none-any.whl
pip install ./cloakapi-0.1.0-py3-none-any.whl

An sdist (cloakapi-0.1.0.tar.gz) and a source zip (cloakapi-python-0.1.0-src.zip, includes the bundled native engine) are also available; pip install ./cloakapi-0.1.0.tar.gz works the same way.

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.0.0-src.zip
unzip cloakapi-go-1.0.0-src.zip           # yields ./go

go.mod

require github.com/cloakapi/cloakapi-go v1.0.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.0.0-src.zip
unzip cloakapi-rust-1.0.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.0.0-src.zip
unzip cloakapi-java-1.0.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.0.0.nupkg
dotnet add package CloakAPI.Sdk --source $(pwd)

Source fallback: cloakapi-dotnet-1.0.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.0.0-src.zip
unzip cloakapi-php-1.0.0-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.0.0.gem
gem install ./cloakapi-1.0.0.gem

Source fallback: cloakapi-ruby-1.0.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 ~40% of common person names at ~100% 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 ~96.5% (still ~100% precision), 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 ~96.5% 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.2.0.tgz
npm install -g ./cloakapi-mcp-server-0.2.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.2.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 distributed the same way — a self-contained tarball that vendors the WASM engine, the shared receipt + patterns packages and the @cloakapi/sdk tgz, so npm install needs no registry:

curl -LO https://app.cloakapi.io/downloads/sdks/starter-kit/cloakapi-starter-kit-1.0.0.tgz
tar xzf cloakapi-starter-kit-1.0.0.tgz && cd cloakapi-starter-kit
npm install

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.0.tgz
curl -O https://app.cloakapi.io/downloads/sdks/veil-tokens/cloakapi-veil-tokens-0.1.0.tgz
curl -O https://app.cloakapi.io/downloads/sdks/typescript/cloakapi-sdk-1.0.0.tgz

npm install ./cloakapi-sdk-1.0.0.tgz ./cloakapi-veil-tokens-0.1.0.tgz \
            ./cloakapi-review-core-0.1.0.tgz ./cloakapi-review-ui-0.1.0.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.