🛡️ SentinelAI

Secure, Local-First AI Workspace

*A self-hostable AI agent that connects teams to workspace knowledge, source code, email, calendars, and operational tools through the Model Context Protocol (MCP).*

Download v2.0.0 · Architecture · Features · Quick Start · Security · Operations

💡 What is SentinelAI?

Imagine asking one workspace:

“What does our incident policy require, did anyone discuss this in Gmail, and is there already a GitHub issue?”

SentinelAI can search only the documents available to that workspace, inspect connected services using that user's credentials, show its sources and tool trace, and pause before an external write. The user reviews the exact action and arguments; nothing pending approval is executed.

It is more than a chat wrapper: it demonstrates the platform controls around an AI agent—identity, authorization, workspace isolation, retrieval, tool policy, approvals, audit records, evaluation, and deployment.

Why MCP?

The Model Context Protocol gives the agent a standard interface for discovering and calling tools. SentinelAI exposes 18 tools through one local FastMCP server while keeping user identity and authorization in the trusted API layer.

Related MCP server: WorkplaceSearchAgent MCP Server

🏗️ Architecture

flowchart TD
    User([👤 User])
    UI[Next.js 16 + React 19<br/>Workspace UI]
    API[FastAPI Gateway<br/>CORS • Rate Limits • Security Headers]
    Auth[Trusted Identity<br/>JWT/OIDC • RBAC • Workspaces]
    Agent[Bounded Agent Loop<br/>Streaming • Tool Trace • Cancellation]
    Policy[Server-Side Tool Policy<br/>Roles • Credentials • Repo Allowlist]
    Approval[Exact Write Approval<br/>Expiring • Atomic • Single-Use]
    LLM[(Ollama Local Model<br/>Optional OpenAI / Anthropic)]
    MCP[Local FastMCP Server<br/>18 Tools • Per-User Environment]
    RAG[Workspace Retrieval<br/>Keyword or Hybrid]
    DB[(SQLite or PostgreSQL<br/>Full-Text + pgvector)]
    Jobs[Durable Ingestion Queue<br/>Single Worker]
    External[GitHub • Gmail • Calendar]
    Host[Restricted Filesystem • SQL]

    User --> UI --> API
    API --> Auth
    API --> Agent
    API --> Jobs
    Agent --> LLM
    Agent --> Policy
    Policy --> RAG --> DB
    Policy --> MCP
    Policy --> Approval --> MCP
    MCP --> External
    MCP --> Host
    Auth --> DB
    Jobs --> DB

    classDef gateway fill:#3b82f6,stroke:#1e40af,color:#fff
    classDef security fill:#ef4444,stroke:#991b1b,color:#fff
    classDef ai fill:#8b5cf6,stroke:#5b21b6,color:#fff
    classDef tool fill:#22c55e,stroke:#15803d,color:#fff
    class UI,API gateway
    class Auth,Policy,Approval security
    class Agent,LLM,RAG ai
    class MCP,External,Host,Jobs,DB tool

The API establishes identity and workspace membership before the model sees any tools. The model cannot choose another user or bypass authorization. Membership and role checks run before tool schema exposure, execution, and approved write execution. Documents and tool output are untrusted evidence, not instructions or authorization.

See architecture, security, and connector setup for details.

✨ Features

• Streamed local inference with Ollama; optional OpenAI and Anthropic adapters

• Persistent conversations with complete tool-call history and saved sessions

• Optional planning, cancellation, bounded tool iterations, and visible tool traces

• Workspace-scoped .txt, .md, and .pdf knowledge

• SQLite keyword retrieval for a lightweight local setup

• PostgreSQL full-text + pgvector candidates with reciprocal-rank fusion

• Source names/pages returned with retrieved evidence

• Durable queued ingestion, previews, replacement hashes/version counters, and deletion of indexed chunks

Google reply actions create drafts; SentinelAI does not send email. Calendar event creation may notify attendees and therefore requires exact approval.

• Local bcrypt authentication with access/refresh JWTs and durable logout revocation

• Optional Keycloak OIDC using authorization code flow and S256 PKCE

• Roles for administrator, user, and viewer plus personal/team workspace membership

• Per-user encrypted GitHub and Google credentials

• Exact, expiring, atomic, single-use approval records for external writes

• No automatic retry for destructive/write tools

• Bounded upload size and filename/type checks

• Resolved-path containment for filesystem tools

• Parsed single-SELECT, read-only SQL with timeout and row limits

• HTTP security headers, CORS configuration, and IP-based rate limits

• CodeQL, Dependabot, locked backend dependencies, and security regressions in CI

For limitations and deployment requirements, read SECURITY.md and the production gap analysis.

• Structured JSON logging and request IDs

• Prometheus HTTP/tool metrics and LLM request counts at /metrics

• Tool and approval audit records

• Optional self-hosted Langfuse timing traces without document text or credentials

• 41 backend regression tests on Python 3.11 and 3.12

• Frontend lint, TypeScript, and Next.js production-build checks

• PostgreSQL/pgvector, browser-workflow, and container-build CI jobs

• Deterministic sample retrieval benchmark and knowledge-reliability checks

• Docker images plus a Compose stack for PostgreSQL/pgvector, API, and frontend

The six-case retrieval benchmark is a regression gate, not a production accuracy claim. See the v2.0 validation record.

🚀 Quick Start

Prerequisites

• Python 3.11 or 3.12

• Node.js 22.13+

• Ollama

The default path uses local inference and does not require a paid model API.

1. Clone and install

git clone https://github.com/virinchisai/sentinel-ai.git
cd sentinel-ai
git checkout v2.0.0

python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.lock
pip install --no-deps -e .

cd frontend
npm ci
cd ..

2. Configure local inference

python scripts/configure.py
ollama pull qwen2.5:1.5b

scripts/configure.py safely creates .env. There is no shared demo account or password.

3. Start the API

python -m backend.migrate
uvicorn backend.api.main:app --host 127.0.0.1 --port 8000

Start Ollama separately if it is not already running.

4. Start the frontend

cd frontend
npm run dev

Open http://localhost:3000, register an account, choose a workspace, and upload documents.

Optional hybrid retrieval

ollama pull nomic-embed-text

Set EMBEDDING_MODEL=nomic-embed-text before ingestion, restart, and upload or reindex documents. Use OLLAMA_MODEL to choose a tool-capable model suited to your hardware, then evaluate it with your own data and workflows.

🐳 Docker Compose

python scripts/configure.py  # only when .env does not exist
docker compose --env-file .env -f docker/docker-compose.yml up --build -d

Compose starts PostgreSQL/pgvector, FastAPI, and Next.js. Ollama runs on the host and must be reachable from the API container. Ports bind to loopback by default. For shared access, configure TLS, trusted origins, backups, and private /metrics and MCP access.

Published Linux AMD64 images are also available:

docker pull ghcr.io/virinchisai/sentinel-ai-backend:v2.0.0
docker pull ghcr.io/virinchisai/sentinel-ai-frontend:v2.0.0

Build the frontend with NEXT_PUBLIC_API_URL when the API is not at http://localhost:8000. ARM hosts require emulation or a native build.

⚙️ Configuration

GitHub and Google credentials are added per user in Settings. Use narrowly scoped provider credentials and follow the connector guide.

🧪 Testing

pip install -e '.[dev]'
pytest backend/tests -q
PYTHONPATH=. python scripts/benchmark.py

cd frontend
npm run lint
npm run build

The v2.0 release recorded:

• 41/41 backend tests passed

• 6/6 expected retrieval sources found within the top 3

• frontend lint and production build passed

• PostgreSQL/pgvector isolation and migration checks passed

• API/frontend container builds passed

• registration, login, upload, preview, streaming UI, deletion, and logout passed

Google/OIDC calls and browser streaming are deterministic mocks in CI. A separate local-agent smoke test exercises real Ollama inference and retrieval. No real email, calendar invitation, or GitHub write is sent during the release checks.

See release validation for exact scope and limitations.

🗂️ Repository Tour

sentinel-ai/
├── backend/
│   ├── api/             # FastAPI routes and lifecycle
│   ├── auth/            # Local/OIDC auth, roles, workspaces, audit data
│   ├── agents/          # Providers, orchestration, policy, MCP client
│   ├── rag/             # Parsing, chunking, retrieval, ingestion jobs
│   ├── mcp_server/      # FastMCP server and connector implementations
│   ├── observability/   # Logging, metrics, request tracing
│   └── tests/           # Security and regression tests
├── frontend/            # Next.js 16 / React 19 workspace UI
├── evaluation/          # Deterministic retrieval evaluation data
├── knowledge/           # Provenance-pinned sample knowledge claims
├── knowledge-tests/     # Knowledge-policy expectations
├── docker/              # Backend/frontend images and Compose stack
├── docs/                # Architecture, connectors, operations, validation
├── .github/workflows/   # CI, CodeQL, packaging, knowledge reliability
├── SECURITY.md          # Trust boundaries and vulnerability reporting
└── CHANGELOG.md         # Version history and upgrade notes

🛡️ Security

SentinelAI uses server-side controls rather than model instructions as its security boundary.

Known boundaries

• Single API process and ingestion worker; no multi-replica coordination or HA

• Application-layer workspace isolation without PostgreSQL row-level security

• Browser bearer tokens stored in localStorage

• Mutable application audit records rather than an immutable external ledger

• No exactly-once guarantee across an external write and process crash

• Model-dependent citation and tool-selection quality

• Keycloak, Docling, and Langfuse are optional and not bundled by Compose

Read the production gap analysis for the prioritized hardening roadmap. Report vulnerabilities through GitHub's private security reporting interface—not a public issue.

💼 Why this project matters

SentinelAI demonstrates the work around an AI model that makes an agent useful and controllable: authentication, workspace-scoped retrieval, MCP integration, least-privilege tools, durable approvals, connector credential handling, observability, evaluation, and reproducible delivery.

Built SentinelAI v2.0, a local-first MCP agent workspace integrating GitHub, Gmail, Calendar, read-only SQL, restricted filesystem tools, and workspace-scoped retrieval. Implemented FastAPI authentication/RBAC, per-user encrypted connector credentials, exact single-use write approvals, PostgreSQL full-text + pgvector search, a Next.js 16 interface, 41 backend regressions, retrieval release gates, CodeQL, and tested Docker delivery for a single-worker small-team pilot.

📈 Star History

📜 License

MIT — see LICENSE. Dependencies and model weights retain their own licenses.

Built by Virinchi Sai Athmakuri · LinkedIn · Email

⭐ Star this repo if you find it useful!