HUQAN

Lokale, verifizierungsorientierte Governance-Ebene für KI-Agenten, Behauptungen, Speicherschreibvorgänge und riskante Aktionen, mit Nachweisen, Policy-Gates, Herkunftsnachweisen und Vertrauensbelegen.

GitHub
35

Dokumentation

HUQAN

A local trust boundary that separates the agent from the operator.

Most tools make agents stronger.
With the Approval Authority installed, HUQAN puts an OS boundary between the agent and the power to approve.

Agents can now write code, delete files, spend money, and change memory.
Without a proper trust layer, that power runs as the same user as you.

On Windows, the Approval Authority moves approval into a separate service protected by TOTP and cryptographic decision envelopes.
The decision is held by that service's own account, not by your user: an agent running as you cannot sign an approval, though it may still share your user identity with the operator.

Every decision is recorded as a Trust Receipt.

No model. No cloud. No API key required for the core gate.

npm Node License OpenSSF Scorecard

Who it is for

Individual and community — your agent's emergency brake. A solo builder does not want a SOC 2 program; they want the agent stopped before it does harm and a plain yes or no. HUQAN holds a mutating call until a person approves it, and huqan.emergency_stop stops one agent or a whole workspace. This is the Agent Brake Layer.

Team and enterprise — an audit record the operator does not write. A platform that audits itself still asks you to trust its own logs. A Trust Receipt is produced by the gate that made the decision, held locally, and verifiable from the receipt itself, so the record of an action is not the agent's own account of it. Where "independent" is claimed, read the boundary under Limits.

Try it in 30 seconds

$ npx -y huqan quickstart
HUQAN quickstart — learn -> review -> approve -> verify -> Trust Receipt
  1. OK   propose: huqan.learn -> review (mutating_requires_review), approval approval-…
      Write held, waiting for approval.
  2. OK   approve: huqan.approve -> approved (actor cli-quickstart)
      Approved; the write happened now.
  3. OK   verify: verified (confidence 0.90)
      Verified.
  4. OK   receipt: receiptId … (status canonical)
      Evidence recorded as a Trust Receipt.

Trust Receipt
  receiptId          : …
  claim              : …
  status             : canonical
  workspaceId        : default
  trustPolicyVersion : …
  provenance         : …
  auditTrail entries : 1

Your own graph is still empty: the run above used the throwaway store.
Next: `huqan status` for what is in your graph, `huqan approvals` for pending
decisions, or `huqan` for the interactive shell.
Connect your agent: README -> "Connect your agent in one line".

The write in step 1 did not happen. It was held until step 2 approved it. The quickstart uses a throwaway store.

No install needed: the same flow runs in the browser at huqan.com. What to run when: product surfaces.

The brake, in one command

$ npm run demo:agent-brake
1. The agent tries to delete a workspace file
   gate        review   external_action_review_required
   hook answer ask      the host stops and asks the operator
   executed    no       notes.txt is still there: yes
2. The operator decides          wrong code refused, TOTP code accepted
3. Only an authorized decision lets the delete run
4. The Trust Receipt             chain intact, seal signature valid
5. Why the demo cannot authorize production   DEMO_AUTHORITY_REFUSED
demo OK: blocked, decided, executed once, receipt verified

A temporary workspace, a signed identity card, a real gate decision, a real Trust Receipt, nothing of yours touched, no network — under two seconds. The gate, the receipt chain and its verifier are the production modules; the approval authority is stood in for on a machine that has none, and the runtime's own decision guard refuses that stand-in (step 5), so a demo can never authorize production. -- --reject runs the same scenario with the operator saying no.

Recording: docs/agent-brake-demo.cast (asciinema play docs/agent-brake-demo.cast), regenerated by the command itself with --record=. Presenter's 15-minute script, including what the demo does not prove: docs/demo-agent-brake-script.md.

Connect your agent in one line

MCP (Claude, Cursor, any MCP client):

{
  "mcpServers": {
    "huqan": {
      "command": "npx",
      "args": ["-y", "--package=huqan", "huqan-mcp"]
    }
  }
}

Gate (pre-execution guard for other agents):

npx -y --package=huqan huqan-gate install --profile claude-code

Profiles: claude-code, codex, openhands, opencode, pi, hermes. The gate enforces only when the client calls it before executing. Details.

Operator tools (huqan.approve, huqan.approvals, huqan.approval_detail, huqan.agent_resume, huqan.emergency_stop) are hidden from the model and require HUQAN_MCP_OPERATOR_TOKEN — an agent cannot approve its own proposal.

Set the operator token (copy-paste):

  1. Generate a token on your machine:
node -e "process.stdout.write(require('crypto').randomBytes(32).toString('hex'))"
  1. Put it in the MCP server configuration, so only the huqan-mcp server process (and therefore you, the operator) holds it:
{
  "mcpServers": {
    "huqan": {
      "command": "npx",
      "args": ["-y", "--package=huqan", "huqan-mcp"],
      "env": { "HUQAN_MCP_OPERATOR_TOKEN": "<paste the value you generated>" }
    }
  }
}
  1. Approve: the operator tools appear in your MCP client only when the token is set. When the agent proposes a mutation, call huqan.approvals to see pending decisions and huqan.approve to decide — from your side of the client, never from the agent's own tools or shell.

⚠️ Do not put the token where the model can see it — the agent's own environment variables, its prompt, or any file it reads. That breaks the "an agent cannot approve its own proposal" guarantee: keep it in the huqan-mcp server block only.

Install

npm install -g huqan     # Node.js 22.13.0 or newer

Seven binaries: huqan (CLI), huqan-mcp (MCP server), huqan-gate (pre-execution guard), huqan-authority (approval authority, ADR-016), plus the experiment CLIs huqan-cognitive-lab, huqan-causal-lab and huqan-neural-lab.
Run huqan doctor to see what is configured.

To stand up the gate, approval authority and Trust Receipt chain on a clean server, follow the 30-minute install guide. For the knowledge base and CLI only, see the local install guide.

How it works

evidence + provenance + workspace scope
        → verification, contradiction, risk
                → policy and approval boundary
                        → outcome + Trust Receipt

The outcome is one of:

ALLOW / REVIEW / QUARANTINE / DRY-RUN ONLY / BLOCK / REJECT

Escalation is a decision a person makes, not one the gate returns. A reviewer can move a pending case to escalated; that needs a second approver, so it is absent in a single-user install. Decision types: approve, reject, expire, cancel, escalate, override — see lib/human-oversight-approval-runtime.js.

A passing verification is a result inside one configured boundary, not a certificate of truth. The receipt names the boundary.

When the Approval Authority is installed, the decision itself moves behind an OS boundary (Windows service + TOTP + cryptographic envelopes). See ADR-016.

Limits (honest)

  • HUQAN does not eliminate hallucinations. It makes one claim inspectable and blockable before it becomes state.
  • Only what is wired is governed. An agent that never calls HUQAN is not covered.
  • The OS boundary needs the Approval Authority (a Windows service today). Code running as your user can still edit runtime files or the local store; the authority's ledger makes that detectable, not impossible. UAC is not a security boundary (ADR-016 residual risks).
  • Complements IAM, infrastructure security and human governance — it replaces none of them.
  • "Independent" is a bounded word. An issuer signature (lib/receipt/issuer-seal.js) proves a receipt's origin and integrity, not operator honesty: whoever holds the issuing key can edit the trail, re-sign it, and ship a clean history where every signature verifies. Independence needs a collector counter-seal (lib/receipt/collector-seal.js) signed with a key the audited host does not have, held by a party the operator does not administer; both keys on one machine means one person holds both ends, and the seal then detects accidental corruption and nothing more.
  • The conformance suites are self-run in this repository, not third-party verification; no third-party attestation is bound yet. See the interoperability and attestation boundary.
  • Synthetic graph read/write benchmarks reached 100k nodes and 100k edges on one machine. Admitted-learning measurements and limits are separate; this is not a production capacity guarantee.

Full details and edge cases: docs.

License

Single license: AGPL-3.0-only. No commercial license is offered, quoted, or granted today. The canonical licensing-status record is docs/legal/dual-licensing-status.md (decision record 2026-09-28, #3082); this README links to it rather than restating the status.

If your requirement makes a commercial path urgent, the decision record lists explicit revisit conditions; condition 3 (a prospective licensee's requirement makes the commercial path urgent) reopens that decision record before any offer is made. Until a new decision record says otherwise, there is nothing to quote, price, or sign.

Register interest (no offer implied): aliulu@ai-ulu.com

Confidence is not truth. Verify before you trust.

Buy Me A Coffee