First-run problems

Everything that commonly goes wrong between "I have an account" and "my first call worked." Each section is a symptom, its cause, and a recovery you can paste.

Two things this page does not cover:

• Provider and credential errors — 503 provider_unavailable, no_upstream_credential, upstream_provider_header_invalid, 404 embeddings_not_supported_for_provider. Those are diagnosed in provider errors.
• Blocked tool calls. A stopped call is not an error — it returns 200 with the call withheld and explained. See what you get back.

pip install sentisec-sdk fails with externally-managed-environment

Python distributions that ship the marker defined in PEP 668 — Homebrew Python on macOS, and the system Python on Debian, Ubuntu, and Fedora — refuse system-wide installs that the OS package manager does not own:

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try brew install xyz...

This is pip honouring the marker, not a Sentisec fault. The recovery is pipx, which builds a per-package virtual environment and puts sentisec on your PATH:

brew install pipx
pipx ensurepath
pipx install sentisec-sdk
sentisec --version

sudo apt update && sudo apt install -y pipx
pipx ensurepath
pipx install sentisec-sdk
sentisec --version

If you genuinely need pip — for example the SDK is a dependency of a larger Python app — create the virtual environment yourself first:

python3 -m venv ~/.sentisec-venv
source ~/.sentisec-venv/bin/activate
pip install sentisec-sdk

The installer reports an unsupported Python version

Releases are built per Python minor version. Supported: 3.11, 3.12, 3.13, and 3.14. Outside that range the installer stops. Its error identifies the detected minor version and interpreter path, lists the supported versions, and suggests installing a supported Python or setting SENTISEC_PYTHON. The exact path and version depend on your machine.

Install a supported version alongside your existing Python and re-run:

brew install [email protected]
curl -fsSL https://get.sentisec.ch | bash
sentisec --version

sudo apt update && sudo apt install -y python3.12
curl -fsSL https://get.sentisec.ch | bash
sentisec --version

The installer uses python3 resolved from your PATH; it does not search for the highest installed python3.X. Set SENTISEC_PYTHON to an executable interpreter path to select the release artifact for that interpreter. The installed zipapp still launches with python3, so ensure the python3 on your runtime PATH has the matching supported minor version, or use the isolated pipx install path.

npm install -g @sentisec/sdk succeeded but sentisec is not found

Three causes, in order of frequency.

The install was local, not global

Without -g, npm installs into ./node_modules/ and the binary lands at ./node_modules/.bin/sentisec, which is not on your shell's PATH:

npm install -g @sentisec/sdk
sentisec --version

If you are scripting the CLI inside a Node project, prefer npx sentisec ... from within that project — npm picks up the local entry without a global install.

The npm global bin directory is not on your PATH

Node managed by nvm, volta, or asdf puts global binaries somewhere your shell may not search. Find the directory:

npm prefix -g
# /Users/you/.nvm/versions/node/v22.16.0

Global binaries live in the bin/ beneath it. Add it to your shell profile — for zsh:

echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
sentisec --version

For bash use ~/.bashrc; for fish, set -Ux fish_user_paths (npm prefix -g)/bin $fish_user_paths.

The postinstall download failed

@sentisec/sdk fetches the native CLI for your platform after installation. If that fetch fails — a network blip, or a strict corporate proxy — npm still reports success but sentisec was never written. There will be a warning line in the npm output.

npm install -g @sentisec/sdk --force
# or fall back to the one-line installer
curl -fsSL https://get.sentisec.ch | bash

sentisec --version

The one-line installer ran but sentisec is not found

Your current shell has not reloaded its PATH

The installer appends a PATH line to your shell profile (~/.zshrc, ~/.bashrc, ~/.config/fish/config.fish). A shell that was already open when you ran it has not read that line yet:

source ~/.zshrc      # zsh
source ~/.bashrc     # bash

sentisec --version

Opening a new terminal tab has the same effect.

The download was interrupted

The installer is idempotent — re-run it. A second run replaces a partial download with a complete one and re-checks it against the release's SHA-256 manifest before unpacking:

curl -fsSL https://get.sentisec.ch | bash
sentisec --version

Behind a corporate proxy

The installer passes HTTPS_PROXY, HTTP_PROXY, and NO_PROXY through to curl unchanged. Export them before running it. If the download still fails, pipx install sentisec-sdk uses your existing pip proxy configuration instead.

My first call returns 401

Sentisec could not authenticate the key you sent. In order of frequency:

• You sent your provider key instead of your Sentisec key. The value in Authorization: Bearer or x-api-key must start with sk_sentisec_. Your Anthropic or OpenAI key belongs in your workspace under Settings → Providers, in Provider keys, not in the request.
• The key is from a different workspace. Keys are per workspace; one minted in workspace A cannot authenticate against workspace B. Check the workspace id in your URL matches the workspace you minted in.
• The key was revoked, or you pasted only the visible prefix. The full key is shown once, at mint time — if you no longer have it, mint a new one and revoke the old.
• Whitespace. A trailing newline from a copy-paste or a .env file is a surprisingly common cause.

Repeated failures from one address are rate-limited, so a script retrying a bad key will start seeing 429 — fix the key rather than backing off.

A 401 that names no_upstream_credential is a different problem: your key is fine, but the workspace has no credential for the provider you are calling. See provider errors.

My first call returns 404

Almost always the /v1 segment, which belongs on OpenAI-shaped URLs and not on Anthropic-shaped ones — the Anthropic SDK appends its own.

https://api.sentisec.ch/ws/<your-workspace-id>        # Anthropic-shaped
https://api.sentisec.ch/ws/<your-workspace-id>/v1     # OpenAI-shaped

A doubled /v1/v1/ in the final path means you set the Anthropic base URL with the suffix already on it. If you are building the path by hand rather than through an SDK, the full route is /ws/<your-workspace-id>/v1/messages or /ws/<your-workspace-id>/v1/chat/completions.

Calls succeed but nothing appears in the dashboard

Check the workspace id in your base URL against the one shown next to your API key. A call that authenticates but shows up in no session list is usually pointed at a different workspace than the one you are looking at — or at no workspace at all, if the /ws/<id> segment is missing. See your base URL.

Uninstall

Roll back whichever way you installed.

pipx uninstall sentisec-sdk

npm uninstall -g @sentisec/sdk

rm -f ~/.local/bin/sentisec
# Then open ~/.zshrc (or ~/.bashrc) and delete the two lines:
#   # Added by sentisec install.sh
#   export PATH="$HOME/.local/bin:$PATH"

If you had set up subscription mode, run sentisec edge uninstall before removing the CLI — it unwires the local background service and restores your agent's own configuration.

Re-open your shell. sentisec --version returning command not found is how you know the uninstall is complete. To also remove your paired credentials:

rm -rf ~/.sentisec

Still stuck

Updates / contradictions

2026-09-09 — Removed an illustrative error that was presented as literal installer output and corrected Python selection: PATH supplies python3; there is no highest-version scan.