# HELM AI Kernel

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![CI](https://github.com/Mindburn-Labs/helm-ai-kernel/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Mindburn-Labs/helm-ai-kernel/actions/workflows/ci.yml)
[![Documentation Gates](https://github.com/Mindburn-Labs/helm-ai-kernel/actions/workflows/docs.yml/badge.svg?branch=main)](https://github.com/Mindburn-Labs/helm-ai-kernel/actions/workflows/docs.yml)
[![CodeQL](https://github.com/Mindburn-Labs/helm-ai-kernel/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/Mindburn-Labs/helm-ai-kernel/actions/workflows/codeql.yml)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/Mindburn-Labs/helm-ai-kernel/badge)](https://scorecard.dev/viewer/?uri=github.com/Mindburn-Labs/helm-ai-kernel)
[![OpenSSF Best Practices evidence](https://img.shields.io/badge/OpenSSF%20Best%20Practices-evidence%20prepared-informational)](BEST_PRACTICES.md)
[![Release](https://img.shields.io/github/v/release/Mindburn-Labs/helm-ai-kernel?label=release)](https://github.com/Mindburn-Labs/helm-ai-kernel/releases/latest)
[![Maven Central](https://img.shields.io/maven-central/v/io.github.mindburnlabs/helm-sdk?label=maven%20central)](https://central.sonatype.com/artifact/io.github.mindburnlabs/helm-sdk)
[![npm](https://img.shields.io/npm/v/%40mindburn%2Fhelm-ai-kernel?label=npm)](https://www.npmjs.com/package/@mindburn/helm-ai-kernel)
[![PyPI](https://img.shields.io/pypi/v/helm-sdk?label=pypi)](https://pypi.org/project/helm-sdk/)
[![crates.io](https://img.shields.io/crates/v/helm-sdk?label=crates.io)](https://crates.io/crates/helm-sdk)
[![Go Reference](https://pkg.go.dev/badge/github.com/Mindburn-Labs/helm-ai-kernel/sdk/go.svg)](https://pkg.go.dev/github.com/Mindburn-Labs/helm-ai-kernel/sdk/go)
[![Launchpad Artifacts](https://github.com/Mindburn-Labs/helm-ai-kernel/actions/workflows/launchpad-artifacts.yml/badge.svg?branch=main)](https://github.com/Mindburn-Labs/helm-ai-kernel/actions/workflows/launchpad-artifacts.yml)
[![Release checksums](https://img.shields.io/badge/release%20checksums-available-success)](https://github.com/Mindburn-Labs/helm-ai-kernel/releases/latest/download/SHA256SUMS.txt)
[![Release attestations](https://img.shields.io/badge/release%20attestations-available-informational)](https://github.com/Mindburn-Labs/helm-ai-kernel/releases/latest/download/release-attestation.json)
[![SBOM CycloneDX](https://img.shields.io/badge/SBOM-CycloneDX%201.5-orange)](https://github.com/Mindburn-Labs/helm-ai-kernel/releases/latest/download/sbom.json)
[![SLSA provenance](https://img.shields.io/badge/SLSA-provenance-blue)](docs/RELEASE_SECURITY.md)
[![Sigstore Cosign](https://img.shields.io/badge/Sigstore-Cosign-blue)](docs/VERIFICATION.md)
[![GHCR kernel](https://img.shields.io/badge/ghcr.io-helm--ai--kernel-2496ED?logo=docker&logoColor=white)](https://github.com/Mindburn-Labs/helm-ai-kernel/pkgs/container/helm-ai-kernel)
[![GHCR chart](https://img.shields.io/badge/ghcr.io-helm--ai--kernel%20chart-0F1689?logo=helm&logoColor=white)](https://github.com/Mindburn-Labs/helm-ai-kernel/pkgs/container/charts%2Fhelm-ai-kernel)
[![Artifact Hub](https://img.shields.io/endpoint?url=https://artifacthub.io/badge/repository/mindburn-labs)](https://artifacthub.io/packages/search?repo=mindburn-labs)

HELM AI Kernel is the fail-closed execution firewall for AI agents.

AI models propose. Deterministic systems govern. HELM sits between stochastic
agent tool calls and infrastructure side effects. It intercepts MCP tools and
OpenAI-compatible requests, evaluates authority before dispatch, and emits
signed receipts that can be verified offline.

This is Mindburn Labs' HELM execution kernel for AI, not the Kubernetes package
manager.

```text
Agent proposal -> HELM boundary -> ALLOW / DENY / ESCALATE -> signed receipt
```

## Status

- Repository: `Mindburn-Labs/helm-ai-kernel`
- Root package identity: `helm-ai-kernel-root`
- Current public release: `v0.5.4`
- License: Apache-2.0
- Supported security line: `0.5.x`; `0.4.x` is best effort
- Canonical docs: <https://helm.docs.mindburn.org/helm-ai-kernel>

The current `v0.5.4` GitHub release was published on 2026-05-20 at
<https://github.com/Mindburn-Labs/helm-ai-kernel/releases/tag/v0.5.4>. It includes
CLI binaries, checksums, SBOM JSON, OpenVEX, release-attestation metadata,
Cosign bundles, `evidence-pack.tar`, `helm-ai-kernel.mcpb`, `helm-ai-kernel.rb`, and sample policy
material.

## What HELM AI Kernel Does

- Enforces default-deny execution for agent tool calls.
- Wraps MCP servers so unknown tools can be quarantined before side effects.
- Runs the kernel, guardian, proxy, receipt store, evidence export, and
  verification paths.
- Produces signed receipts and EvidencePacks for replay, audit, and tamper
  checks.
- Ships public SDK sources for Go, Python, TypeScript, Rust, and Java.

HELM AI Kernel does not include hosted Mindburn operations, private operational
tooling, or non-OSS downstream extensions.

## Quick Start

Install the published macOS CLI from the current GitHub release. The public
Homebrew tap should be verified before relying on it for the latest version.

```bash
curl -L -o helm-ai-kernel https://github.com/Mindburn-Labs/helm-ai-kernel/releases/latest/download/helm-ai-kernel-darwin-arm64
chmod +x helm-ai-kernel
./helm-ai-kernel --version
```

Start a local boundary. Add `--console` when you want the self-hostable Console:

```bash
helm-ai-kernel serve --policy ./release.high_risk.v3.toml
helm-ai-kernel serve --policy ./release.high_risk.v3.toml --console
helm-ai-kernel boundary status
```

Run the local proof demo after `helm-ai-kernel serve` starts on `127.0.0.1:7714`:

```bash
curl http://127.0.0.1:7714/api/demo/run \
  -H 'content-type: application/json' \
  -d '{"action_id":"export_customer_list","policy_id":"agent_tool_call_boundary"}'
```

Verify the returned receipt and confirm that tampering fails:

```bash
curl http://127.0.0.1:7714/api/demo/verify \
  -H 'content-type: application/json' \
  -d '{"receipt":{...},"expected_receipt_hash":"<receipt_hash from proof_refs>"}'

curl http://127.0.0.1:7714/api/demo/tamper \
  -H 'content-type: application/json' \
  -d '{"receipt":{...},"expected_receipt_hash":"<receipt_hash from proof_refs>","mutation":"flip_verdict"}'
```

Govern MCP tools or an OpenAI-compatible client:

```bash
python3 scripts/launch/mock-openai-upstream.py --port 19090
helm-ai-kernel mcp wrap --server-id local-tools --upstream-command "python3 scripts/launch/mcp-fixture-server.py"
helm-ai-kernel proxy --upstream http://127.0.0.1:19090/v1
```

Inspect and verify evidence:

```bash
helm-ai-kernel sandbox preflight --runtime wazero
helm-ai-kernel receipts tail --agent agent.demo.exec
helm-ai-kernel verify evidence-pack.tar
```

`helm-ai-kernel serve --policy` stores receipts in SQLite by default unless
`DATABASE_URL` is set. `helm-ai-kernel verify evidence-pack.tar` runs offline by default;
use `--online` only when public proof endpoint credentials are available for
that release.

## Build From Source

```bash
git clone https://github.com/Mindburn-Labs/helm-ai-kernel.git
cd helm-ai-kernel
make build
./bin/helm-ai-kernel serve --policy ./release.high_risk.v3.toml
```

Run the retained validation targets before publishing changes:

```bash
make test
make test-console
make test-platform
make test-all
make crucible
```

## Architecture

HELM separates orchestration from execution authority. Agent frameworks decide
what to attempt; HELM decides what is allowed to execute.

```mermaid
flowchart LR
    Agent["Agent tool call"] --> Boundary["HELM boundary"]
    Boundary --> Verdict["ALLOW / DENY / ESCALATE"]
    Verdict --> Receipt["Signed receipt"]
    Receipt --> Verify["Verify / replay"]
    Verify --> Tamper["Tamper fails"]
```

Unknown MCP servers and tools enter quarantine before dispatch:

```mermaid
flowchart TD
    Server["Discovered MCP server"] --> Quarantine["Quarantined by default"]
    Quarantine --> Inspect["Metadata and schema inspection"]
    Inspect --> Risk["Risk classification"]
    Risk --> Approval["Approval record"]
    Approval --> Active["Policy-bound active state"]
    Active --> Decision["ALLOW / DENY / ESCALATE"]
    Decision --> Proof["Receipt and ProofGraph event"]
```

Key terms:

- `ALLOW`: HELM lets the action run.
- `DENY`: HELM blocks the action.
- `ESCALATE`: HELM stops and asks for more facts, policy, or human approval.
- `Receipt`: signed record of the decision.
- `ProofGraph`: replayable record chain for what happened.
- `EvidencePack`: portable bundle of records for a review path.

The complete diagram doctrine lives in
[docs/architecture/canonical-diagrams.md](docs/architecture/canonical-diagrams.md).

## Public Interfaces

| Surface | Path | Status |
| --- | --- | --- |
| CLI and kernel | `core/` | Go implementation of boundary, CLI, HTTP API, proxy, receipts, evidence export, and verification |
| Console | `apps/console/` | Self-hostable HELM AI Kernel Console |
| Design system core | `packages/design-system-core/` | Workspace package source used by the Console |
| Wire contracts | `api/openapi/`, `protocols/`, `schemas/` | OpenAPI, Protobuf, policy schemas, and JSON schemas |
| SDKs | `sdk/` | Go, Python, TypeScript, Rust, and Java sources |
| Examples | `examples/` | Runnable integrations and launch smoke material |
| Conformance | `tests/conformance/`, `reference_packs/` | Profile, checklist, fixtures, and reference packs |
| Deployment | `deploy/helm-chart/` | Helm chart for running the kernel in Kubernetes |

## SDKs And Packages

| Surface | Current install or status |
| --- | --- |
| CLI | GitHub Release binaries; the latest release attaches a `helm-ai-kernel.rb` formula asset. Verify the public tap before relying on `brew install mindburnlabs/tap/helm-ai-kernel` for the latest version |
| Go SDK | `go get github.com/Mindburn-Labs/helm-ai-kernel/sdk/go@main`; tagged module versions are tracked as an OSS-readiness follow-up |
| Python SDK | `pip install helm-sdk` |
| TypeScript SDK | `npm install @mindburn/helm-ai-kernel` |
| Rust SDK | `cargo add helm-sdk` |
| Java SDK | Maven Central coordinate `io.github.mindburnlabs:helm-sdk:0.5.4` |
| Design system core | Workspace source; public npm registry publication is not verified in this repo |

HTTP clients are generated from
[`api/openapi/helm.openapi.yaml`](api/openapi/helm.openapi.yaml). Protobuf
message bindings come from [`protocols/proto/`](protocols/proto/) where a
language SDK ships them.

## Documentation

Public OSS docs are sourced from this repo and published through
`helm.docs.mindburn.org`. The owned docs set for sync is declared in
`docs/public-docs.manifest.json`.

- [Quickstart](docs/QUICKSTART.md)
- [Console](docs/CONSOLE.md)
- [Architecture](docs/ARCHITECTURE.md)
- [Conformance](docs/CONFORMANCE.md)
- [Verification](docs/VERIFICATION.md)
- [Publishing](docs/PUBLISHING.md)
- [Compatibility](docs/COMPATIBILITY.md)
- [SDK Index](docs/sdks/00_INDEX.md)
- [Security Model](docs/EXECUTION_SECURITY_MODEL.md)
- [OWASP Mapping](docs/OWASP_MCP_THREAT_MAPPING.md)
- [NIST AI Agent Critical Infrastructure Alignment](docs/compliance/nist-ai-agent-critical-infrastructure.md)
- [NIST AI RMF to ISO 42001 Crosswalk](docs/compliance/nist-ai-rmf-iso-42001-crosswalk.md)

## Release Verification

For `v0.5.4`, verify downloads with `SHA256SUMS.txt`, `sbom.json`,
`v0.5.4.openvex.json`, `release-attestation.json`, the platform binary assets,
matching `*.cosign.bundle` files, and offline `evidence-pack.tar` verification.

Current release tooling derives artifact versions from tag refs, requires an
exact `v<version>.openvex.json` for tag releases, and verifies the staged
`evidence-pack.tar` before checksums are finalized.

See [docs/VERIFICATION.md](docs/VERIFICATION.md) and
[docs/PUBLISHING.md](docs/PUBLISHING.md) for the full release verification path.

## Security, Contributing, And Governance

- Report vulnerabilities through [SECURITY.md](SECURITY.md). Do not open public
  issues for security-sensitive reports.
- Contribution setup and validation expectations are in
  [CONTRIBUTING.md](CONTRIBUTING.md).
- Project governance and maintainer responsibilities are in
  [GOVERNANCE.md](GOVERNANCE.md) and [MAINTAINERS.md](MAINTAINERS.md).
- Community behavior expectations are in [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
- Support channels are listed in [SUPPORT.md](SUPPORT.md).
- Near-term OSS work is summarized in [ROADMAP.md](ROADMAP.md).

## License

Apache-2.0. See [LICENSE](LICENSE).
