How Custodian-Kernel Works
Custodian-Kernel is a provider-neutral policy and evidence kernel designed to govern AI agent actions without relinquishing control. It operates as an intermediary between the agent and its environment, evaluating proposed actions against predefined rules. The kernel does not depend on a specific AI model or harness, making it adaptable to various frameworks such as OpenAI Codex, Claude Code, and Hermes Agent. Each integration—Codex Guard, Claude Guard, Hermes Guard, and Talaria—shares the same decision engine, receipt chain, and credential broker, ensuring consistency across different environments.
The kernel enforces a unified decision boundary across multiple domains, including filesystem operations, shell commands, network access, credential usage, financial transactions, and attempts to modify its own policies. Every action proposed by an agent is assessed for compliance with these rules. The kernel then assigns a verdict—autonomous execution, operator approval required, or block—and records the decision in a tamper-evident ledger. This ledger stores metadata such as the authority band, reason for the decision, and an authenticated receipt, ensuring transparency and accountability without exposing sensitive data like credentials or tool results.
The decision-making process begins when an agent proposes an action. Mandatory guards inspect the tool, arguments, scope, and policy to determine the appropriate response. If the action is deemed safe and within policy, it executes autonomously. If operator approval is required, the agent pauses until explicit, authenticated consent is granted. Approvals are single-use and expire, binding the tool, action class, arguments, workspace, requester, and policy version. Any modification to the action necessitates a new decision. Actions that violate boundaries are blocked immediately, with a reason provided.
The kernel itself does not import harness adapters or payment vendor SDKs directly, adhering to a defense-in-depth security model rather than relying on operating-system sandboxes. This design ensures that the kernel’s guarantees depend on the harness routing actions through the enforcement boundary and on protecting operator state from the agent. The kernel’s state, including personal control-plane data and workspace-specific policies, is stored in designated directories (e.g., ~/.custodian, ~/.paladin) and preserved during upgrades or uninstallation.
The kernel’s control plane includes commands for diagnostics, health checks, and operator interactions. For example, custodian doctor and custodian health --format json provide system status, while custodian console offers a live view of pending approvals, blocked actions, and policy enforcement. Gates can be configured to operate in open or protected modes, where open mode permits configured actions while retaining receipts, and protected mode requires approval for consequential actions. Gate rules can target specific harnesses, tools, workspaces, or action classes, allowing granular control over agent behavior.
Paladin, an encrypted credential broker included with the kernel, manages sensitive data such as API keys or tokens. Agents reference credentials using identifiers like paladin://githubtoken instead of receiving raw values, which are resolved at runtime by Paladin. Grants restrict access to credentials based on the requester’s authority band and scope, ensuring least-privilege access. Paladin’s vault uses AES-256-GCM encryption, and credentials are never exposed in receipts or logs, enhancing security. The credential broker operates independently of the kernel, maintaining a strict import boundary to prevent contamination.
Financial transactions are governed through a vendor-neutral PaymentProcessor interface, which supports operations like charging, refunding, payouts, and balance checks. The kernel does not bundle payment vendor SDKs but provides a reference implementation (ManualLedgerProcessor) for testing. External processors, such as those for Stripe, register their capabilities via importlib.metadata entry points, allowing seamless integration without modifying kernel code.
Custodian-Kernel’s architecture enforces deterministic, zero-trust decision-making. When an agent proposes an action involving financial transactions, Paladin verifies factual claims against ground truth before the kernel authorizes the payment. For instance, if an agent recommends a refund based on a customer’s claim, the kernel cross-references the claim with order records. If discrepancies are found, the kernel overrides the agent’s recommendation, even if the agent’s confidence in the claim is high. This mechanism prevents fraudulent transactions by ensuring that only verifiable facts influence decisions.
The kernel integrates with Linux Security Modules (LSM) like Landlock to enforce least-privilege access at the syscall level. This ensures that even if an agent’s process is compromised, it cannot bypass kernel-enforced restrictions. For example, an agent cannot open a network socket to an unwhitelisted payment endpoint, regardless of its internal logic. Open Policy Agent (OPA) evaluates each action against authority bands and Rego rules, enforcing per-action caps (e.g., $250) and session spend limits (e.g., $1,000). Every decision is logged as an Open Cybersecurity Schema Framework (OCSF) event, providing a tamper-evident audit trail compatible with SIEM systems.
Custodian-Kernel’s enforcement extends beyond financial transactions to include tool usage, data access, and infrastructure interactions. Tools such as email, SMS, GitHub, Docker, web search, and NVIDIA NIM inference jobs are governed by the kernel, with consequential actions (e.g., L3 tools) requiring human approval via SMS or other authentication methods. The kernel’s rail-agnostic design allows it to govern diverse operations, from refunds and payouts to NVIDIA NIM job provisioning, without coupling to specific payment providers or AI frameworks. This flexibility ensures consistent governance across heterogeneous environments.
Agents operate within defined authority bands, and no single component holds both the keys to decision-making and execution. For example, while an agent may recommend a payment, the actual authorization and execution occur through the kernel, which verifies claims, enforces caps, and escalates to human operators when necessary. This model mirrors real-world access controls, where employees can propose actions but lack the authority to approve or execute them without oversight.
Custodian-Kernel is currently in alpha and has undergone extensive testing, including over 3,000 source tests, clean-wheel installations, artifact validation, and cross-platform qualification on Linux and Windows. The 0.4.4 release resolves architectural inconsistencies introduced in earlier versions, consolidating core components like the action-evaluation engine and Paladin bridge into the kernel. This release also enforces permanent architecture-boundary tests to prevent future dependencies between harness adapters. While the kernel has not undergone a third-party security audit, its design principles and testing rigor aim to mitigate risks in production environments.
Use Cases
Custodian-Kernel is primarily designed for testing and red teaming AI agent systems, where its policy enforcement and audit capabilities are critical. By simulating real-world scenarios—such as fraudulent refund requests or unauthorized tool usage—the kernel helps identify vulnerabilities in agent behavior and governance policies. Its vendor-neutral architecture allows security teams to evaluate agents across different frameworks without rewriting enforcement logic, making it a versatile tool for stress-testing AI systems.
In production environments, Custodian-Kernel can serve as a gatekeeper for AI-driven workflows involving sensitive operations. For example, an AI agent managing customer refunds can use the kernel to verify claims against order records before processing payments. If the agent’s recommendation conflicts with ground truth, the kernel blocks the transaction and escalates the issue to a human operator.
The kernel’s credential management system, Paladin, is particularly useful in scenarios requiring secure access to third-party APIs or services. By replacing hardcoded credentials with references (e.g., paladin://stripe_sk), organizations can enforce least-privilege access and audit all credential usage. This is especially valuable in multi-tenant environments or when integrating with external payment processors, where credential exposure poses significant security risks. Paladin’s encrypted vault and sandboxed egress further enhance security by preventing credential leakage into agent processes.
Its OCSF-compatible audit logs and tamper-evident receipts ensure that all agent actions are traceable and verifiable, which is essential for audits or legal investigations. The kernel’s ability to enforce per-action caps and session limits also aligns with financial regulations, such as those governing transaction monitoring and fraud prevention. By centralizing governance logic, the kernel reduces the complexity of implementing compliance controls across distributed AI systems.
Researchers and developers can use Custodian-Kernel to explore novel governance models for AI agents. Its modular design allows for experimentation with different policy engines, credential brokers, and payment processors without coupling to specific vendors. For instance, a team could test how Open Policy Agent’s Rego rules compare to custom logic for enforcing authority bands. The kernel’s support for multiple harness adapters also enables cross-framework comparisons, helping identify best practices for secure AI agent deployment.
In collaborative AI development environments, Custodian-Kernel facilitates shared governance policies across teams. Operators can define gates and approval workflows that apply uniformly to all agents, ensuring consistency in enforcement. For example, a team managing multiple AI agents could use the kernel to enforce a global policy prohibiting agents from accessing certain data sources or executing destructive commands. The kernel’s live console and audit logs provide visibility into agent behavior, enabling teams to detect and address policy violations in real time.
Key Features and Capabilities
Custodian-Kernel’s core feature is its unified decision boundary, which governs a wide range of agent actions, from filesystem operations to financial transactions. This boundary is enforced through a combination of mandatory guards, policy evaluation, and operator approval workflows. Each action is evaluated against predefined rules, and the kernel’s response—autonomous execution, approval required, or block—is recorded in a tamper-evident ledger. This ensures that all agent activity is logged and auditable, providing a clear trail of decisions and their rationale.
The kernel’s modular architecture supports integration with multiple AI harnesses and payment processors without interdependencies. For example, custodian-codex-guard and custodian-claude-guard can coexist on the same system, each governing its respective harness independently. Similarly, payment processors like Stripe can be added via separate packages, which register their capabilities with the kernel using importlib.metadata entry points. This design minimizes coupling and allows for easy updates or replacements of individual components.
Paladin, the kernel’s credential broker, enhances security by replacing direct credential exposure with references. Agents interact with credentials using identifiers like paladin://githubtoken, while Paladin resolves these references at runtime within a sandboxed environment. This approach prevents credentials from being logged, stored in configuration files, or leaked through agent prompts. Paladin’s AES-256-GCM encrypted vault and host-based access controls further restrict credential usage to authorized requesters and scopes, adhering to the principle of least privilege.
Financial governance is a key capability of Custodian-Kernel, enabled by its vendor-neutral PaymentProcessor interface. The kernel evaluates transaction requests against authority bands, session caps, and factual claims before authorizing payments. For instance, if an agent proposes a refund, the kernel verifies the claim against order records. If the claim is contradicted by ground truth, the kernel blocks the transaction and escalates the issue. This deterministic verification process ensures that financial decisions are based on verifiable facts rather than agent assertions, reducing the risk of fraud or errors.
The kernel’s integration with Linux Security Modules (LSM) like Landlock provides an additional layer of security by enforcing least-privilege access at the operating system level. This ensures that even if an agent’s process is compromised, it cannot bypass kernel-enforced restrictions, such as opening network sockets to unauthorized endpoints. Combined with Open Policy Agent (OPA), the kernel evaluates every action against Rego rules, enforcing granular controls like per-action caps and session spend limits. These rules are applied in real time, ensuring consistent governance across all agent activities.
Custodian-Kernel’s audit and logging capabilities are designed for compliance and forensic analysis. Every decision—whether an action is allowed, blocked, or requires approval—is recorded as an Open Cybersecurity Schema Framework (OCSF) event. These events are tamper-evident and structured, making them compatible with Security Information and Event Management (SIEM) systems. The kernel’s live console (custodian console) provides operators with visibility into pending approvals, blocked actions, and policy enforcement, enabling proactive management of agent behavior.
Gates can be configured to operate in open or protected modes, where open mode permits configured actions while retaining receipts, and protected mode requires approval for consequential actions. Gate rules can target specific harnesses, tools, workspaces, or action classes, providing fine-grained control over agent permissions. This flexibility is particularly useful in environments where policies need to evolve rapidly, such as during red teaming exercises or production deployments.
Custodian-Kernel’s support for multiple AI frameworks and payment processors makes it a versatile tool for organizations with heterogeneous AI infrastructures. For example, an organization using both OpenAI Codex and Claude Code can deploy separate guard adapters (custodian-codex-guard and custodian-claude-guard) while sharing the same kernel for policy enforcement and auditing. Similarly, the kernel can integrate with various payment processors, including Stripe, without requiring changes to its core logic.
The kernel’s deterministic decision-making process ensures that agent actions are governed by verifiable rules rather than probabilistic models. For example, when evaluating a refund request, the kernel cross-references the agent’s claims with ground truth data, such as order records. If the claims are contradicted, the kernel overrides the agent’s recommendation, regardless of the agent’s confidence level. This approach eliminates the risk of agents being manipulated into approving fraudulent transactions, providing a robust safeguard against both internal and external threats.
Custodian-Kernel’s architecture is designed to minimize trust assumptions and maximize security. For instance, while an agent may propose a payment, the kernel verifies the request and authorizes the transaction only if it complies with policies. This separation of concerns mirrors real-world access controls, where employees can propose actions but require approval from higher authorities to execute them.
The kernel’s cross-platform compatibility and testing rigor ensure reliability in diverse environments. As of version 0.4.4, Custodian-Kernel has been qualified on Linux and Windows, with macOS qualification pending. The release has passed over 3,000 source tests, artifact validation, and end-to-end behavioral simulations, demonstrating its stability and correctness. Organizations evaluating the kernel for consequential workloads are advised to review its security policy and conduct their own assessments.