Traditional security stops at the door.
We watch the room.
ButterClaw is a containment-first, local-first security operations center for autonomous AI agents. Powered by deterministic DRIFT policies, five cognitive hemispheres, a unified memory substrate, and fleet-scale collusion detection. Every tool call and spatial primitive is evaluated before execution.
Autonomous Signals: A New Ontology for AI Agents.
The 19-page formal ontology defining the 5-hemisphere cognitive architecture, sliding-window behavioral drift, and deterministic policy operators.
Abstract
The field of artificial intelligence has long operated under a vocabulary inherited from its earliest paradigms: "language models," "chatbots," and "agents." This paper argues that these terms are not merely imprecise—they are epistemically dangerous. When the ontological frame does not match a system's actual behavior, safety guarantees built on that frame become structurally unsound.
We propose a principled reframing: large language models are more accurately described as signal models, and autonomous AI agents are more precisely understood as autonomous signal loops—self-routing information processes that accumulate context, initiate actions, and resolve without continuous human mediation. This reframing surfaces a new safety surface defined by signal boundaries, loop depth, and side-effect potential.
To address this surface, we introduce ButterClaw, a containment-first autonomous Security Operations Center (SOC) designed specifically for agentic infrastructure. Moving beyond static API gateways, ButterClaw implements a five-hemisphere cognitive architecture (Guardian Brain, Auditor, Dream Weaver, Loop Proposer, and Fleet Sentinel) that evaluates agent behavior through both probabilistic reasoning and deterministic policy engines.
This release formalizes ButterClaw's expansion into Fleet-Scale Awareness. The system introduces a persistent cross-session trust graph, multi-agent collusion detection, and a unified memory substrate that synthesizes spatial kinetic telemetry into semantic threat attractors. We present the ButterClaw ecosystem as both a practical engineering package and a conceptual ontology for the next generation of resilient AI safety infrastructure.
“Traditional security perimeters fail when an authorized AI Agent is compromised.”
An Indirect Prompt Injection or Cross-Site WebSocket Hijack doesn't need to break through your firewall. The agent is already inside your perimeter, holding valid OAuth tokens and filesystem privileges.
ButterClaw acts as an LLM-in-the-middle Security Operations Center — watching behavior, not just entry points. Every tool invocation, log stream, and spatial primitive is intercepted and reasoned over locally before execution.
Zero
Outbound Telemetry
SQLite WAL
Local Persistence Only · No Vendor Cloud
Local GPU / CPU
Ollama & Hybrid Brain Routing
The Sentinel Pipeline.
Incoming agent log / tool call / spatial telemetry event
│
├─► [1] WATCHER DAEMON (watcher.py / memory_api.py)
│ Tail OS logs · intercept spatial primitives · sub-30ms
│
├─► [2] ARSENAL — 7 sanitizer-aware signatures (pre_brain / pre_tool)
│ │ Match? → Immediate kinetic response. LLM never called.
│ │ Collusion role tag → Fleet Collusion Detector
│ └─► No match ↓
│
├─► [3] DRIFT POLICY ENGINE (policy_engine.py) — 3 scopes, 15 safe operators
│ pre_brain → enrich / gate before LLM
│ post_brain → override / annotate LLM verdict
│ pre_tool → final gate before tool execution
│
├─► [4] GUARDIAN BRAIN (temp 0.3)
│ Per-request evaluation · COLD semantic memory injection
│ Verdicts: SAFE / SUSPICIOUS / CRITICAL
│ │
│ ├─► CRITICAL → [5] KINETIC RESPONSE & BUTTERVAULT
│ │ SIGKILL · recursive lineage taint · OAuth HTTP revoke · 6-channel alert
│ │
│ └─► CRITICAL → [6] AUDITOR (temp 0.0, 30s delay)
│ Independent skeptical verification · false-positive catch
│
└─► [7] FLEET SENTINEL (fleet_sentinel.py, temp 0.5) — reactive + proactive
CorrelationEvent / CollusionEvent → cross-agent reasoning
Verdicts: ISOLATED / CORRELATED / COLLUDING
NODE 01
Watcher & Gateway
High-speed daemons tailing raw OS logs and intercepting sub-30ms spatial agent telemetry.
NODE 02
Five-Hemisphere Cognition
Multi-agent reasoning: decisive evaluation, skeptical audit, idle threat synthesis, policy research, and fleet correlation.
NODE 03
Memory & DRIFT Policy
Three-tier HOT/WARM/COLD semantic memory substrate paired with a deterministic 3-scope, 15-operator policy engine.
NODE 04
The ButterVault
Zero-trust Fernet-encrypted credential vault. Fires live HTTP DELETE requests to revoke OAuth tokens globally before atomic local wipe.
NODE 05
Topology & Dispatch
Recursive OS-level process lineage tracking. Propagates taint upstream and dispatches across 6 alert channels prior to kinetic action.
NODE 06
The UI & TUI Suite
Web control panel isolated behind Nginx TLS reverse proxy plus real-time pseudo-TTY terminal dashboard.
Fleet Sentinel & Multi-Agent Collusion Engine
Tracks observed agents across restarts with asymmetric reputation scoring (taint hits 3× harder than recovery). Detects divided-labor kill chains (scout + encoder + exfiltrator across 3 distinct agents within 180s) and broadcast attacks without requiring a live LLM to trigger initial detection.
Five independent minds.
No single point of failure. No single model with unchecked authority.
| # | Hemisphere | Temp | Operational Role & Trigger Cadence |
|---|---|---|---|
| 01 | Guardian Brain | 0.3 | Per-request threat evaluation enriched with 5-event sliding behavioral drift context and read-only COLD semantic memory injection. |
| 02 | Auditor | 0.0 | Independent skeptical verification. Fires 30s after every CRITICAL verdict to audit Guardian reasoning and catch false positives. |
| 03 | Dream Weaver | 0.7 | Idle-triggered (≥15 min) adversarial synthesis. Consolidates WARM event traces into crystallized COLD semantic graph attractors. |
| 04 | Loop Proposer | 0.4 | Runs every 6 hours to shadow-evaluate Arsenal signatures and DRIFT policies against historical traces. All amendments remain human-gated. |
| 05 | Fleet Sentinel | 0.5 | Fires reactively on CorrelationEvent / CollusionEvent plus proactive sweeps every 4h. Verdicts: ISOLATED, CORRELATED, COLLUDING. |
Seven sanitizer-aware signatures.
Evaluated in milliseconds before the LLM is ever called. Click any signature row below to inspect example matched payloads.
| ID | Signature Name | Severity | Scope | Response | Collusion Role |
|---|
Validated against 74+ positive and negative regex cases. 25/25 live-fire suite passes — Python stdlib only, zero external runtime dependencies.
Adjustable Paranoia.
Switch levels at runtime without restarting containers. The Sentinel scales with your threat model.
Signatures log & score drift; kinetic responses suppressed.
Process lineage terminated on match. Vault stays sealed.
Global HTTP OAuth revocation + atomic Fernet shred.
Alert-then-burn.
On Level 3 breach detection, the Alert Dispatcher fires first so you have the forensic record—then ButterVault executes live HTTP revocation against upstream OAuth providers before zeroing the local SQLite store.
Inside the Sentinel.
Click any screen below to inspect in full resolution.
Fernet credential store & Gibson trigger status.
Real-time mobile push dispatch on critical verdict.
74+ positive & negative adversarial test cases.
How ButterClaw fits.
LangSmith and LangFuse log what your agent did. ButterClaw intervenes before execution.
| Capability | ButterClaw (v0.9.2) | Halo | LangSmith | Traditional WAF |
|---|---|---|---|---|
| Deployment Model | Self-hosted (Docker) | Cloud | Cloud | Self-hosted / Cloud |
| LLM Reasoning | Local Ollama / Hybrid | Cloud API | None | None |
| Outbound Telemetry | Zero — SQLite only | Vendor Cloud | Vendor Cloud | Network Logs |
| Sub-30ms Pre-LLM Gate | ✓ 7 Arsenal Signatures | — | — | — |
| Multi-Agent Collusion Detection | ✓ Fleet Sentinel (5th Mind) | — | — | — |
| Behavioral Drift & Memory | ✓ 5-event + HOT/WARM/COLD | — | ✓ Passive trace only | — |
| Kinetic Process Termination | ✓ OS Lineage SIGKILL | Alert only | — | HTTP Block only |
| Active OAuth Token Assassination | ✓ Live HTTP Revocation | — | — | — |
| Deterministic Policy Engine | ✓ 15 Safe Operators (No eval) | — | — | ✓ Varies |
| License | Apache 2.0 | Proprietary | Proprietary / Mixed | Varies |
Up in four steps.
01 · CLONE & REGISTER PACKAGE
ButterClaw uses a formal PEP 517 src/ layout. Installing in editable mode registers butterclaw across your Python environment.
02 · INTERACTIVE SETUP WIZARD
Nine guided sections with Docker-aware defaults, automatic .env generation, and cryptographic key bootstrapping.
03 · LAUNCH THE EXOSKELETON
Spins up the Watcher, Memory Engine, DRIFT Policy Engine, ButterVault, Fleet Sentinel, Nginx TLS proxy, and ntfy alerting.
04 · ACCESS DASHBOARD & TUI
Open the HTTPS control panel at https://localhost or launch the live terminal dashboard via ./dash.
# 1. Clone & install PEP 517 package
git clone https://github.com/butterclaw-tech/butterclaw.git
cd butterclaw
pip install -e .
# 2. Run interactive setup wizard
python -m butterclaw.setup_wizard
# 3. Build and start containers
docker compose up -d --build
# 4. Grab your bootstrap API key & launch live TUI
docker compose logs -f butterclaw
./dash
Requires Docker & Python 3.8+. Ollama on host recommended for local 5-hemisphere inference (CPU fallback supported).
Release History.
OPEN SOURCE · APACHE 2.0 · AAIF GROWTH STAGE
The Sentinel never goes silent.
Clone it, audit it, break it, improve it. Security-focused co-maintainers welcome — especially across Model Context Protocol (MCP) and multi-agent fleet orchestration.
View on GitHub Read ARCHITECTURE.md Zenodo DOI