sentisec-sdk

Public Python SDK for Sentisec.

sentisec-sdk is a thin client. You install it with pip, point it at your workspace, and wrap your existing OpenAI / Anthropic client. Your agent's tool calls then flow through Sentisec's hosted control plane, where they are evaluated and either allowed, rewritten, or blocked before they reach the world.

Install

pip install sentisec-sdk

Python 3.11+ is required.

Quick start

from sentisec_sdk import Monitor

monitor = Monitor()  # picks up ~/.sentisec/credentials.toml after `sentisec login`
client = monitor.wrap_openai(...)
client = monitor.wrap_anthropic(...)

The sentisec CLI is shipped in the same wheel — see The sentisec CLI below for the full surface.

sentisec login
sentisec status
sentisec demo run
sentisec logout

From 0.1.0a4 onwards SENTISEC_WORKSPACE_ID is OPTIONAL — the Sentisec proxy resolves the workspace from the API key prefix, so a one-env-var setup (SENTISEC_API_KEY only) is sufficient for the wrap_anthropic / wrap_openai path.

Corrected 2026-08-18: this section used to warn that Monitor() / Session() "raises NotImplementedError" in the alpha. That has not been true since 0.1.0a0 — the wrapper path is fully implemented and tested. The note is removed rather than softened; it described a build state, not the shipped wheel.

Protecting a Claude Code / Codex subscription (sentisec edge)

The same wheel ships the edge daemon — the way to put Sentisec in front of an agent you drive on a Claude or ChatGPT subscription, with no API key and no provider token ever leaving your machine.

sentisec edge            # guided setup: pair, install, start
sentisec edge status     # what is wired and whether it is healthy
sentisec edge off        # pause: calls pass through unchecked
sentisec edge on         # resume (also restarts the local service)
sentisec edge logs       # the local service log
sentisec edge uninstall  # remove the service, hooks and provider entry

Setup is re-runnable and refuses before it writes: it looks for Claude Code first, then verifies your workspace key with Sentisec, then shows every file it is about to change and asks once. For a headless install, pass --key (or set SENTISEC_WORKSPACE_KEY) with --yes:

sentisec edge setup --yes --key "$SENTISEC_WORKSPACE_KEY"

sentisec edge off is real: while it is paused the local service answers every Claude Code hook with an explicit "not checked" allow, relays Codex turns untouched, and uploads nothing.

Setup starts a small local service (launchd on macOS, a systemd user unit on Linux) listening on 127.0.0.1:45711. It forwards Claude Code's PreToolUse hooks to Sentisec's hosted control plane for a verdict and uploads a token-scrubbed activity trail. When Codex is wired it also listens on 45712 and relays each turn to chatgpt.com — your ChatGPT credential goes there and nowhere else, and the copy Sentisec analyses is redacted before it is sent.

No detection logic runs on your machine. The daemon forwards and enforces; the analysis happens server-side.

When Sentisec cannot be reached

The daemon has to answer a tool call it is holding, even when Sentisec's hosted plane is unreachable. What it answers is yours to choose:

The same value can live in ~/.sentisec/edge.toml as fail_posture = "…"; the environment variable wins, so you can change posture during an incident without editing a file the setup wizard also writes. Until the daemon has completed one successful check it does not know which kind of workspace it belongs to, and allows.

Whatever it decides, it records: every unchecked call leaves a event=edge_fail_posture_applied line in the daemon's log naming the cause, the posture and the decision, and the activity trail marks the call as unchecked once connectivity returns.

The sentisec CLI

One command group, one exit-code contract, --json on everything that has something to report.

Exit codes. Every command uses the same seven:

Machine-readable output. --json prints exactly one JSON document on stdout and nothing else; every document carries schema_version and exit_code. Available on status, doctor, demo run, update, version, login, logout, edge status, edge setup --yes, edge on, edge off and edge uninstall. A workspace key never appears in any of them — only its last four characters.

Terminal behaviour. Colour is off under NO_COLOR, TERM=dumb, --no-color, --plain, and whenever stdout is not a terminal. --plain prints the same lines without panels, spinners or colour, with ASCII status markers. -q prints nothing and lets the exit code carry the answer.

Version check. status, doctor, version, update and the bare help may check for a newer release: one request, a one-second budget, cached for a day under ~/.sentisec/update-check.json, silent on failure, and never before the command's own output. Set SENTISEC_NO_UPDATE_CHECK=1 to switch it off. sentisec update only prints the upgrade command for however you installed the CLI; it never changes the installation itself.

Documentation

• Product overview: https://sentisec.ch
• Developer docs: https://docs.sentisec.ch
• Dashboard: https://app.sentisec.ch
• Support: mailto:support@sentisec.ch

Building the standalone CLI

For shipping channels that cannot rely on a working pip on the user's box (curl installer, npm postinstall, GitHub Releases tarball), the sentisec console-script entry is bundled as a single shiv zipapp:

# one-time: install the build-only extra
uv pip install --system shiv          # or: pipx install shiv

# build
./scripts/build-cli.sh                # → dist/sentisec (executable)

# (optional) verify the build is reproducible
VERIFY_DETERMINISM=1 ./scripts/build-cli.sh

The build script:

• runs shiv --console-script sentisec --output-file dist/sentisec --reproducible --compressed --python "/usr/bin/env python3" .,
• smoke-tests ./dist/sentisec --version and asserts the output equals sentisec <version-from-pyproject>,
• when VERIFY_DETERMINISM=1, rebuilds into a tempdir and diffs the two artifacts byte-for-byte (shiv's --reproducible flag pins all zip-entry timestamps to a fixed value).

Platform caveat. The resulting dist/sentisec shebangs to /usr/bin/env python3, but its bundled wheels include the native pydantic-core extension for the builder's (os, arch, python-minor) tuple. The artifact therefore runs on hosts matching that tuple only. The release pipeline (P-INST-02) matrix-builds one artifact per supported tuple and uploads each as a separate GitHub Release asset.

License

Apache License 2.0. See LICENSE.