akita-sentinel 0.2.19

Akita Sentinel — local AI agent monitoring. Watch your agents, scan new skills before they run.

Know what your AI agent just did.

AI agents install tools, read files, make API calls, and run code on your machine.
Most people have no idea what those tools actually do.

Akita watches every tool call your agent makes, scans new skills before they run, and blocks the dangerous ones.

---

Install

pip install akita-sentinel
akita sentinel start

That's it. On first run the sentinel bootstraps itself:

• Registers autostart at login (HKCU Run on Windows, LaunchAgent on macOS, systemd user unit on Linux)
• Creates a desktop launcher icon
• Brings up the tray icon (macOS + Windows; opt-in via --tray on Linux)
• Stays current automatically — update.auto_update is on by default

Akita discovers your agent frameworks, watches their skill directories, and starts scanning. Your agents never know it's there.

No need for a separate akita install step — akita install still exists if you want to re-run the bootstrap explicitly. Headless? akita sentinel start --no-tray. Pin a version? akita config set update.auto_update false. Don't want autostart? akita sentinel disable-autostart.

---

What You Get

Dashboard — real-time agent status, recent activity, and system health at a glance.

Governance Rules

Define what your agents can and can't do. Rules are enforced automatically — the most dangerous actions are blocked before they execute.

26 built-in rules covering file access, network calls, money transfers, destructive operations, and more.

Trust Center

See exactly which governance rules protect each agent and skill. Connection map shows the relationship between your agents, their skills, and the rules that guard them.

Skills Library

Browse and manage every skill your agents have access to. Risk scores, metadata, and scan results in one place.

Agent Management

Monitor connected agents, test connections, and see protection status for each framework.

---

Why Akita?

Problem	How Akita Helps
New skill installed silently	Immediate detection + risk scan
Agent calls a suspicious tool	Hook-based governance (blocking for Hermes; advisory alerts for other frameworks)
No audit trail of agent activity	Local audit log with 30-day retention
Credentials scattered in plaintext files	OS keychain storage (macOS Keychain, Windows Credential Locker)
Different agents, different configs	Single sentinel monitors all your agent frameworks

Features

• Auto-discovery — detects installed agent frameworks automatically
• Skill scanning — new or modified skills are scanned before they run
• Governance enforcement — Hermes hook-based blocking for governed tool calls (requires hook to be installed; advisory alerts for other frameworks)
• 26 built-in rules — file access, network calls, money transfers, destructive operations, off-hours gates, and more
• Trust center — visual map of which rules protect which agents and skills
• Local audit log — every event logged to ~/.akita/audit.db with 30-day retention
• OS keychain — credentials stored in macOS Keychain, Windows Credential Locker, or Linux SecretService (requires libsecret)
• Cloud pairing — pair with your Akita account for governance rules and remote visibility
• Cross-platform — macOS and Windows with native system tray; Linux on X11/Wayland desktop environments with D-Bus support
• Start at login — one command to auto-start on boot (launchd / Registry Run / systemd)

How It Works

┌──────────────────────────────────────────────┐
│  Your Machine                                │
│                                              │
│  ┌───────────┐         ┌──────────────────┐  │
│  │  Hermes   │────────▶│   Tool Call      │  │
│  │  (agent)  │         └──────────────────┘  │
│  └───────────┘                               │
│       │ hooks                                │
│       ▼                                      │
│  ┌──────────────────┐                        │
│  │  Akita Sentinel  │──▶ Scan new skills     │
│  │  (background)    │──▶ Block or allow      │
│  │                  │──▶ Local audit log     │
│  └────────┬─────────┘                        │
│           │                                  │
└───────────┼──────────────────────────────────┘
            │ paired
┌───────────▼─────────────────────────────────┐
│  Akita Cloud                                │
│  (governance rules, remote visibility)      │
└─────────────────────────────────────────────┘

The sentinel hooks into the framework's tool-call pipeline and watches skill directories. Your agent runs normally while Akita monitors from the side.

Supported Frameworks

Framework	Status
Hermes	Supported — hook-based governance
Claude Code	Coming soon
Cursor	Coming soon

Adding a new framework requires a discovery config + hook adapter.

Commands

Command	Description
akita sentinel start	Start watching your agents
akita sentinel stop	Stop the sentinel
akita sentinel status	Check health and watched agents
akita sentinel events	View recent audit log
akita sentinel pair	Pair with your Akita account
akita sentinel unpair	Remove pairing
akita sentinel enable-autostart	Auto-start at login
akita frameworks check	Detect installed frameworks
akita tray start	Start with tray icon and notifications
akita update	Update to latest version
akita config show	Show configuration
akita config set <key> <val>	Set a config value
akita uninstall	Completely remove Akita Sentinel

System Tray

The live status icon and notification popups are bundled — akita sentinel start brings them up automatically on macOS and Windows. Linux users can opt in with akita sentinel start --tray. Suppress with --no-tray.

Icon	Meaning
Blue shield	Watching — all clear
Blue + amber dot	Scanning a new skill
Amber shield	Warning — suspicious skill detected
Red shield	Suspicious activity detected
Grey shield	Stopped

Configuration

Settings live in ~/.akita/config.yaml:

akita config show                                        # show current settings
akita config set update.check_interval_hours 12         # check every 12 hours
akita config set update.auto_update true                # auto-install updates
akita config set registration.base_url https://my.url   # set Akita server URL

Auto-update downloads and installs from PyPI using pip. Review the changelog before enabling in security-sensitive environments.

Start at Login

akita sentinel enable-autostart          # headless
akita sentinel enable-autostart --tray   # with tray icon
akita sentinel disable-autostart         # remove

Platform	Method	Location
macOS	launchd Launch Agent	~/Library/LaunchAgents/io.plugpipe.akita-sentinel.plist
Windows	Registry Run key	HKCU\Software\Microsoft\Windows\CurrentVersion\Run
Linux	systemd user service	~/.config/systemd/user/akita-sentinel.service

Security

• OS keychain for credential storage — no plaintext secrets on disk
• Automatic keychain migration from file-based credentials on first access
• Unix socket IPC with owner-only permissions (0600)
• Cryptographically random single-use pairing codes
• Signed governance tokens (JWT, JWKS-validated) for cloud enforcement
• Atomic file writes to prevent partial-state corruption
• TLS certificate verification on all outbound connections
• Path traversal guards on all filesystem operations
• Symlink protection (O_NOFOLLOW) on security-sensitive file reads

Files

Path	Description
~/.akita/audit.db	Local audit log (SQLite, 30-day retention)
~/.akita/sentinel.sock	IPC socket (owner-only)
~/.akita/config.yaml	User configuration
~/.akita/credentials.json	Credentials (migrated to keychain on first access)

Uninstall

akita uninstall              # interactive confirmation
akita uninstall --confirm    # non-interactive

This stops the daemon, removes governance hooks from agent settings, disables autostart, clears OS keychain credentials, and deletes ~/.akita/. Then run pip uninstall akita-sentinel to remove the package.

Use --keep-data to preserve ~/.akita/ (audit log, config, sentinel ID) for re-installation. Use --keep-keychain to keep credentials in the OS keychain.

Developer Install

git clone https://github.com/PlugPipe/akita-sentinel.git
cd akita-sentinel
pip install -e ".[dev,tray]"
pytest tests/ -x -v

License

MIT — see LICENSE.

Little Snitch is a registered trademark of Objective Development Software GmbH. Not affiliated.

Links

• Akita — Personal AI agent hub
• PlugPipe — AI-native infrastructure

---

Detection Accuracy Notice

No detection system is perfect. Akita Sentinel layers rule-based, heuristic, signature, behavioural-contract, allow/deny-list, and audit-logging techniques to reduce prompt-injection and tool-misuse risk — but it will miss some threats and may flag some safe activity. The software is provided "AS IS" / "AS AVAILABLE" with no warranty. By installing it you accept the residual risk; first-run requires explicit acknowledgement of the detection disclaimer. Full disclaimer also available via the tray menu > Detection Disclaimer.