How it Works
This design ensures that every proposed action—such as executing a shell command, modifying a file, or invoking a tool—is evaluated against predefined policies before execution. The process unfolds in three key stages: interception, enrichment, and evaluation.
During interception, Cupcake captures the agent’s proposed action, including tool calls or file operations. Enrichment follows, where Cupcake gathers real-time contextual signals from the environment, such as the current Git branch, CI/CD pipeline status, or database metadata. Finally, the action and associated signals are packaged into a structured JSON input, which is then evaluated against policies compiled to WebAssembly (Wasm) for deterministic and high-performance decision-making.
Cupcake supports two evaluation models to accommodate varying governance needs. The first is deterministic policies, where rules are authored in Open Policy Agent (OPA) Rego and compiled to Wasm. This approach ensures consistent, sub-millisecond evaluation times, as policies are sandboxed and executed independently of the agent’s runtime. The second model leverages an LLM-as-Judge mechanism, where a secondary language model or agent dynamically evaluates actions when static rules prove insufficient. This hybrid approach allows for adaptive oversight, particularly in scenarios where agent behavior may be ambiguous or context-dependent.
Once evaluation completes, Cupcake returns one of five possible decisions to the agent runtime, each accompanied by a human-readable explanation. These decisions include Allow, where the action proceeds optionally with contextual guidance; Modify, where the action is adjusted (e.g., sanitized commands or added safety flags); Block, where the action is halted with a rationale for self-correction; Warn, where the action proceeds but triggers a logged alert; and Require Review, where the action pauses pending human approval.
A defining feature of Cupcake’s architecture is its separation of policies by agent harness. Policies are organized in harness-specific directories (e.g., policies/claude/, policies/cursor/), ensuring clarity and access to harness-native capabilities. This structure avoids normalization layers, allowing policies to directly interface with the unique event formats of supported harnesses like Claude Code, Cursor, Factory AI, and OpenCode. For unsupported harnesses, integration is contingent on the harness providing runtime hooks for event interception.
Cupcake also extends support to JavaScript-based agent frameworks through native bindings, enabling integration with web-centric tools such as LangChain, Google ADK, NVIDIA NIM, and Vercel AI SDK. This flexibility ensures that policy enforcement can be applied across diverse agent ecosystems, from CLI-based harnesses to browser-based development environments. The bindings are distributed via a TypeScript package (cupcake-ts), facilitating seamless adoption in JavaScript-centric workflows.
The system’s performance is optimized for low latency, with cached policies achieving sub-millisecond evaluation times in typical deployments. Additionally, Cupcake generates structured logs and evaluation traces for all inputs, signals, and decisions, enhancing observability and debugging capabilities.
Installation and development are streamlined through Nix-based workflows, where Cupcake can be installed via a flake or development shell. The project also provides official release scripts for Unix/macOS and Windows PowerShell, with SHA256 checksums for verification. This modular approach ensures that users can deploy Cupcake with minimal friction while maintaining control over policy enforcement.
Cupcake’s development is supported by EQTYLab, with contributions from Trail of Bits for agentic safety research. The project adheres to the Apache 2.0 license, fostering permissive adoption in both open-source and enterprise environments. Contributions are welcome, with guidelines documented in CONTRIBUTING.md, and the roadmap for future features is scheduled to be published in Q1 2026.
Use Cases
Cupcake addresses a critical gap in AI agent governance: the enforcement of operational and security rules without consuming model context or degrading performance. Traditional approaches often embed governance logic within agent prompts or rely on post-hoc monitoring, both of which introduce inefficiencies and inconsistencies. Cupcake mitigates these challenges by externalizing policies into a dedicated enforcement layer, ensuring rules are applied deterministically and in real time.
One primary use case is granular tool control, where Cupcake prevents agents from executing dangerous or unauthorized operations. For example, policies can block commands like rm -rf / or restrict access to sensitive tools based on contextual signals such as branch protection rules or CI status. This capability is particularly valuable in collaborative environments where multiple agents may interact with shared repositories or infrastructure. By intercepting tool calls before execution, Cupcake reduces the risk of accidental or malicious actions while maintaining agent autonomy.
Another key application is Model Context Protocol (MCP) governance, where Cupcake enforces policies on tools adhering to the MCP standard (e.g., mcpmemory*, mcpgithub*). MCP tools are designed to interact with external systems in a structured manner, but their usage must align with organizational policies. Cupcake evaluates MCP tool invocations against predefined rules, ensuring compliance with access controls, data retention policies, or audit requirements.
Cupcake also excels in reactive automation, where policies trigger actions in response to agent behavior without relying on the agent itself. For instance, a policy could automatically lint a modified file after an edit, enforce coding conventions, or generate compliance reports. This functionality is enabled by Cupcake’s event-driven architecture, which evaluates actions against policies and executes secondary workflows when violations occur. Such automation reduces manual oversight while maintaining consistency in operational processes.
For enterprises, Cupcake provides enterprise-ready controls that align with security and compliance frameworks. Policies can be tailored to enforce internal guidelines (e.g., those documented in CLAUDE.md or AGENT.md) or external regulations, ensuring agents adhere to both technical and organizational standards. The ability to timeout or block repeat offenders further enhances security posture by isolating misbehaving agents.
The LLM-as-Judge feature extends Cupcake’s capabilities into dynamic governance scenarios. When static policies are insufficient—such as when an agent’s behavior is ambiguous or context-dependent—a secondary LLM or agent can intervene to evaluate the action’s appropriateness. For example, an LLM-as-Judge could assess whether an agent’s proposed code change aligns with architectural principles or ethical guidelines, providing a layer of adaptive oversight.
Cupcake’s support for guardrail libraries further enhances its utility in content and safety checks. Integrations with tools like NeMo and Invariant allow policies to incorporate pre-built guardrails for detecting harmful content, bias, or non-compliance with safety standards. These libraries can be seamlessly embedded into harness-specific policies, ensuring consistent enforcement across diverse agent workflows.
Finally, Cupcake enables proactive warnings and feedback loops that improve agent performance over time. Similarly, blocked actions include detailed explanations, enabling agents to self-correct and learn from policy violations. This feedback mechanism fosters a culture of compliance while reducing the cognitive load on human reviewers.
Key Features & Capabilities
Cupcake’s core functionality revolves around deterministic policy enforcement, where rules written in OPA/Rego are compiled to WebAssembly for fast, sandboxed evaluation. The use of Wasm also enhances security by isolating policy logic from the host system, reducing the risk of exploits or unintended side effects. Policies are authored in a declarative syntax, making them accessible to developers familiar with governance-as-code principles.
A standout capability is multi-harness support, with native integrations for Claude Code, Cursor, Factory AI, and OpenCode. Each harness integration is optimized for its event format, ensuring policies can access harness-specific features without abstraction layers. For example, a policy for Cursor may enforce file edit conventions, while a policy for Claude Code could govern shell command execution. This granularity allows organizations to tailor governance rules to the unique capabilities of each agent harness, maximizing both flexibility and control.
Every policy evaluation generates structured logs and traces, capturing inputs, signals, and decisions in a machine-readable format. The structured nature of the logs also simplifies forensic analysis, enabling rapid incident response when policy violations occur.
The platform’s granular tool control extends beyond basic blocking or allowing actions. Policies can modify tool arguments, inject safety flags, or enforce conventions before execution. For instance, a policy might sanitize a shell command by removing dangerous flags or redirect output to a secure log location.
Support for Model Context Protocol (MCP) tools is another differentiator, as Cupcake natively governs interactions with MCP-compliant tools such as memory or GitHub integrations. Cupcake evaluates MCP tool calls against customizable rules, ensuring compliance with access controls, data handling requirements, or audit trails. This integration is seamless, as Cupcake’s event interception mechanism is designed to handle MCP tool events by default.
The LLM-as-Judge feature introduces a dynamic layer to policy enforcement, where a secondary LLM or agent evaluates actions that static rules cannot address. For example, an LLM-as-Judge could assess whether an agent’s proposed API call aligns with rate limits or service-level agreements, providing a more nuanced evaluation than predefined rules.
Cupcake also includes guardrail libraries for content and safety checks, with first-class integrations for tools like NeMo and Invariant. These libraries provide pre-built policies for detecting harmful content, bias, or non-compliance with ethical guidelines.
The system’s enterprise-ready controls include features such as allow/deny/review workflows, audit trails, and proactive warnings. For example, the Require Review decision pauses an action until a human approves it, ensuring critical operations are not automated without oversight. Similarly, audit trails capture all policy evaluations, enabling retrospective analysis of agent behavior for compliance reporting.
Performance is a critical aspect of Cupcake’s design, with sub-millisecond evaluation times for cached policies in typical deployments. This speed is achieved through the use of WebAssembly-compiled policies, which execute independently of the agent’s runtime. The separation of policies from model context also prevents token consumption, ensuring that governance rules do not impact agent performance or responsiveness.