POST-AUTHORIZATION OBSERVABILITY · v0.9.2

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.

Apache 2.0 7 Arsenal Signatures 25/25 Live-Fire Suite 77 API Routes Zero Telemetry
butterclaw — docker compose logs -f
RESEARCH PAPER · ZENODO ARCHIVE October 2026 · CC-BY 4.0 · 19 Pages

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.

THE THREAT MODEL

“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

7-NODE DECOUPLED ARCHITECTURE

The Sentinel Pipeline.

Inspect docs/ARCHITECTURE.md →
Runtime Flow
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

watcher.pymemory_api.py

High-speed daemons tailing raw OS logs and intercepting sub-30ms spatial agent telemetry.

NODE 02

Five-Hemisphere Cognition

GuardianAuditorDreamLoopFleet

Multi-agent reasoning: decisive evaluation, skeptical audit, idle threat synthesis, policy research, and fleet correlation.

NODE 03

Memory & DRIFT Policy

memory_engine.pypolicy_engine.py

Three-tier HOT/WARM/COLD semantic memory substrate paired with a deterministic 3-scope, 15-operator policy engine.

NODE 04

The ButterVault

buttervault.py

Zero-trust Fernet-encrypted credential vault. Fires live HTTP DELETE requests to revoke OAuth tokens globally before atomic local wipe.

NODE 05

Topology & Dispatch

topology_manager.py

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

Docker + Nginx TLS ./dash

Web control panel isolated behind Nginx TLS reverse proxy plus real-time pseudo-TTY terminal dashboard.

NODE 07 NEW IN v0.9 fleet_sentinel.py

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.

COGNITIVE ARCHITECTURE

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.
DETERMINISTIC SIGNATURE ENGINE

Seven sanitizer-aware signatures.

Evaluated in milliseconds before the LLM is ever called. Click any signature row below to inspect example matched payloads.

View default_signatures.json →
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.

RUNTIME POSTURE

Adjustable Paranoia.

Switch levels at runtime without restarting containers. The Sentinel scales with your threat model.

LEVEL 01
Observe

Signatures log & score drift; kinetic responses suppressed.

LEVEL 02
SIGKILL

Process lineage terminated on match. Vault stays sealed.

LEVEL 03
☢️ Gibson

Global HTTP OAuth revocation + atomic Fernet shred.

CREDENTIAL OBLITERATION · BUTTERVAULT

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.

buttervault — gibson sequence
☢️ [VAULT] GIBSON SEQUENCE — INITIATED
→ Dispatching forensic alert to ntfy / Discord... SENT
→ Sending DELETE /applications/{id}/token... 200 OK
→ GitHub OAuth token: REVOKED GLOBALLY
→ Sending POST /oauth2/revoke... 200 OK
→ Google OAuth token: REVOKED GLOBALLY
→ Fernet master key: DERIVING ephemeral wipe key...
→ Local vault entries: SHREDDED (14 records)
→ SQLite DB: ZEROED
[COMPLETE] Credential attack surface eliminated in 1.3s.
OPERATOR INTERFACE

Inside the Sentinel.

Click any screen below to inspect in full resolution.

ButterVault Credential UI
ButterVault credential management — active assassination status

Fernet credential store & Gibson trigger status.

Air-Gapped ntfy Push Alert
Air-gapped ntfy push notification on verdict_critical event

Real-time mobile push dispatch on critical verdict.

25/25 Live-Fire Test Suite
25/25 live-fire test suite — 74+ positive and negative regex cases

74+ positive & negative adversarial test cases.

ARCHITECTURAL COMPARISON

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
DEPLOYMENT

Up in four steps.

Full Deployment Guide (DEPLOYMENT.md) →

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.

bash — quickstart
# 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).

MISSION LOG

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