Install guide

Get Sentinel running.

From zero to a live, governed commit feed in about five minutes. Sign up, subscribe, drop in the SDK, then run one setup command — it creates your project, wires the git hook, and opens your dashboard. Follow the steps in order.

You're on a phone — installing needs a computer. Sentinel runs as a desktop app (Windows, macOS or Linux) with Python. Read the steps here, then open this page on your PC to actually install and run the SDK.

New to Python or git? You'll need both installed first. Full step-by-step install instructions for Windows, Mac & Linux are at the end of this guide — jump to "Installing Python & git" →

Members print & save — subscribe Dashboard manual (PDF) Activity Report manual (PDF)

Before you start

A computer with Python 3.8+ and git installed.
The requests library: pip install requests
A project that lives in a git repository (GitHub, GitLab, Bitbucket, etc.).

Not sure if you have them? Open a terminal and run:

# Mac / Linux
python3 --version
git --version

# Windows (try py if python doesn't work)
python --version
git --version

You should see something like Python 3.11.5 — any 3.8 or higher works. If you see Python 2.x, use the python3 command instead. Missing one, or getting "not recognized" / "command not found"? See Installing Python & git at the end of this guide.

Create your account

Go to /sentinel and click Get started (or open /sentinel/signup). Sign up with your email and password — you'll land on your Sentinel Start Here page.

Tip: members can print or save this guide as a PDF to follow along offline — it's included with your subscription.

A new account is read-only until you subscribe. On the dashboard click Subscribe (or open /sentinel/pricing) and complete checkout. Project creation unlocks the moment your subscription is active.

Download the SDK into your repo

On your Start Here dashboard click Download sentinel_sdk.py. Save the downloaded sentinel_sdk.py to a local folder (on your PC) named "git repo".

Run one setup command

In a terminal at your repo root, run the following command. Click the Copy setup command button below to copy the command string you need to paste into your local terminal window to make the connection to Sentinel.

python -m sentinel_sdk init --token YOUR_SENTINEL_TOKEN

That one command does everything for you — no keys to copy, no config to edit:

Creates a Sentinel project for this repo (named after the folder), with sensible default allow-paths and guards.
Registers a primary agent and its key automatically.
Installs the git post-commit hook so every commit is reported — it never blocks or slows your commit.
Opens your live dashboard and Activity Report in your browser.
Places a "Sentinel" log-on icon on your desktop — from now on just double-click it to reopen your Dashboard and Activity Report together, no command needed.

Re-running init is safe — it reuses the project already linked to this repo and skips the hook if it's installed, so nothing gets duplicated.

Verify it's working

Want to double-check? Run the built-in self-check from your repo root — it confirms Python, requests, git, the hook, and your connection to Sentinel:

python -m sentinel_sdk check --base https://sci-ficomics.com/api

Every line should read [ OK ] and finish with "All good — Sentinel is ready." If any line shows [FAIL], see Troubleshooting at the end for the exact fix — and if you're still stuck, copy the whole output and email it to support@sci-ficomics.com.

Commit as normal

git commit -m "Fix reader crash"
# Sentinel: 6e3e3a87993e → approved

The hook reports each commit automatically and never blocks it. A commit touching .env, auth, or payments comes back flagged + pending for your review — watch it land live on the dashboard init just opened.

Review & control

Everything below happens on your Start Here dashboard. The Sentinel Activity Report there is read-only — it shows you what needs attention (approved / pending / rejected counts, trends and flagged writes); you take action inside the project itself:

Approve or reject a pending commit: open the project from your dashboard, go to its Pending approval tab, and use the Approve / Reject buttons on each commit.
Freeze a project (Kill switch): on the project's card in the dashboard list, click its Kill switch button. The card turns red and all of that project's agent writes are blocked instantly. Click Disable kill switch to resume.
See trends & export: the Sentinel Activity Report shows activity over time and lets you export CSV / PDF.

Good to know

• The hook runs on your own computer, and only in the copy of the project where you installed it. If you work on this project from more than one computer, re-run init (Steps 3–4) on each one.

• It reports after a commit lands, so it never blocks or slows your work.

• Changes made by Emergent's build agent happen on Emergent's servers, so your hook doesn't see them. To track those, run git pull to bring them onto your computer, then commit them there.

Note — a plain-English breakdown of two git terms above:

"A clone" = a copy of your code repository sitting on a computer. When you run git clone, git downloads the whole project onto that machine. So if you have the same project on your work laptop and your home desktop, that's two clones — two separate copies. Sentinel's hook lives inside one copy's .git folder, so it only works on the machine where you installed it. If you want commits tracked from more than one computer, re-run init (Steps 3–4) on each one.

"Commit on your machine" = a git commit you make from your own computer. Sentinel's hook only fires when a commit happens where the hook is installed — i.e., your machine. Emergent's build agent makes its commits up in its own cloud sandbox, where your hook isn't installed, so those changes never trigger Sentinel. To get them tracked, run git pull to bring them onto your computer, then commit them there — that commit does run the hook.

In short: the hook only sees commits made on a computer where you personally installed it.

Re-open your dashboard & Activity Report later

Step 4's init already opens both for you the first time. When you come back later and just want to watch your activity again — without re-running setup — use the open command. It's the same one the Start Here page hands you.

On your Start Here dashboard, click Copy re-open command (your token is filled in automatically).
In a terminal at your repo root, paste and run it:
```
python -m sentinel_sdk open --token YOUR_SENTINEL_TOKEN
```
Log in and reopen this page to have your token filled in automatically.
Two browser tabs open — the live dashboard at http://localhost:8787 and your Activity Report at http://localhost:8788.
Leave it running while you work; stop both anytime with Ctrl + C.

A "Sentinel" icon is placed on your desktop

The first time you run init or open, Sentinel drops a "Sentinel" log-on icon on your desktop. After that you don't need this command at all — just double-click the desktop icon to reopen your live Dashboard and Activity Report together. Your token is remembered securely on your computer, so the icon works on its own.

Prefer just one? python -m sentinel_sdk dashboard --token … opens only the live dashboard, and … report --token … --port 8788 opens only the report. Your token is private — treat it like a password; reset it from your dashboard if it ever leaks.

How to add a commit (test it)

Want to confirm Sentinel is really watching? Make a commit in a connected repo and watch it land on your dashboard within seconds. A brand-new account shows No commits yet until you do this — that's normal.

1. A clean commit → auto-approved

In a repo where you ran init (or used + Connect a repo), run this. --allow-empty lets you test without changing any files:

git commit --allow-empty -m "sentinel test"

Your terminal prints something like Sentinel: 6e3e3a87 → approved, and the commit appears on the dashboard's Overview and Commits tabs — no guard touched, so it auto-merges.

2. A risky commit → held for approval

Guards trigger on the files a commit touches. Create a guarded file (like .env) and commit it to see it get flagged:

echo "SECRET=test" > .env
git add .env
git commit -m "add env file"

This one comes back flagged + pending and waits in your Pending tab, where you can Approve or Reject it. (The commit still lands in git locally — Sentinel governs the record, it never blocks your commit.)

Tip: don't want a real .env lying around? Delete it after testing with rm .env (or del .env on Windows) and commit again.

Desktop Operations — what each button does

A plain-English guide to every button in the desktop app (the window that opens at http://localhost:8787). Buttons are grouped by where you'll find them.

Top of the app

Project dropdownSwitches which project you're viewing. It lists your Sentinel projects — not folders on your computer.

Overview · Agents · Commits · Pending · Guards · Audit logThe row of tabs. Click one to switch views (each is explained below).

Overview tab

+ Connect a repoTurns a local folder into a Sentinel project in one click — creates the project, generates an agent key, and installs the git commit hook. Runs git init for you if the folder isn't a repo yet.

ConnectConfirms the folder path (and optional name) in the Connect form and sets everything up.

CancelCloses the Connect form without doing anything.

Kill switchFreezes a project: every agent write is instantly rejected until you turn it off. Use it if an agent goes rogue.

DisableAppears once the kill switch is on — clicking it lifts the freeze so commits flow normally again.

Agents tab

+ New agentCreates a new agent and shows its key once — copy it right away.

Rotate keyIssues a fresh key for that agent and instantly invalidates the old one. Use it if a key may have leaked.

DeleteRemoves the agent entirely. Any tool still using its key will stop being able to report.

Commits & Pending tabs

ApproveLets a held commit through — it counts as reviewed and ships.

RejectBlocks a held commit. You'll be asked for an optional reason, which is saved to the audit log.

Guards tab

Add (Allow-paths)Adds a folder pattern (e.g. src/**) that agents may write to freely without needing approval.

Add (Guard patterns)Adds a pattern (e.g. .env) that always requires your sign-off, even inside allow-paths.

Return to defaultsReplaces that list with Sentinel's recommended default patterns.

× (on a chip)Removes that single path from the list.

Activity Report window (localhost:8788)

PDFDownloads the current report as a PDF you can save or share.

CSVDownloads the underlying numbers as a spreadsheet-friendly CSV.

This vs last monthPreset that compares the current month against the previous one.

Apply rangeRuns the report for the custom start/end dates you picked.

N flagged ▾Expands a period to list the individual flagged commits behind the number.

Create your account →Read the full docs →

Troubleshooting

If the self-check shows a [FAIL]

Run python -m sentinel_sdk check --base https://sci-ficomics.com/api (from Step 4). Find the line that failed below and follow its fix — most take under a minute.

[FAIL] Python 3.8+

Python isn't installed or is too old. See Installing Python & git below. If python shows a 2.x version, use python3 instead.

[FAIL] requests library

Install the one library Sentinel needs: pip install requests (or pip3 install requests / python -m pip install requests).

[FAIL] git installed

git isn't installed or isn't on your PATH. See Installing Python & git below, then open a fresh terminal.

[FAIL] git repository

You're not inside a git project. cd into your project folder and try again. If the folder isn't a repo yet, run git init first.

[FAIL] Sentinel commit hook

The hook isn't installed in this repo (or another tool's hook is there). Re-run Step 4's init command from your repo root. Remember: the hook is per-repo, so run it once in each clone.

[FAIL] Reach Sentinel server

Your machine can't reach Sentinel. Check your internet connection, confirm the --base URL matches the one in this guide (https://sci-ficomics.com/api), and if you're on a corporate network, a firewall or VPN may be blocking it.

[FAIL] Project key valid

The agent key is wrong, expired, or revoked. Easiest fix: re-run Step 4's init — it registers a fresh agent and re-wires the hook for you. (This line only appears if you passed --project and --agent-key to check yourself.)

[FAIL] Subscription active

Your Sentinel subscription isn't active, so commits are paused. Open /sentinel/pricing and subscribe (or reactivate). Everything resumes the moment it's active — your keys are kept.

Still stuck after fixing the failed line? Run the check once more, copy the entire output, and email it to support@sci-ficomics.com — it tells us exactly where things break so we can get you running fast.

Appendix

Installing Python & git

Only needed if the checks in "Before you start" failed. Do these once, then return to Step 1. After installing, always close and reopen your terminal so it picks up the new commands.

Python 3.8+

Windows

Go to python.org/downloads and click "Download Python 3.x".
Run the installer. On the first screen, tick "Add python.exe to PATH" (this is the #1 thing people miss), then click "Install Now".
Close and reopen your terminal, then verify: python --version (or py --version).

Mac

Easiest with Homebrew: brew install python
Or download the installer from python.org/downloads/macos and run it.
Verify: python3 --version

Linux

# Debian / Ubuntu
sudo apt update && sudo apt install python3 python3-pip

# Fedora
sudo dnf install python3 python3-pip

# then verify
python3 --version

git