Docs · v0.1 live

Sentinel concepts.

This page covers everything you need to know to use Sentinel: the four core building blocks (commits, allow paths, guards, kill switch), the routing matrix that wires them together, agent registration, and how to use the SDK.

Commits

A commit is a single batch of changes your agent makes to the codebase — the same idea as a Git commit, but with extra agent-context attached. Every Sentinel commit records:

• Which agent made it (its registered identity).
• Which prompt triggered it.
• Which model + run id generated the work.
• Which files were touched and what changed.
• Timestamp and parent commit it built on.

Git tells you "Kestrel committed at 3:42 PM." Sentinel tells you "Kestrel was asked to fix the Site Policy crash and changed line 1922 of AdminDashboardPage.jsx." That's the full chain of authorship.

Allow paths

A whitelist of file paths your agent is expected to touch. Anything outside the list raises a flag. Defaults on a new project:

src/**
app/**
frontend/**
backend/**

If your agent commits a change to frontend/src/pages/BrowsePage.jsx it matches frontend/** ✅. If it ever tries /etc/hosts — way outside the list ⚠️ — Sentinel routes that commit to the approval queue. The point: agents stay in their lane.

Guards (a.k.a. sensitive patterns)

A blacklist of file paths that always trigger human approval — even if the agent is your trusted primary, even if the path is inside the allow-list. Defaults (14 patterns) cover the danger zones:

.env              .env.*              secrets/**          credentials/**
**/auth/**        **/auth.py          **/auth.js          **/migrations/**
**/payment*       **/stripe*          **/paypal*
Dockerfile        **/*deploy*         **/.github/**

This is the "buy-off from a human for steps that affect secure data" rule made concrete. Authentication code, env files, payment integrations, deploy configs, database migrations — these are the moments where one bad agent line could nuke production. Guards force a human review before they ship.

Kill switch

A master "no writes" toggle. When ON, every commit attempt from any agent — including the primary — is rejected with HTTP 423 and logged. Flip it back off and commits resume.

When to use it: live demo coming up; you spotted something weird in the queue and want to freeze the codebase; vacation; an agent misbehaving and you want it stopped instantly without unregistering it.

It's the parachute. Hopefully you never pull the cord, but if you do it works instantly and atomically.

Routing matrix

How a commit flows from your agent to either auto-merge, the approval queue, or a rejection:

Agents

An agent is a project-scoped machine identity. Each agent gets a unique API key (SHA-256 hashed at rest, shown to you once on creation/rotation), an optional expiry (default 30 days), and an optional hourly rate limit. Designate one agent per project as the primary — that's the agent whose clean commits auto-merge. Everyone else's work flows to the approval queue.

You can rotate a key any time (invalidates the old one instantly), revoke an agent (irreversible — they're locked out), or extend the TTL.

SDK quick-start

The Sentinel Python SDK is a single file — no install dance. Drop sentinel_sdk.py into your repo, run one command, and every git commit is governed automatically.

# Drop sentinel_sdk.py into your repo root, then run one command:
python -m sentinel_sdk init --token YOUR_SENTINEL_TOKEN

# This creates your project, registers a primary agent,
# installs a git post-commit hook, and opens your dashboard.

# From now on, just commit as normal:
git commit -m "Fix Site Policy crash"
# Sentinel reports the commit automatically:
#   clean commits from your primary agent -> approved
#   risky writes (.env, auth, payments)    -> pending your review

That's the whole setup. The git hook reports each commit for you — it never blocks or slows your commit — and Sentinel returns the routing decision so you can see instantly whether a change auto-shipped or is awaiting your sign-off.

Reporting from the SDK

The same client can pull your governance data — the monthly activity report, the failed-only view, the flagged-commit drill-down, the agent leaderboard, and a one-page PDF. Authenticate with your Sentinel account token.

from sentinel_sdk import Sentinel

s = Sentinel(token="YOUR_SENTINEL_TOKEN")   # from your Sentinel account

s.activity_report(scope="all")      # every commit, this month vs last
s.activity_report(scope="failed")   # rejected + risk-flagged only
s.flagged_commits(month="current")  # who touched sensitive paths
s.agent_leaderboard()               # agents ranked by how often they're flagged
s.export_pdf("sentinel-report.pdf") # one-page PDF for board / compliance

Equivalent CLI: sentinel report, sentinel report --failed, sentinel report flagged, sentinel report leaderboard, and sentinel report export --pdf. Every command maps to a customer-scoped endpoint under /api/sentinel/me/* that only ever returns your own projects.

Desktop dashboard

The same downloadable client ships a live local dashboard. Run one command and an always-on window docks to your screen — commits, flagged writes and the agent leaderboard update in real time, with a one-click minimise/enlarge. No browser tab, served straight from your machine.

# launch the live dashboard (opens your browser)
python -m sentinel_sdk dashboard \
  --token $SENTINEL_TOKEN

# or from Python:
from sentinel_sdk import Sentinel
Sentinel(token="YOUR_SENTINEL_TOKEN").dashboard()

Desktop operations (what each button does)

A plain-English guide to every button in the desktop app (the window at http://localhost:8787), grouped by where you'll find it. Also in the Install Guide.

Feed it with your commits — the git hook

The dashboard is a monitor — it lights up when commits are reported to Sentinel. The fastest way to feed it real activity is the built-in git hook: install it once and every git commit reports itself automatically (it never blocks your commit).

You'll need a per-project agent key (snt_…) from your project's Register agent screen, and your project ID.

# 1. Install the hook once, inside your repo:
python -m sentinel_sdk install-hook \
  --project YOUR_PROJECT_ID \
  --agent-key snt_YOUR_AGENT_KEY \
  --base https://sci-ficomics.com/api

# → writes .git/hooks/post-commit

# 2. That's it. Commit as normal:
git commit -m "Fix reader crash"
# Sentinel: 6e3e3a87993e → approved
# (a commit touching .env / auth / payments shows up flagged + pending)

# Report the current HEAD manually any time:
python -m sentinel_sdk report-commit \
  --project YOUR_PROJECT_ID --agent-key snt_… --base https://sci-ficomics.com/api