title: HELM Open Source Scope

HELM — Fail-Closed Execution Firewall for AI Agents

Fail-closed execution firewall · Fail-closed MCP interceptor · Signed receipts for AI actions

HELM is a deterministic proxy that sits between your AI agent and the tools it calls. Every tool invocation passes through a fail-closed policy gate, gets canonicalized (JCS + SHA-256), and produces an Ed25519-signed receipt. The receipts form a causal DAG (ProofGraph) that can be exported and verified offline.

- client = openai.OpenAI()
+ client = openai.OpenAI(base_url="http://localhost:8080/v1")

One line. Every tool call is now governed.

What HELM Does

Stops dangerous agent tool calls. Emits signed receipts.

What HELM Enforces By Default

The Problem

The Fix

Every tool call is governed, hashed, and signed:

• Fail-closed policy — undeclared tools are blocked, schema drift is a hard error
• Cryptographic receipts — Ed25519-signed, Lamport-ordered
• Budget enforcement — ACID locks, fail-closed on ceiling breach
• Offline verifiable — export EvidencePack, verify without network access
• Sub-0.1ms p99 overhead — governed hot-path measured at 75µs p99 (methodology)

Install

# Script (macOS / Linux)
curl -fsSL https://raw.githubusercontent.com/Mindburn-Labs/helm-oss/main/install.sh | bash

# Go
go install github.com/Mindburn-Labs/helm-oss/core/cmd/helm@latest

# Docker
docker run --rm ghcr.io/mindburn-labs/helm-oss:latest --help

Quick Start

# 1. Initialize (SQLite + Ed25519 keypair + default config)
helm onboard --yes

# 2. Run the demo — 5 synthetic tool calls, real receipts
helm demo organization --template starter --provider mock

# 3. Export and verify offline
helm export --evidence ./data/evidence --out evidence.tar
helm verify --bundle evidence.tar

The demo produces ALLOW, DENY, and BUDGET_EXCEEDED verdicts. Each verdict has a signed receipt. The EvidencePack is a deterministic .tar — same inputs produce identical output bytes.

Or govern an existing app:

helm proxy --upstream https://api.openai.com/v1
export OPENAI_BASE_URL=http://localhost:8080/v1
python your_app.py

How It Works

Your App (OpenAI SDK)
       │
       │ base_url = localhost:8080
       ▼
   HELM Proxy ──→ Guardian (policy: allow/deny)
       │                │
       │           PEP Boundary (JCS canonicalize → SHA-256)
       │                │
       ▼                ▼
   Executor ──→ Tool ──→ Receipt (Ed25519 signed)
       │                        │
       ▼                        ▼
  ProofGraph DAG          EvidencePack (.tar)
  (append-only)           (offline verifiable)
       │
       ▼
  Replay Verify
  (air-gapped safe)

Execution Security Model

HELM enforces security through three independent layers:

→ Execution Security Model · OWASP MCP Threat Mapping

Verify It Works

# 1. Trigger a deny
curl -s http://localhost:8080/v1/tools/execute \
  -H 'Content-Type: application/json' \
  -d '{"tool":"unknown_tool","args":{"bad_field":true}}' | jq .reason_code
# → "DENY_TOOL_NOT_FOUND"

# 2. View receipt
curl -s http://localhost:8080/api/v1/receipts?limit=1 | jq '.[0].receipt_hash'

# 3. Export + verify offline
helm export --evidence ./data/evidence --out pack.tar
helm verify --bundle pack.tar
# → "verification: PASS"

# 4. Conformance
helm conform --level L2 --json
# → {"profile":"CORE","pass":true,"gates":9}

→ Quickstart · Verification

HELM vs. Alternatives

Integrations

Python (OpenAI SDK)

import openai

client = openai.OpenAI(base_url="http://localhost:8080/v1")

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "List files in /tmp"}]
)
# X-Helm-Decision-ID: dec_a1b2c3...
# X-Helm-Verdict: ALLOW

→ examples/python_openai_baseurl/main.py

TypeScript

const response = await fetch("http://localhost:8080/v1/chat/completions", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "gpt-4",
    messages: [{ role: "user", content: "What time is it?" }],
  }),
});
// X-Helm-Decision-ID: dec_d4e5f6...
// X-Helm-Verdict: ALLOW

→ examples/js_openai_baseurl/main.js

MCP Interceptor

# Discover governed tools
curl -s http://localhost:8080/mcp/v1/capabilities | jq '.tools[].name'

# Execute with governance
curl -s -X POST http://localhost:8080/mcp/v1/execute \
  -H 'Content-Type: application/json' \
  -d '{"method":"file_read","params":{"path":"/tmp/test.txt"}}' | jq .
# → { "result": ..., "receipt_id": "rec_...", "reason_code": "ALLOW" }

→ examples/mcp_client/main.sh

Agent Runtimes

MCP Client Install

# Claude Desktop
helm mcp pack --client claude-desktop --out helm.mcpb

# Claude Code
helm mcp install --client claude-code

# VS Code / Cursor / Windsurf
helm mcp print-config --client windsurf

CI Integration

# .github/workflows/ci.yml
jobs:
  helm-check:
    uses: Mindburn-Labs/helm-oss/.github/workflows/boundary-checks.yml@main
    with:
      level: L2

SDKs

HELM works with your existing SDK first. Point any OpenAI-compatible client at the HELM proxy and you have governed tool calling with zero code changes. Native SDKs are there when you want tighter integration.

→ Insertion Guide — three copy-paste paths to get started.

Generated from api/openapi/helm.openapi.yaml.

c := helm.New("http://localhost:8080")
res, err := c.ChatCompletions(helm.ChatCompletionRequest{
    Model:    "gpt-4",
    Messages: []helm.ChatMessage{{Role: "user", Content: "List /tmp"}},
})
if apiErr, ok := err.(*helm.HelmApiError); ok {
    fmt.Println("Denied:", apiErr.ReasonCode) // DENY_TOOL_NOT_FOUND
}

→ examples/ · SDK docs

What Ships

Not included: managed federation, pack entitlement, compliance intelligence, Studio, managed control plane. See docs/OSS_SCOPE.md.

Security

• TCB isolation — 8-package kernel boundary, CI-enforced forbidden imports (TCB Policy)
• Bounded compute — WASI sandbox with gas/time/memory caps, deterministic traps (UC-005)
• Schema enforcement — JCS canonicalization + SHA-256 on every tool call, input and output (UC-002)
• Three-layer model — surface containment + dispatch enforcement + verifiable receipts (Execution Security Model)

SECURITY.md · Threat Model · OWASP MCP Mapping

Build & Test

make test       # 115 packages
make crucible   # 12 use cases + conformance L1/L2
make lint       # go vet

Deploy

docker compose up -d                              # local
docker compose -f docker-compose.demo.yml up -d   # production

→ deploy/README.md

Project Structure

helm-oss/
├── api/openapi/         # OpenAPI 3.1 spec (source of truth for SDKs)
├── core/                # Go kernel (8-package TCB + executor + ProofGraph)
│   └── cmd/helm/        # CLI: proxy, export, verify, replay, conform
├── packages/
│   └── mindburn-helm-cli/  # @mindburn/helm-cli (npm verifier)
├── sdk/                 # TypeScript, Python, Go, Rust
├── examples/            # Runnable per-language + MCP examples
├── deploy/              # Caddy, compose, deploy guide
├── docs/                # Threat model, security model, conformance
└── Makefile             # build, test, crucible, release-binaries

Contributing

See CONTRIBUTING.md.

License

Apache License 2.0

Built by Mindburn Labs — applied research for execution security in autonomous systems.