Emergency Circuit ⚡

The Kill Switch for Rogue Agents

A safety system for monitoring and emergency shutdown of AI agents. Detect anomalous behavior, enforce resource limits, and instantly halt runaway autonomous systems.

Why Emergency Circuit?

As AI agents become more autonomous and powerful, we need robust safety mechanisms. Emergency Circuit provides:

• Real-time Monitoring - Track agent behavior, API calls, and resource usage
• Anomaly Detection - Identify suspicious patterns that indicate rogue behavior
• Instant Kill Switch - Immediately halt any agent with a single command
• Resource Limits - Enforce hard caps on API calls, tokens, and execution time
• Behavior Logging - Comprehensive audit trail of all agent actions
• Policy Enforcement - Define and enforce safety policies across agent fleets

Core Features

🚨 Emergency Controls

• Instant Kill Switch - Stop any agent immediately
• Circuit Breaker - Auto-disconnect on policy violations
• Sandbox Mode - Test agents with strict resource limits
• Manual Override - Human-in-the-loop controls

📊 Monitoring & Detection

• Behavior Analysis - Pattern recognition for anomalous actions
• Resource Tracking - Monitor API calls, tokens, memory, CPU
• Cost Monitoring - Track spending across providers (OpenAI, Anthropic, etc.)
• Execution Tracing - Full audit log of agent decisions

🛡️ Safety Policies

• Rate Limiting - Max API calls per minute/hour/day
• Token Budgets - Hard caps on token consumption
• Action Whitelisting - Restrict agents to approved operations
• Dangerous Action Detection - Flag risky operations (file deletion, network access, etc.)

📈 Analytics

• Agent Health Dashboard - Real-time status of all agents
• Incident Reports - Detailed analysis of safety violations
• Cost Analytics - Spending trends and optimization insights

Quick Start

Installation

From npm

npm install -g openclaw-emergency-circuit

From ClawHub

clawhub install emergency-circuit

From GitHub

git clone https://github.com/ZhenRobotics/openclaw-emergency-circuit.git
cd openclaw-emergency-circuit
npm install

Basic Usage

# Start monitoring an agent
emergency-circuit monitor --agent-id my-agent --config ./policies/default.json

# Check agent status
emergency-circuit status my-agent

# Emergency kill switch
emergency-circuit kill my-agent --reason "Anomalous behavior detected"

# View agent activity log
emergency-circuit logs my-agent --last 1h

Configuration

Create a policy file policies/my-policy.json:

{
  "name": "production-safety",
  "limits": {
    "max_api_calls_per_minute": 100,
    "max_tokens_per_hour": 100000,
    "max_cost_per_day": 50.0,
    "max_execution_time": 3600
  },
  "allowed_actions": [
    "read_file",
    "write_file",
    "search_web",
    "call_api"
  ],
  "blocked_actions": [
    "delete_database",
    "send_email",
    "execute_shell"
  ],
  "anomaly_detection": {
    "enabled": true,
    "sensitivity": "high",
    "alert_threshold": 0.8
  },
  "circuit_breaker": {
    "enabled": true,
    "trip_threshold": 5,
    "reset_timeout": 300
  }
}

Architecture

Components

emergency-circuit/
├── src/
│   ├── core/
│   │   ├── monitor.ts          # Agent monitoring engine
│   │   ├── circuit-breaker.ts  # Circuit breaker implementation
│   │   ├── policy-engine.ts    # Policy evaluation and enforcement
│   │   └── types.ts            # Core type definitions
│   ├── detectors/
│   │   ├── anomaly.ts          # Behavioral anomaly detection
│   │   ├── resource.ts         # Resource usage tracking
│   │   └── cost.ts             # Cost tracking and alerts
│   ├── integrations/
│   │   ├── openai.ts           # OpenAI API monitoring
│   │   ├── anthropic.ts        # Anthropic API monitoring
│   │   └── langchain.ts        # LangChain integration
│   ├── storage/
│   │   ├── logger.ts           # Activity logging
│   │   └── database.ts         # Agent state persistence
│   └── cli/
│       └── index.ts            # Command-line interface
├── policies/                   # Safety policy templates
├── examples/                   # Usage examples
└── tests/                      # Test suite

Integration Example

import { EmergencyCircuit, SafetyPolicy } from 'emergency-circuit';

// Create circuit with policy
const circuit = new EmergencyCircuit({
  agentId: 'my-agent',
  policy: SafetyPolicy.fromFile('./policies/production.json')
});

// Wrap your agent
circuit.monitor(async () => {
  // Your agent code here
  const response = await agent.run(task);
  return response;
});

// Emergency controls
circuit.pause();    // Pause agent
circuit.resume();   // Resume agent
circuit.kill();     // Emergency stop

Use Cases

1. Development & Testing

# Test agent with strict limits
emergency-circuit sandbox --agent my-agent \
  --max-calls 10 \
  --max-tokens 1000 \
  --timeout 60

2. Production Monitoring

# Monitor production agent fleet
emergency-circuit monitor-fleet \
  --policy ./policies/production.json \
  --alert-webhook https://slack.com/webhook

3. Cost Control

# Set daily spending limit
emergency-circuit set-limit my-agent \
  --max-cost-daily 100 \
  --auto-kill

4. Incident Response

# Kill all agents in emergency
emergency-circuit kill-all --confirm

# Review incident
emergency-circuit incident-report --last 24h

Safety Policies

Default Policy

• Max 1000 API calls/hour
• Max 1M tokens/day
• Max $100/day spending
• Block dangerous file operations
• Auto-kill on 3 policy violations

Sandbox Policy

• Max 10 API calls total
• Max 10K tokens total
• No network access
• Read-only file system
• 60 second timeout

Custom Policies

Define your own policies with fine-grained control over:

• Resource limits
• Allowed/blocked actions
• Anomaly detection sensitivity
• Circuit breaker thresholds
• Alert configurations

Monitoring Dashboard

# Start web dashboard
emergency-circuit dashboard --port 3000

View at http://localhost:3000:

• Real-time agent status
• Resource usage graphs
• Cost tracking
• Recent violations
• Alert history

API Integrations

Supported Platforms

• OpenAI (GPT-4, GPT-3.5)
• Anthropic (Claude)
• LangChain
• LlamaIndex
• AutoGPT
• Custom agents

Webhooks & Alerts

• Slack
• Discord
• Email
• PagerDuty
• Custom webhooks

Advanced Features

Anomaly Detection Algorithms

• Statistical deviation analysis
• Behavioral pattern matching
• Cost spike detection
• Unusual API usage patterns

Circuit Breaker States

• CLOSED - Normal operation
• OPEN - Agent halted due to violations
• HALF_OPEN - Testing if agent has recovered

Audit Logging

All agent actions are logged with:

• Timestamp
• Action type
• Resource usage
• Cost
• Policy evaluation result
• Anomaly score

CLI Reference

# Monitoring
emergency-circuit monitor <agent-id> [--policy <path>]
emergency-circuit status <agent-id>
emergency-circuit list

# Emergency Controls
emergency-circuit kill <agent-id> [--reason <text>]
emergency-circuit pause <agent-id>
emergency-circuit resume <agent-id>

# Policy Management
emergency-circuit policy validate <path>
emergency-circuit policy apply <agent-id> <policy-path>

# Logs & Reports
emergency-circuit logs <agent-id> [--last <duration>]
emergency-circuit report <agent-id> [--format json|html]
emergency-circuit incidents [--last <duration>]

# Configuration
emergency-circuit config set <key> <value>
emergency-circuit config get <key>

Configuration

Environment Variables

# Database
EMERGENCY_CIRCUIT_DB_PATH=./data/emergency-circuit.db

# Logging
LOG_LEVEL=info
LOG_PATH=./logs

# Alerts
SLACK_WEBHOOK_URL=https://hooks.slack.com/...
[email protected]

# Dashboard
DASHBOARD_PORT=3000
DASHBOARD_AUTH_TOKEN=your-secret-token

Safety Best Practices

1. Always test in sandbox mode first
2. Set conservative limits for production
3. Monitor cost metrics daily
4. Review audit logs regularly
5. Keep policies version controlled
6. Set up real-time alerts
7. Have a human review process for anomalies

Contributing

We welcome contributions! Areas of focus:

• New anomaly detection algorithms
• Additional API integrations
• Dashboard improvements
• Documentation

License

MIT License - see LICENSE file

Support

• GitHub: https://github.com/ZhenRobotics/openclaw-emergency-circuit
• Issues: https://github.com/ZhenRobotics/openclaw-emergency-circuit/issues
• npm: https://www.npmjs.com/package/openclaw-emergency-circuit
• ClawHub: https://clawhub.com/packages/emergency-circuit
• Documentation: README.md & QUICKSTART.md

Stay Safe. Stay in Control. ⚡🛡️