Hello world: Python

Ready — installs from the CloakAPI downloads page. Tested end to end on Linux x86-64.

Runs today on Linux x86-64. On macOS, Windows and ARM the on-device engine is not available yet; the SDK uses basic detection and shows a warning.

1. Get an API key

Create a key at app.cloakapi.io/api-keys. It starts with cloak_. Verify your email to unlock your trial balance.

2. Install

Set up the on-device engine and pin: Engine setup.

python3 -m venv .venv && . .venv/bin/activate
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"
export CLOAKAPI_ENGINE_SHA256_PIN="$(awk '{print $1}' libcloak_engine.so.sha256)"
curl -fsSLO https://app.cloakapi.io/downloads/sdks/python/cloakapi-0.4.0.tar.gz
pip install ./cloakapi-0.4.0.tar.gz

The hello example uses review_callback, which ships in source 0.4.1 (not yet on the downloads page). Use pip install -e sdk/python from a checkout until then.

3. Set your key

export CLOAKAPI_API_KEY="cloak_your_key_here"

4. Run hello world

hello.py

import os
import sys

from cloakapi import CloakAPI
from cloakapi.errors import CloakAPIError, ReviewRequiredError

PROMPT = "Say hello to jane.doe@example.com in one short sentence."


def review(request):
    body = request.body.decode("utf-8") if isinstance(request.body, bytes) else request.body
    print(f"This exact request will leave your machine:\n\n{request.method} {request.url}\n{body}")
    return input("\nSend it? [y/N] ").strip().lower() == "y"


api_key = os.environ.get("CLOAKAPI_API_KEY")
if not api_key:
    sys.exit("CLOAKAPI_API_KEY is not set. Create a key at https://app.cloakapi.io/api-keys")

client = CloakAPI(api_key=api_key, review_callback=review)
try:
    msg = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=100,
        messages=[{"role": "user", "content": PROMPT}],
    )
except ReviewRequiredError:
    print("Not sent. You declined the request.")
    sys.exit(0)
except CloakAPIError as err:
    sys.exit(f"Request failed: {err}")

print("\nReply (restored on your device):")
print(msg.text())

cp path/to/examples/hello.py .
python3 hello.py

5. What you should see

You’ll see the exact request before it is sent. Your email address is replaced with a token like <<CLOAK:CONTACT_EM:3f9a1c>>. Type y. The reply comes back with the real address restored on your device. The reply text varies.

If something goes wrong

See the Python SDK README for common messages and fixes.

What this does and does not do

• Detection is best-effort. Emails, phone numbers, cards and similar are matched by rules; names use an on-device list and an optional on-device model, and may be missed. A value the detector misses is sent as written.
• You see the exact request before it is sent.
• CloakAPI does not refuse a request because of what it contains. Errors come from your key, balance, usage limits, request format or size, or the model provider.
• The gateway does not run detection on your content. It checks the request proof, then relays it to the model provider.
• Model calls use your trial balance, or your own provider key (BYOK) if you added one in the portal.