Cupcake is a policy-enforcement layer that sits between AI agent runtimes and their actions, ensuring that tool calls and commands follow user-defined rules written in OPA/Rego and compiled to WebAssembly. It acts as an MCP (Model Context Protocol) server, exposing policy evaluation capabilities for harness integrations such as Claude Code, Cursor, Factory AI, and OpenCode. By intercepting proposed actions, enriching them with real-time signals, and evaluating them against Wasm policies, Cupcake can allow, modify, block, warn, or require human review of actions before they reach the agent runtime. This yields deterministic rule-following, improved security, and the ability to push governance decisions out of the agent’s context. The server supports both deterministic policy evaluation (Rego-to-Wasm) and an LLM-as-Judge mode for oversight, making it suitable for environments that demand strict guardrails as well as flexible oversight.

Prerequisites:

• Node.js (recommended) or a containerized runtime if running via docker
• Access to the repository hosting Cupcake (clone or install from npm)

Option A: Install via npm (recommended for Node.js projects)

1. Install the package globally or in your project: npm install -g cupcake@latest

   or in your project: npm install cupcake@latest

2. Start the Cupcake MCP server (example used if installed locally): npx cupcake start
3. Verify the server is listening on the configured port (default 3000).

Option B: Run from source (Node.js)

1. Clone the repo: git clone https://github.com/eqtylab/cupcake.git
2. Navigate to the project and install dependencies: cd cupcake npm install
3. Run the server: node server.js
4. Ensure the server exposes the MCP API on the expected port (default 3000).

Option C: Docker (if provided)

1. Build or pull the Cupcake image from the repository: docker pull eqtylab/cupcake:latest
2. Run the container (example): docker run -d -p 3000:3000 --name cupcake eqtylab/cupcake:latest
3. Confirm the MCP API is accessible at http://localhost:3000/

Note: Adjust PORT and other environment variables as needed for your deployment environment. See additional_notes for environment variable details.

Environment variables and configuration tips:

• PORT: Port on which the MCP server listens (default 3000).
• LOG_LEVEL: Logging verbosity (e.g., debug, info, warn, error).
• MCP_LOG_DIR: Directory for structured evaluation traces and logs.
• Ensure the policy modules (OPA/Rego compiled to Wasm) are available to the server at runtime.
• When integrating with multiple harnesses, provide clear policies per harness under policies/ directories (e.g., policies/claude/, policies/cursor/, policies/factory/, policies/opencode/).
• Common issues: port conflicts, missing policy WASM modules, or misconfigured environment variables leading to initialization failures. Check logs for policy evaluation errors and ensure Wasm modules are correctly compiled and loaded.
• If you need to customize the default actions, you can tune the decision behavior (Allow, Modify, Block, Warn, Require Review) via policy definitions and, where supported, by binding contextual hints to responses.