SentinelOS

Privacy-first enterprise AI workstation. Run large language models locally, govern access with RBAC policies, and give every team a secure, auditable AI assistant — without sending a single prompt to the cloud.

SentinelOS combines a desktop chat application, an enterprise governance layer, a local RAG pipeline, and an admin console into a single deployable stack. Models run on your hardware via Ollama. Every action is logged. Every tool call is policy-gated. Data never leaves your network.

Key Capabilities

Architecture

┌─────────────────────────────────────────────────────────┐
│                     Desktop App                         │
│              (Electron + React + TUI)                   │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────┐
│                  Agent Runtime                          │
│     Skills · Memory · Tools · Subagents · Scheduler     │
├─────────────────────────────────────────────────────────┤
│                Enterprise Layer                         │
│  Auth · Groups · Tool Policies · Model Whitelist · RAG  │
│         Governance · Audit · Config Validation          │
├─────────────────────────────────────────────────────────┤
│                  Admin Console                          │
│        (React SPA ← FastAPI backend @ :18830)           │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────┐
│              Local Model Backend                        │
│           Ollama (Qwen, Holo3, Llama, …)                │
└─────────────────────────────────────────────────────────┘

Desktop App — Electron application providing a chat interface, conversation management, and tool output rendering.

Agent Runtime — Python-based agent with autonomous skill creation, persistent memory, cron-scheduled tasks, subagent delegation, and multi-platform messaging (Telegram, Discord, Slack, CLI).

Enterprise Layer — RBAC identity and governance. Groups define which tools and models each team can access. Policy enforcement is default-deny: if a tool or model isn't explicitly allowed, it's blocked. Auth uses timing-safe token comparison.

Admin Console — React single-page application served by a FastAPI backend. Manages groups, tool policies, model whitelists, RAG document ingestion, organization branding, and audit logs.

Local Model Backend — Ollama provides local inference. Models are pulled once and served from disk. External providers (OpenRouter, OpenAI) are supported but clearly marked with privacy badges.

Claude OAuth Architecture (Pro/Max Subscription)

When a user selects Claude (Pro/Max — OAuth) during onboarding, SentinelOS deploys two local sidecars that chain together to route requests through the user's Anthropic subscription:

┌─────────────────────────────────────────────────────────────────┐
│                     Desktop App / Gateway                      │
│              config: base_url = 127.0.0.1:18802                │
└────────────────────────┬────────────────────────────────────────┘
                         │  POST /v1/messages
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│              sentinel-billing-proxy  (:18802)                   │
│                                                                 │
│  • Billing header injection (CC fingerprint)                    │
│  • System prompt template bypass                                │
│  • Tool name obfuscation (bidirectional)                        │
│  • String trigger sanitization                                  │
│  • Tool description stripping                                   │
│  • Property name renaming                                       │
│  • Full bidirectional SSE + JSON reverse mapping                │
│                                                                 │
│  Zero dependencies · Node.js · loopback-only                    │
└────────────────────────┬────────────────────────────────────────┘
                         │  upstream: 127.0.0.1:8316
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│              CLIProxyAPI sidecar  (:8316)                        │
│                                                                 │
│  • OAuth token storage & auto-refresh                           │
│  • Multi-credential pool (round-robin)                          │
│  • Auth file watcher (hot-reload)                               │
│  • Loopback-only binding                                        │
└────────────────────────┬────────────────────────────────────────┘
                         │  HTTPS  (Bearer sk-ant-*)
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│                    api.anthropic.com                             │
│              Claude Opus / Sonnet / Haiku                       │
└─────────────────────────────────────────────────────────────────┘

Sidecar Lifecycle

File Layout

~/.sentinel/
├── bin/cliproxyapi              # managed binary (auto-downloaded)
├── config/cliproxyapi.yaml      # loopback-only config
├── run/cliproxyapi.pid           # PID tracking
├── logs/cliproxyapi.log          # sidecar logs
scripts/
└── billing-proxy/
    ├── proxy.js                  # sentinel-billing-proxy (zero-dep Node.js)
    └── logs/                     # billing proxy logs

Note: The sentinel-billing-proxy is independent from any third-party routing infrastructure. Each SentinelOS install runs its own instance on loopback.

Quick Start

One command to install on a fresh macOS or Linux machine:

curl -fsSL https://sentinel-agent.nousresearch.com/install.sh | bash

Then configure your API keys and start chatting:

sentinel setup   # interactive wizard — pick a model, set API keys
sentinel         # start chatting

Already have Python/pip? pip install sentinelos-agent && sentinel setup works too.

See docs/INSTALL.md for full installation instructions, enterprise admin setup, and troubleshooting.

Full Install (OAuth routing stack)

When you choose Claude (Pro/Max — OAuth) during sentinel setup, the wizard offers to install the full local routing stack automatically. Advanced/manual equivalent:

sentinel oauth-stack install

This installs two loopback services:

SentinelOS → billing-proxy :18802 → CLIProxyAPI :8316 → Anthropic OAuth

Requirements

• macOS with launchd or Linux with user systemd
• Node.js 18+
• A Claude Pro/Max OAuth login for CLIProxyAPI

The installer is safe to re-run: existing configs are backed up before replacement, and services are unloaded/reloaded cleanly. To remove services without deleting configs or OAuth credentials:

./scripts/install-full.sh --uninstall

OAuth login and smoke test

After services start, the installer checks ~/.cli-proxy-api/claude-*.json. If credentials are missing, interactive terminals can launch:

cliproxyapi -config ~/.sentinel/cliproxyapi.conf -claude-login

When credentials exist, the installer sends a tiny real request through http://127.0.0.1:18802/v1/messages and reports pass/fail.

Troubleshooting

Enterprise Admin Setup

# 1. Run the enterprise setup script
bash sentinel-enterprise/setup.sh

# 2. Start the admin console
SENTINEL_ADMIN_TOKEN=$(cat ~/.sentinel/admin/token) \
  ./venv/bin/python sentinel-enterprise/admin/serve.py

# 3. Open the admin console at http://127.0.0.1:18830

Documentation

• Installation Guide — Prerequisites, setup, configuration
• Admin Guide — Groups, policies, RAG, audit, branding
• Architecture — Component design, data flows, security model

License

This project is licensed under the MIT License — see LICENSE for details.

SentinelOS is a fork of Nous Research Hermes Agent. The original work is copyright © 2025 Nous Research and contributors, licensed under MIT. See the LICENSE file for the full copyright notice.