Integrate HELM in 10 Minutes

This path gets a developer from a normal AI call to a governed call with a receipt that can be inspected and verified. The goal is not to read the architecture first. The goal is to see the boundary work.

Audience

Use this guide if you are adding HELM to an application, evaluating the proxy path for an internal platform, or proving to a security reviewer that tool calls can be allowed, denied, receipted, and replayed without trusting the model provider.

Outcome

At the end you will have:

• a local HELM boundary accepting OpenAI-compatible requests;
• one AI request routed through HELM instead of directly to the provider;
• one denied tool action with a reason code;
• one receipt or evidence bundle reference;
• a verifier command that returns deterministic pass/fail output;
• a short troubleshooting path for the common first-run failures.

Request Lifecycle

sequenceDiagram
  participant App as Application
  participant Helm as HELM proxy
  participant Policy as Policy bundle
  participant Provider as Upstream model
  participant Proof as Receipt and evidence
  App->>Helm: OpenAI-compatible request
  Helm->>Policy: Evaluate identity, tool, args, egress, delegation
  alt allowed
    Helm->>Provider: Forward governed request
    Provider-->>Helm: Model response
    Helm->>Proof: Write receipt headers and evidence
    Helm-->>App: Response with X-Helm-* headers
  else denied or escalated
    Helm->>Proof: Write denial receipt
    Helm-->>App: 403 with reason code
  end

sequenceDiagram
  participant App as Application
  participant Helm as HELM proxy
  participant Policy as Policy bundle
  participant Provider as Upstream model
  participant Proof as Receipt and evidence
  App->>Helm: OpenAI-compatible request
  Helm->>Policy: Evaluate identity, tool, args, egress, delegation
  alt allowed
    Helm->>Provider: Forward governed request
    Provider-->>Helm: Model response
    Helm->>Proof: Write receipt headers and evidence
    Helm-->>App: Response with X-Helm-* headers
  else denied or escalated
    Helm->>Proof: Write denial receipt
    Helm-->>App: 403 with reason code
  end

Source Truth

The public docs route is backed by this file. Implementation truth is in the HELM runtime and the OSS verifier surfaces:

• docs/public/product/integrations/openai-baseurl.md
• docs/public/reference/verify.md
• docs/public/product/integrations/mcp.md
• ../helm-ai-kernel/docs/QUICKSTART.md
• ../helm-ai-kernel/docs/VERIFICATION.md
• ../helm-ai-kernel/docs/INTEGRATIONS/openai_baseurl.md

If a command here disagrees with the implementation, the source files and verifier output win.

1. Start HELM

From the HELM repo:

docker compose up -d
curl -fsS http://localhost:8080/health

Expected output is an HTTP 200 health response. If your deployment exposes a separate health port, use the health URL shown by your compose or operator config.

2. Point One Client at HELM

HELM intentionally uses an OpenAI-compatible edge so most clients only change base_url.

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

Full Python request:

import openai

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

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Return the current policy status."}],
)

print(response.choices[0].message.content)

For Node.js:

import OpenAI from "openai";

const openai = new OpenAI({
  baseURL: "http://localhost:9090/v1",
});

3. Confirm Receipt Headers

Allowed requests should return HELM headers when the proxy path is active:

X-Helm-Receipt-ID: rec_...
X-Helm-Output-Hash: sha256:...
X-Helm-Lamport-Clock: ...

The exact receipt ID and hash are runtime values. The important property is that the response is linked to a decision record, not just to a model completion.

4. Trigger a Deny

Use a tool name or argument shape that is not in the active policy bundle:

curl -sS http://localhost:9090/v1/tools/execute \
  -H 'Content-Type: application/json' \
  -d '{"tool":"unknown_tool","args":{"bad_field":true}}' | jq .

Expected shape:

{
  "status": "DENIED",
  "reason_code": "DENY_TOOL_NOT_FOUND",
  "receipt_hash": "sha256:..."
}

The exact reason code depends on the active bundle and runtime adapter. Treat any allow on an unknown tool as a failed setup.

5. Verify the Evidence

Use the maintained verifier path for bundles produced by local runtime, CI, or release artifacts:

npx @mindburn/helm-ai-enterprise --bundle ./path/to/evidence --level L2 --depth 1

Expected result is a deterministic pass/fail summary. The verifier should not need the upstream model provider. It needs the bundle, policy/evidence material, and trust inputs required by the selected verification level.

6. Move From Verification to App

Before using HELM in a real app:

1. Pin the upstream URL and policy bundle.
2. Decide which effects require approval rather than automatic allow.
3. Store receipt IDs with the application action they governed.
4. Add a CI job that verifies representative bundles.
5. Expose receipt or proof links in your operator UI.

Troubleshooting

Next Pages

• OpenAI base URL integration
• MCP integration
• Verify HELM conformance
• SDK documentation