Carapace

Name: Carapace
Author: jdesl55

@jdesl55

About Carapace

Armor for your AI agent. Carapace is a local-first security system that protects autonomous AI agents from prompt injection and goal drift. It verifies actions against user-defined rules before execution, uses rotating HMAC keys that injected prompts can't forge, re-reads goals e

Basic information

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "carapace": {
      "command": "carapace-mcp",
      "args": []
    }
  }
}

Tools

Security checkpoint. Validates actions against your rules, returns pass/block verdict with rotating key.

Goal journal. Returns your goals, priorities, and constraints. Detects drift by comparing agent activity against configured categories.

Action logger. Records what the agent did, flags unverified sensitive actions.

Security posture summary. Health status, action counts, key rotation timing, drift level.

Session grader. Analyzes all actions against goals, produces a scorecard with grades, highlights, and improvement insights.

Overview

What is Carapace?

Carapace is a local-first security system for autonomous AI agents. It plugs into any MCP-compatible agent (OpenClaw, Claude Code, Codex, and others) and provides security verification, goal anchoring, drift detection, action logging, and session grading — all running on your machine with zero cloud dependencies.

How to use Carapace?

Install via Git and npm, then build the project. Add the server to your agent's MCP configuration (e.g., ~/.config/openclaw/mcp.json) by specifying the path to the built index.js. On first run, Carapace creates ~/.carapace/ with configuration, database, and security secret. Edit ~/.carapace/config.json by hand or use the optional Carapace Dashboard.

Key features of Carapace

Security checkpoint that validates actions against user-defined rules
Rotating cryptographic key (every 30 minutes) to prevent prompt injection hijacking
Goal anchoring that re-reads priorities every 15 minutes to detect drift
Action logger that records all agent activity and flags unverified sensitive actions
Session grader that produces scorecards and actionable insights for agent improvement
Completely local, zero cloud dependencies for core security operations

Use cases of Carapace

Blocking unauthorized spending, messaging, or file deletion by AI agents
Preventing prompt injection attacks where malicious instructions are hidden in emails or web pages
Keeping an agent focused on its original goals and detecting when it wanders off-task
Logging and reviewing every action an agent takes for audit and accountability

FAQ from Carapace

What problem does Carapace solve?

Carapace addresses two critical risks of autonomous AI agents: prompt injection (tricking the agent into executing unauthorized actions) and goal drift (the agent losing focus over time).

How does the rotating key anti-hijacking work?

Every 30 minutes, Carapace generates a cryptographic verification key using a secret that never enters the agent's context window. The real agent has the key; a prompt injection cannot forge it.

What are the dependencies and runtime requirements?

Carapace requires Node.js and runs on any platform where Node.js is available. It uses TypeScript, the MCP SDK, better-sqlite3 for local logging, and HMAC-SHA256 for key verification. It has zero external dependencies for core security operations.

Where does Carapace store data?

All data lives in ~/.carapace/ on the local machine. This includes config.json (security rules, goals), logs.db (action log), .secret (HMAC signing key with 600 permissions), and insights.md (session learnings).

What transport does Carapace use and how does it authenticate?

Carapace communicates over stdio via the Model Context Protocol. The HMAC secret is created with owner read/write permissions only and never enters the agent's context window or is transmitted over any network.