Skip to content

QUICKSTART.md

Latest commit

 

History

History
217 lines (167 loc) · 7.62 KB

QUICKSTART.md

File metadata and controls

217 lines (167 loc) · 7.62 KB
Raw
title Quickstart
last_reviewed 2026-08-20

Quickstart

Run HELM locally and prove the boundary before connecting it to a real agent. No account or model key is required.

Install

brew tap mindburn-labs/tap
brew install mindburn-labs/tap/helm-ai-kernel
helm-ai-kernel --version

From source:

git clone https://github.com/Mindburn-Labs/helm-ai-kernel.git
cd helm-ai-kernel
git checkout v0.8.4
mise trust
mise install
mise exec -- make build
./bin/helm-ai-kernel --version

The source build uses Go 1.25.12, pinned by go.work and mise.toml. The recipe explicitly trusts the checked-out mise configuration and installs the pinned toolchain before building. If mise is unavailable, use a compatible native Go toolchain instead.

Delivery Surfaces

These are distinct delivery surfaces for the released v0.8.4 Kernel. The Homebrew, binary, container, and chart rows install or retrieve the Kernel; MCPB/Console bundles are release artifacts and are not CLI substitutes; SDKs are client libraries, not executable Kernel installs.

Surface Install or artifact Verification / boundary
Homebrew CLI formula brew tap mindburn-labs/tap then brew install mindburn-labs/tap/helm-ai-kernel Canonical formula mindburn-labs/tap/helm-ai-kernel
GitHub release binaries HELM Kernel v0.8.4 release: macOS/Linux amd64 and arm64, Windows amd64 assets Download SHA256SUMS.txt and the matching per-asset Cosign bundle
GHCR images docker pull ghcr.io/mindburn-labs/helm-ai-kernel:v0.8.4 or docker pull ghcr.io/mindburn-labs/helm-ai-kernel:v0.8.4-slim Verify the image signature before use
OCI chart helm pull oci://ghcr.io/mindburn-labs/charts/helm-ai-kernel --version 0.8.4 Verify the chart signature before deployment
MCPB / Console bundles helm-ai-kernel.mcpb and helm-console-local-sidecar-* / helm-ai-kernel-*-console.tar.gz release assets Release artifacts only; they do not replace the CLI install
SDKs npm @mindburn/helm-ai-kernel@0.8.4; PyPI helm-sdk==0.8.4; crates helm-sdk@0.8.4; Maven io.github.mindburnlabs:helm-sdk:0.8.4; Go github.com/Mindburn-Labs/helm-ai-kernel/sdk/go@v0.8.4 Client libraries only; use the SDK docs for integration, not executable installation

Supported CLI Paths

Surface Public proof
Install brew install mindburn-labs/tap/helm-ai-kernel or the tagged source build above
CLI chooser helm-ai-kernel or helm-ai-kernel setup
Local proof helm-ai-kernel mcp proof --json --out ~/.helm-ai-kernel/proofs
Codex setup helm-ai-kernel setup codex --dry-run --json
Claude Code setup helm-ai-kernel setup claude-code --dry-run --json
Hermes setup helm-ai-kernel setup hermes --scope user --dry-run --json
DeepSeek setup helm-ai-kernel setup deepseek --scope user --dry-run --json
Cursor / Windsurf / VS Code config helm-ai-kernel setup --client cursor --print-config
OpenClaw / Hermes adapters tool runtime adapters
Framework adapters framework adapters
Skill Packs helm-ai-kernel skills search --json
Agent risk scan helm-ai-kernel scan --path . --risk-envelope out/risk-envelope.json --preview out/risk-report.md
MCP quarantine and recovery mcp authorize-call, mcp quarantine, mcp pending, mcp receipts, mcp revoke; mcp approve rejects opaque local approval metadata
OpenAI proxy helm-ai-kernel proxy --port 9090
Receipts helm-ai-kernel mcp receipts --json and helm-ai-kernel boundary records --json
Conformance helm-ai-kernel conform --level L1 --json and --level L2
SDKs source clients under sdk/ with local test targets

Prove The Boundary

helm-ai-kernel mcp proof --json --out ~/.helm-ai-kernel/proofs

Expected shape:

{
  "schema_version": "helm.mcp.proof/v1",
  "offline_verified": true,
  "scenarios": [
    { "verdict": "ESCALATE", "dispatched": false },
    { "verdict": "DENY", "dispatched": false }
  ]
}

Verify the generated EvidencePack offline:

helm-ai-kernel verify --bundle ~/.helm-ai-kernel/proofs/<run-id>/evidencepacks/<run-id> --profile dev-local --allow-self-attested --json

The explicit opt-in is required because this local proof creates its own signing key. It proves internal consistency, not provenance.

When the v0.8.4 GitHub Release publishes an evidence-pack.tar, use that release asset for release verification instead of a local proof bundle. Until then, the local proof bundle above is the verifiable path.

For the full public flow, see HELM Proof Loop.

See An Escalation

Ask HELM to authorize a local MCP action before dispatch:

helm-ai-kernel mcp authorize-call \
  --server-id helm-governance \
  --tool-name file_read

Every verdict prints the same shape: verdict, decision id, reason, and receipt path. A local quarantine escalation intentionally does not print a command that could mint approval authority.

HELM ESCALATE
decision: mcp-boundary-...
reason: unknown MCP server remains quarantined; credential verification is unavailable
approval: credential verification unavailable; the server remains quarantined
receipt: data/receipts/mcp/...

Nothing runs on ESCALATE. Local helm-ai-kernel mcp approve is retained only for compatibility and rejects opaque approver names, receipt ids, tool lists, and TTLs; it cannot create an MCP approval or side-effect grant.

To progress a bounded action, the governing approval integration must issue an exact, credential-verified durable dispatch admission. The local CLI deliberately has no command that can create that admission. A verifier-backed runtime re-evaluates the exact request, schema pin, policy, effect scope, expiry, and revocation before it dispatches.

Inspect the local, no-dispatch state and its evidence:

helm-ai-kernel mcp quarantine --json
helm-ai-kernel mcp pending --json
helm-ai-kernel mcp receipts --json

If an existing registry record must be invalidated, revocation remains available; it never grants authority:

helm-ai-kernel mcp revoke \
  --server-id helm-governance \
  --reason "inspection finished"

See Deny Reason Codes for the evidence required to resolve each reason code.

Connect A Local Agent

See the supported matrix:

helm-ai-kernel setup --json

For Claude Code:

helm-ai-kernel setup claude-code --yes

For Codex:

helm-ai-kernel setup codex --yes

For Hermes (writes a fail-closed pre_tool_call hook in ~/.hermes/config.yaml; this does not mean Hermes already sees DENY in the wild, and it does not write MCP):

helm-ai-kernel setup hermes --scope user --yes

For DeepSeek (writes a fail-closed Kernel PreToolUse hook in ~/.dsh/hooks.json and points the stock DSH dsh-hooks-claude-code bridge configPath at that file; this is an adapter hop, not a HELM-native agent runtime, and it does not mean npx @deepseek-ai/dsh web sees DENY):

helm-ai-kernel setup deepseek --scope user --yes

Preview writes first:

helm-ai-kernel setup codex --dry-run --json
helm-ai-kernel setup --client cursor --print-config

Setup writes local config and draft policy artifacts. It does not approve detected tools.

Inspect

helm-ai-kernel mcp pending --json
helm-ai-kernel mcp receipts --json
helm-ai-kernel boundary records --verdict ESCALATE --json

Keep sensitive prompts, provider keys, endpoints, and unredacted receipts out of public issues.