Quickstart
Five minutes, no model server and no secrets to export:
mkdir voc && cd vocuvx --from "obsei[recommended]>=1.0" obsei init # project, secrets, sample data, local modelobsei try # redacted, labelled preview of the sampleobsei try https://apps.apple.com/us/app/whatsapp-messenger/id310633997 # any public linkobsei run # fetch, redact, label, deliver, storeThen add your own sources and sinks without editing YAML: obsei add appstore, obsei add slack,
obsei check (see Set up without editing YAML).
obsei needs Python 3.11 or newer. On an older Python, pip and uv quietly pick the legacy 0.0.x
instead, so keep the >=1.0 floor in install commands; obsei --version shows what you got.
obsei[recommended] is the full local setup: the classifier (local) and multilingual themes
(embeddings). uvx runs obsei without installing it; to keep the obsei command, install it
once with uv tool install "obsei[recommended]>=1.0" (or pip install).
obsei init creates:
obsei.yaml, with theclassifyenricher on whenobsei[local]is installed, andfeedback.csv, a sample in ten languages with a few synthetic emails, phone numbers and card numbers so you can see redaction work..obsei/secrets.envwith a random database key (OBSEI_DB_KEY) and author pseudonym salt (OBSEI_PSEUDONYM_SALT), readable only by you, and.obsei/in.gitignore. Every command loads it; variables already set in the environment win, andobsei doctorshows where each came from. Back the file up: without the key the database cannot be read, and a new salt produces new pseudonyms.obsei initnever overwrites it.- DuckDB’s
httpfsextension for encryption and, withobsei[local], the classifier model (about 1.2 GB, once).--offlineskips both downloads.
On servers and in CI, set OBSEI_DB_KEY and OBSEI_PSEUDONYM_SALT from your secret manager, or
mount a .obsei/secrets.env next to obsei.yaml.
Preview with obsei try
Section titled “Preview with obsei try”obsei try prints a table of up to 10 records per source (--limit): source, language, labels
with the model’s confidence (review marks answers below the cutoff) and the redacted text. Below
it, the number of values redacted per type and before and after for three records. Nothing is
stored or sent; the original text exists only in that preview. --json prints one JSON object per
record instead, and --no-enrich skips the classifier. If the classifier cannot run, the table
still shows redaction and a warning says why.
Without an argument it reads the sources in obsei.yaml. With a link or a file it reads only that,
with redaction always on and the enrichers of the first pipeline (or -p NAME); outside a project,
with the local classifier when obsei[local] is installed:
| Argument | Source |
|---|---|
https://apps.apple.com/<country>/app/<name>/id<digits> |
appstore, that app and country |
https://github.com/<owner>/<repo> |
github_issues, without a token |
https://news.ycombinator.com/item?id=<id> or an hn.algolia.com search |
hackernews |
https://wordpress.org/support/plugin/<slug>/reviews/ |
rss, the plugin’s review feed |
| Any other link | rss (RSS 2.0 or Atom) |
.csv, .jsonl, .json file |
csv, jsonl or filedrop, text from a text, comment, review, body, content, message or feedback column |
Google Play, YouTube and Bluesky need credentials, so obsei try names the source to configure
instead. The preview fetches only from the link’s host. The egress policy governs where feedback
is sent (models and sinks), and the local classifier runs in process, so nothing else is
contacted.
Optional extras
Section titled “Optional extras”Some features need extra packages. Add them to the same install:
| Extra | Adds |
|---|---|
recommended |
local and embeddings: everything that runs on this machine |
mcp |
obsei serve, obsei mcp and Studio over HTTP |
local |
the local classifier for classify (PyTorch; no model server) |
embeddings |
the local multilingual model, so themes group across languages |
names |
local name redaction (GLiNER) |
sql |
the SQL source and sink |
google |
the Google Play source |
apple |
the App Store Connect source |
# uv tool: --force replaces the install, so list every extra you want to keepuv tool install --force "obsei[mcp,embeddings]>=1.0"# pip, in the environment where obsei is installedpip install "obsei[mcp,embeddings]>=1.0"uv run --extra ... only works inside a project checkout; outside one it ignores the extra.
Plugins install the same way: uv tool install --force obsei --with obsei-teams
(see Plugins).
Add a model
Section titled “Add a model”The default classifier runs inside obsei on the CPU, so there is no model server to start. If you
ran obsei init without obsei[local], add it and fetch the model:
uv tool install --force "obsei[local]>=1.0" # or: pip install "obsei[local]>=1.0"obsei models download # once, with network (about 1.2 GB)Then uncomment the classify enricher in obsei.yaml. Every record gets sentiment, intent and
language, with a probability for each answer; answers below the cutoff are marked for review. To
use a decision model, Ollama or a hosted LLM instead, or to add the chat model that obsei ask
needs, see Models.
Ask your agent
Section titled “Ask your agent”claude mcp add obsei -- obsei mcpThen ask: “What are the top complaints this month, by country?” See MCP and agents.
Run with Docker
Section titled “Run with Docker”Run inside the project directory. The image’s entrypoint is obsei, so arguments are subcommands:
docker run --rm -v "$PWD:/data" -w /data --user "$(id -u):$(id -g)" \ ghcr.io/obsei/obsei:1.1.1 runThe container reads .obsei/secrets.env from the mounted project; pass -e OBSEI_DB_KEY -e OBSEI_PSEUDONYM_SALT instead when the secrets come from the environment.
Images are tagged by release (1.1.1); there is no latest tag yet. --user keeps the
database and outputs owned by you.
Docker Compose
Section titled “Docker Compose”docker-compose.yml runs
obsei serve with the store in a named volume and your obsei.yaml mounted read-only. Copy it and
.env.example into your project
directory:
cp .env.example .env # fill in OBSEI_DB_KEY, OBSEI_PSEUDONYM_SALT (e.g. from .obsei/secrets.env) and OBSEI_API_TOKENdocker compose up -ddocker compose ps # healthy once /healthz answersStudio is at http://localhost:8765/studio/ and MCP at http://localhost:8765/mcp, both behind
OBSEI_API_TOKEN (see Server and webhooks). The port is published on
127.0.0.1 only; change the mapping to expose it. Files your pipelines read, such as a CSV,
need their own mount under /data.