Engine setup (on-device)

Native CloakAPI SDKs (Python, Go, Java, .NET, PHP, Ruby, Rust) load libcloak_engine on your machine before a protected request is sent. Browser TypeScript uses a separate WASM path — see the browser extension guide and the TypeScript SDK README.

This page is the single place for engine and name-model downloads. Language READMEs link here instead of duplicating the steps.

Download and verify the engine

curl -fsSLO https://app.cloakapi.io/downloads/sdks/engine/libcloak_engine.so
curl -fsSLO https://app.cloakapi.io/downloads/sdks/engine/libcloak_engine.so.sha256
sha256sum -c libcloak_engine.so.sha256
export CLOAKAPI_ENGINE_LIB="$PWD/libcloak_engine.so"

Point CLOAKAPI_ENGINE_LIB at the verified file. Cross-check the digest in manifest.json when you can.

Sidecar format (sha256sum -c)

Each .sha256 file beside a download is a GNU sha256sum checkfile: a 64-character hexadecimal digest, two spaces, then the artifact basename (for example … libcloak_engine.so). CloakAPI publishes sidecars in that form when the download tree is built.

Set your pin from the digest (first field):

export CLOAKAPI_ENGINE_SHA256_PIN="$(awk '{print $1}' libcloak_engine.so.sha256)"

You can also copy the 64-character hex digest manually from the sidecar.

Pin integrity (read this before production)

CLOAKAPI_ENGINE_SHA256_PIN records which engine binary you intend to run. SDKs compare the loaded library’s hash to this value; the gateway checks the declared engine identity on protected relays.

If you fetch both the .so and its .sha256 sidecar from the same host in one session, you are trusting that host for the bytes and the expected hash. That is fine for many dev setups, but it gives weaker integrity than getting the digest from an independent source (a second mirror, your own earlier pin, or manifest.json after verifying the file out of band). Choose based on your threat model.

Name model (~178 MB, optional)

Structured identifiers (email, phone, payment cards, government IDs) use deterministic detectors and do not need the neural model. Person names use an ONNX model that is not compiled into the .so. Without it, names may be missed on the text path unless you explicitly accept reduced coverage later.

curl -fsSLO https://app.cloakapi.io/downloads/sdks/engine/model.onnx
curl -fsSLO https://app.cloakapi.io/downloads/sdks/engine/model.onnx.sha256
sha256sum -c model.onnx.sha256
curl -fsSLO https://app.cloakapi.io/downloads/sdks/engine/tokenizer.json
export CLOAKAPI_NER_MODEL_PATH="$PWD/model.onnx"
export CLOAKAPI_NER_TOKENIZER_PATH="$PWD/tokenizer.json"

When the model loads, SDK results report ner_enabled: true.

Pin mismatch message (terminal examples)

SDK hello-world and CLI examples use this message when the loaded engine does not match CLOAKAPI_ENGINE_SHA256_PIN (exit code 1):

The on-device engine does not match CLOAKAPI_ENGINE_SHA256_PIN. Download the engine again and update the pin: https://docs.cloakapi.io/start/engine-setup/

Reduced coverage is not step one

Do not treat CLOAKAPI_ALLOW_REDUCED=1 as the first fix when the engine or name model is missing. That flag opts into reduced name coverage and is for an explicit operator decision after you understand the tradeoff — not for initial onboarding.