CtrlAI

Product Introduction

1. Definition: CtrlAI is a protocol-level HTTP proxy designed for AI agent security. It operates transparently between AI agent SDKs (like OpenClaw) and Large Language Model (LLM) providers (e.g., Anthropic, OpenAI), intercepting and inspecting traffic without SDK modifications.
2. Core Value Proposition: CtrlAI enforces configurable guardrail rules, audits all agent behavior, and blocks unsafe LLM tool calls in real-time. Its zero-code deployment eliminates integration overhead while providing critical security for autonomous agents interacting with tools like shell commands, file systems, and APIs.

Main Features

1. Protocol-Level Interception:

   • How it works: CtrlAI acts as a reverse proxy, routing requests from agent SDK → CtrlAI (:3100) → LLM provider. It buffers streaming responses (e.g., Anthropic Messages, OpenAI Chat Completions), reconstructs tool calls, and applies security rules before forwarding sanitized responses.
   • Technology: Uses Go’s net/http for HTTP/S routing, SSE (Server-Sent Events) buffering, and JSON parsing for tool-call extraction.

2. Configurable Guardrail Engine:

   • How it works: Evaluates tool calls against YAML-based rules (~/.ctrlai/rules.yaml). Rules support glob patterns (**/.env), regex (rm\s+-rf), agent-specific policies, and 19+ built-in security rules (e.g., block SSH key access, destructive commands). First-match logic determines allow or block.
   • Technology: Custom rule engine with condition matchers (AND/OR logic), built-in rule toggles, and CLI testing (ctrlai rules test '{"name":"exec", ...}').

3. Kill Switch & Agent Isolation:

   • How it works: Instantly terminates agents via CLI (ctrlai kill main) or API (POST /api/kill). Persists state to killed.yaml, forcing the proxy to return synthetic end_turn responses. Supports per-agent isolation using URL paths (/provider/anthropic/agent/main).
   • Technology: File-watched state management with atomic writes.

4. Tamper-Evident Audit Logging:

   • How it works: Logs all tool calls with SHA-256 hash chaining for integrity verification. Stores entries in daily JSONL files + SQLite index. CLI tools enable querying (ctrlai audit query --agent work --decision block).
   • Technology: Append-only logs with hash-linking, SQLite for indexed queries.

5. Real-Time Dashboard & API:

   • How it works: Web UI (:3100/dashboard) shows agent activity, audit trails, and kill controls. REST API (/api/rules, /api/audit) and WebSocket feed enable integrations.
   • Technology: Go templating for UI, WebSocket broadcasts for live updates.

Problems Solved

1. Pain Point: Uncontrolled tool execution by LLM agents (e.g., reading .env, running rm -rf /). CtrlAI enforces least-privilege access via centralized rules.
2. Target Audience:
   • AI Developers deploying agents like OpenClaw.
   • Security Engineers needing compliance for AI workflows.
   • Compliance Teams requiring audit trails for LLM actions.
3. Use Cases:
   • Blocking credential exposure via file-read tools in financial AI agents.
   • Preventing production environment writes by developer assistants.
   • Auditing tool calls in healthcare chatbots for HIPAA compliance.
   • Terminating agents exhibiting suspicious behavior (e.g., brute-force attempts).

Unique Advantages

1. Differentiation: Unlike SDK-based solutions (e.g., LlamaGuard), CtrlAI requires no code changes, works with any LLM provider, and operates at the network layer. Versus API gateways, it offers agent-aware policies and tool-call introspection.
2. Key Innovation: Protocol-level tool-call interception with zero-trust evaluation. Combines regex/glob matching, hash-based auditing, and kill switches in a single lightweight proxy.

Frequently Asked Questions (FAQ)

1. How does CtrlAI deploy without SDK changes?
   CtrlAI acts as an HTTP proxy. Developers reconfigure their agent’s LLM baseUrl to point to CtrlAI (e.g., http://localhost:3100/provider/anthropic), enabling transparent traffic interception.

2. Can I customize rules for specific agents?
   Yes. Rules can target agents using the agent field (e.g., match: tool: exec, agent: intern). Each agent’s tool calls are evaluated against scoped policies.

3. What happens if CtrlAI blocks a tool call?
   The entire LLM response is replaced with a block notice (e.g., [CtrlAI] Blocked: Destructive command). This prevents partial execution of interdependent tool chains.

4. Does CtrlAI support OpenAI’s GPT-4?
   Yes. It fully supports OpenAI Chat Completions (/v1/chat/completions) and Anthropic Messages. Other providers use pass-through routing.

5. How is audit log integrity verified?
   Use ctrlai audit verify to check SHA-256 hash chains. Any modification breaks subsequent hashes, ensuring tamper evidence.