Projects

A project in Sentinel is a label. Every fingerprint, occurrence, and trace is stored with the project that was active when it was ingested. Projects keep one app’s history from leaking into another’s when you point multiple stacks at the same local database.

You will rarely need to think about projects until you have more than one. Once you do, they show up in three places: the CLI --project flag, defaults.project in .sentinel.yml for sentinel dev, and the project dropdown in the UI.

How a project name is picked

Resolution order, highest priority first:

1. --project <name> on the CLI
2. defaults.project in .sentinel.yml (only sentinel dev reads this)
3. for sentinel dev, the workspace directory name, normalized to lowercase with spaces changed to dashes
4. default for non-dev commands, or dev as a final fallback for sentinel dev

Project names passed with --project are trimmed, but otherwise kept as provided. That means My App and my-app are different project names. defaults.project in .sentinel.yml and the automatic sentinel dev workspace fallback are normalized by the dev config loader.

What scoping changes

Fingerprinting includes the project name in its hash, except for the default project (kept that way for backwards compatibility). So:

• The same exception in two different projects produces two different fingerprint IDs.
• sentinel history and sentinel analyze accept --project and only return rows for that project. sentinel explain --last N also honors --project; direct sentinel explain <fingerprint> looks up the fingerprint prefix you provide.
• The web UI has a project dropdown. Leave it on All Projects to see everything, or choose one project to filter the feed and traces.
• The trace database is partitioned the same way. sentinel traces --project foo only returns spans ingested under foo.

Setting a project

For a single ingest:

sentinel run --project my-app -- npm run dev
sentinel docker --project my-app
sentinel watch ./logs/*.log --project my-app

For a sentinel dev workspace, set it in .sentinel.yml and forget about it:

defaults:
  project: my-app

For ad-hoc CLI use, pass --project on each command that should write or read a specific project. The Settings page does not currently persist a default project.

Listing and deleting

sentinel project list
sentinel project delete my-app --dry-run
sentinel project delete my-app --yes

sentinel project delete removes fingerprints, occurrences, triage reports, traces, and session rows for that project. The local master key file and other projects are untouched. Always run --dry-run first when you intend to delete; the --yes flag is required to actually proceed without an interactive prompt.

Storage model in one paragraph

Sentinel stores everything in a single SQLite file under ~/.sentinel/sentinel.db by default. The schema migrates itself on first run. Issues live in fingerprints (with a project column and indexes on (project, last_seen) and (project, status)); occurrences and triage reports key off fingerprint IDs; traces and spans are stored in their own tables and rolled up periodically. The background maintenance routine in sentinel ui (and the Optimize Local DB button in Settings) prunes old rollups and runs SQLite’s optimize and analyze.

If you want a clean slate without losing other projects, prefer sentinel project delete <name> over removing the whole database.