sentinelos-agent 1.2.1

The self-improving AI agent — creates skills from experience, improves them during use, and runs anywhere

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

Capability	Description
Local Model Inference	Run Qwen, Holo3, Llama, and other open models via Ollama. No API keys required for local models.
RBAC Governance	Define groups (Engineering, Sales, Legal) with per-group tool policies and model access.
Tool & Model Policies	Allowlist which MCP tools each group can invoke. Whitelist models with privacy badges (local vs. third-party).
Local RAG	Ingest company documents (PDF, text). Chunks are embedded and stored locally in ChromaDB.
Admin Console	Web-based dashboard for group management, model configuration, RAG ingestion, branding, and audit review.
Audit Trail	Chronological log of every administrative and governance action.
Desktop Application	Electron-based chat interface with streaming responses, tool output display, and conversation history.
Agent Runtime	Self-improving agent with skill creation, memory, scheduled automations, and multi-platform messaging.
Default-Deny Security	Fail-closed policy enforcement, timing-safe token auth, local-first data model.

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

Event	Action
User selects Claude OAuth in onboarding	cliproxyapi binary downloaded + config written
Gateway starts with provider: custom:anthropic-oauth	sentinel-billing-proxy + cliproxyapi auto-started
OAuth login (/api/providers/oauth/claude-max/start)	Browser opens Anthropic consent → tokens saved to auth dir
Gateway shutdown	Both sidecars stopped (PID-tracked)

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.

Full Install (OAuth routing stack)

Recommended two-command setup:

pip install sentinelos-agent
sentinel setup

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

sentinel oauth-stack install

This installs SentinelOS plus 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

Symptom	Likely cause	Fix	Logs
Connection error after 3 retries or proxy dead after reboot	sentinel-billing-proxy or sentinel-cliproxyapi service did not load	Re-run ./scripts/install-full.sh; macOS: `launchctl list	grep sentinel; Linux: systemctl --user status sentinel-billing-proxy sentinel-cliproxyapi`
HTTP 404 on /v1/v1/messages	Client base URL already ends in /v1; older proxy did not normalize doubled prefix	Update/re-run installer so scripts/billing-proxy/proxy.js normalizes /v1/v1/ to /v1/	$SENTINEL_HOME/logs/billing-proxy.log
Smoke test skipped	No ~/.cli-proxy-api/claude-*.json OAuth credential	Run cliproxyapi -config ~/.sentinel/cliproxyapi.conf -claude-login, then re-run installer	$SENTINEL_HOME/logs/cliproxyapi.log

Quick Start

See docs/INSTALL.md for full installation instructions.

# 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.