---
title: "Integrate HELM in 10 Minutes"
canonical: "https://helm.docs.mindburn.org/start"
source: "helm-ai-enterprise/docs/public/getting-started/integrate-in-5-min.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/getting-started/integrate-in-5-min.md"
section: "start"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-04"
checksum_sha256: "sha256:fcf61af43fb4c1e84844c8fdc338c3d49457e5033eaddab30e0318795f66cc72"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# 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

```mermaid
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:

```bash
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`.

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

Full Python request:

```python
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:

```ts
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:

```text
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:

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

Expected shape:

```json
{
  "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:

```bash
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

| Symptom | Likely Cause | Fix |
| --- | --- | --- |
| Client still talks directly to OpenAI | `base_url` or `baseURL` was not changed | Log the request host and confirm it is `port 3000` or your HELM host. |
| Response has no `X-Helm-*` headers | Request bypassed HELM or proxy/header emission is disabled | Use the OpenAI base URL guide and check proxy logs. |
| Unknown tool is allowed | Wrong policy bundle or permissive dev policy | Load the intended bundle and rerun the deny step. |
| Verifier cannot find bundle material | Evidence export path is wrong | Use the receipt/evidence export produced by your runtime or CI job. |
| First request is denied | Identity, tool, or egress policy is missing | Inspect the denial receipt and add the smallest required grant. |

## Next Pages

- [OpenAI base URL integration](/integrations/openai-baseurl)
- [MCP integration](/integrations/mcp)
- [Verify HELM conformance](/reference/verify)
- [SDK documentation](/reference/sdks)