# ClawButler

> OpenClaw Agent governance platform — monitor, approve, and control with full audit trails. Not another agent builder, but the management layer for your OpenClaw Agent ecosystem. Leverages MCP and A2A protocols as the standards layer.

## Docs

- [Documentation Overview](https://clawbutler.cc/docs): Project introduction, core concepts, architecture, and quick start
- [Overview#core-concepts](https://clawbutler.cc/docs#core-concepts): Agent Registry (18 endpoints), MCP Protocol, A2A Interop, HITL Approvals, Audit Trail
- [Features](https://clawbutler.cc/docs/features): All features organized by category — governance, operations, templates & automation, integrations
- [Features#governance](https://clawbutler.cc/docs/features#governance): Unified governance, HITL approvals, audit & compliance, Config Safety V2.0, kill switch
- [Features#operations](https://clawbutler.cc/docs/features#operations): Real-time activity, cost tracking & budget, cron scheduling, analytics, reports
- [Features#templates-automation](https://clawbutler.cc/docs/features#templates-automation): Verified Templates V2.5, Runbooks V3
- [Features#integrations](https://clawbutler.cc/docs/features#integrations): Web Push, data export, runtime host intake, MCP
- [Overview#tech-stack](https://clawbutler.cc/docs#tech-stack): Next.js 15, FastAPI, PostgreSQL 17, Docker Compose
- [Self-Host Deployment Guide](https://clawbutler.cc/docs/self-host): Step-by-step guide to deploy ClawButler on your own infrastructure
- [Ecosystem](https://clawbutler.cc/docs/ecosystem): Curated tools, MCP servers, model providers, and resources
- [MCP Server Guide](https://clawbutler.cc/docs/mcp): Use ClawButler as an MCP server — manage agents from Claude, Cursor, or any AI assistant
- [Compare Plans](https://clawbutler.cc/docs/compare): Community vs Cloud vs Enterprise feature comparison
- [Full Documentation for LLMs](https://clawbutler.cc/llms-full.txt): Complete project documentation optimized for AI consumption

## API

- [OpenAPI Spec](https://clawbutler.cc/api/openapi.json): Machine-readable API specification (Swagger UI at /api/docs) — 185+ endpoints
- [Health Check](https://clawbutler.cc/api/health): Service health endpoint

## Source Code

- [GitHub Repository](https://github.com/Octo-o-o-o/clawbutler): Open-source codebase

## Quick Start

```bash
git clone https://github.com/Octo-o-o-o/clawbutler.git && cd clawbutler
cp deploy/.env.production .env && bash scripts/generate-secrets.sh >> .env
nano .env  # fill in CORS_ORIGINS, AUTH_URL, SMTP_* (optional)
docker compose up -d --build
# Web UI: http://localhost:3000 | API docs: http://localhost:8000/docs
```

## Key Concepts

- **Agent Registry**: Connect and manage OpenClaw Agents. 18 management endpoints with 6-tab structured config.
- **MCP Protocol**: Tool and data connection standard for agent interoperability — databases, APIs, file systems with unified auth.
- **A2A Protocol**: Agent-to-agent communication standard for collaboration and task delegation.
- **HITL Approvals**: Human-in-the-loop approval workflows with risk assessment, cost estimation, batch processing, and allow-once/allow-always decisions.
- **Cost Tracking & Budget**: Per-agent cost attribution with anomaly detection, budget circuit-breakers, and model routing optimization.
- **Audit Trail**: Append-only event log with monotonic sequence IDs, trace chain linking, and automatic PII masking.
- **Kill Switch**: Emergency agent shutdown with upstream propagation, three-state health monitoring, 30-second offline detection.
- **Config Safety V2.0**: Two-layer protection — (1) Per-Agent: immutable snapshots with semantic diff, dry-run rollback preview, save-before-restore, drift detection. (2) Gateway-Level: encrypted `.cbpkg` backup packages for full or scoped restore of entire OpenClaw configuration including all agents, global defaults, and workspace files.
- **Verified Templates V2.5**: Template registry with type-safe variables, deploy preview, post-deploy checks, compatibility matrix.
- **Runbooks V3**: Multi-step automation centered on the OpenClaw-native path, with state machine lifecycle, approvals, verification, and evidence.
- **Agent Scorecard (ARS v2.5)**: Per-agent reliability scoring with evaluation snapshots, quality/cost metrics, session breakdown, and resource group aggregation. Quad-platform: Web, CLI, Mobile, MCP.
- **Runtime Hosts**: Pair a machine, discover Hermes / Claude Code / Codex / OpenClaw instances, batch-add connectors, and sync attach-mode sessions for investigation.

## Tech Stack

- Frontend: Next.js 15, React 19, Tailwind CSS 4, Auth.js v5
- Backend: FastAPI, Python 3.12, SQLAlchemy 2 (async), Alembic
- Database: PostgreSQL 17, Valkey 8 (Redis-compatible)
- Deploy: Docker Compose, Caddy (auto HTTPS)
- Requirements: 2 vCPU, 4 GB RAM, 20 GB SSD minimum