Skip to main content

LOKAHI

Model Context Protocol (MCP) Runtime Security Gate & Deterministic Policy Firewall for AI Agents

PyPI version Python Versions License: Apache-2.0 CI Tests: 102 passed Protocol: MCP Security: Fail-Closed

Checks what an autonomous AI agent is about to do against community-signed rules before every tool call runs. Silence means no.


What is LOKAHI?

LOKAHI is a lightweight, fail-closed runtime security gate that sits between an autonomous AI agent (such as Claude Code, Cursor, LangChain, or custom agent harnesses) and the tools it invokes over the Model Context Protocol (MCP).

Before any tool executes:

  1. LOKAHI validates the call against a cryptographically signed boundary manifest.
  2. Restricts data access to explicitly permitted fields and enforced jurisdictions/residency.
  3. Enforces multi-party Ed25519 consent quorum on irreversible actions.
  4. Writes every decision into a tamper-evident, hash-chained audit ledger.

If an approval window closes without human consent, the action is refused. If an agent attempts to approve its own calls or inject arguments outside policy, the action is blocked.

The name comes from the Hawaiian word lōkahi, meaning unity, agreement, or harmony. LOKAHI ensures critical actions proceed only when independent parties agree.

                     [ AI Agent (Claude Code / Cursor / LLM) ]
                                        │
                                (MCP Tool Request)
                                        ▼
                 ┌──────────────────────────────────────────────┐
                 │             LOKAHI RUNTIME GATE              │
                 │  • Signed Manifest Capability Check          │
                 │  • Data Boundary & Residency Enforcement     │
                 │  • Ed25519 Multi-Party Consent Quorum        │
                 │  • Sliding-Window Emergency Exception Budget │
                 └──────────────────────┬───────────────────────┘
                                        │
                        ┌───────────────┴───────────────┐
                        ▼                               ▼
                   [ ALLOWED ]                [ REFUSED / ESCALATE ]
               Passes to MCP Server        Mid-stream refusal injected
                        │                               │
                        └───────────────┬───────────────┘
                                        ▼
                          [ Tamper-Evident S2 Ledger ]
                           (SHA-256 + Ed25519 Envelopes)

Why LOKAHI? (Deterministic Gate vs. Prompt Guardrails)

Most AI guardrails today (such as prompt-based filters or LLM evaluators) run inside or alongside the context window. They are vulnerable to indirect prompt injection, jailbreaks, semantic obfuscation, and hallucination.

LOKAHI enforces deterministic object capabilities outside the model context:

Security Dimension Prompt-Based Guardrails (NeMo, Llama Guard) Traditional API Gateways / RBAC LOKAHI MCP Runtime Gate
Defense Mechanism Probabilistic prompt inspection Static user/token permissions Cryptographic boundary manifests
Bypass Resistance Susceptible to jailbreaks & prompt injection Incapable of reasoning about tool arguments Immune: deterministic out-of-band rules
Irreversible Actions Often auto-executed or binary allow/deny Static rules with no quorum Ed25519 m-of-n disjoint human quorum
Fail Mode Often fails open or leaks partial output Fails open on timeout Strictly fail-closed: silence means no
Audit Trail Ephemeral application logs Centralized database logs Tamper-evident hash-chained cryptographic ledger
Core Dependencies Heavy LLM inference runtime / GPUs Heavy infrastructure Zero runtime dependencies (Python standard library)

3 Core Invariants

  1. Fail Closed: If a manifest is unsigned, expired, tampered with, or unverified by a trusted public key, LOKAHI permits nothing.
  2. Silence Means No: If an approval window closes without enough separate, authorized humans signing yes, the action is refused.
  3. Two-Person Freeze: Any two independent approvers casting a "No" vote immediately freeze the action, regardless of any other votes.

Quickstart (60 Seconds)

1. Install

# Minimal zero-dependency core:
pip install lokahi

# With Ed25519 cryptographic signatures & conformance tools:
pip install "lokahi[signatures]"

2. Generate Keys & Sign a Boundary Manifest

# 1. Generate keys for the manifest issuer and a human approver
lokahi-sign keygen --out manifest.key
lokahi-sign keygen --out reviewer.key

# 2. Inspect the example manifest
cat examples/editorial-desk.manifest.json

# 3. Sign the manifest
lokahi-sign manifest --key-file manifest.key \
  --in examples/editorial-desk.manifest.json \
  --out manifest.json

3. Run the MCP Security Gate

Run LOKAHI as a transparent stdio proxy between your agent and an MCP server:

lokahi-gate --manifest manifest.json \
  --key-file manifest.key \
  --approvers examples/approvers.example.json \
  --approvals approvals.jsonl \
  --ledger lokahi-ledger.jsonl \
  --requester agent:claude-code \
  --operator ops:salik

4. Approve Irreversible Calls Out-of-Band

When an agent requests an irreversible action (e.g., publishing data, deleting a table, executing a financial transfer), LOKAHI returns an ESCALATE verdict with a cryptographic action_digest.

The human approver signs from their own terminal or device:

lokahi-approve --key-file reviewer.key \
  --operator reviewer:alice --node workstation-1 \
  --digest <action_digest> \
  --decision yes \
  --approvals approvals.jsonl

The approval is cryptographically bound to that exact call, tool, and argument payload, expiring after a configured timeout (default: 1 hour).


Python API

LOKAHI can also be embedded directly in your Python agent pipelines:

from lokahi import Manifest, Signer, evaluate

# Load and verify boundary manifest
manifest = Manifest.load("manifest.json")
signer = Signer.load("manifest.key")

# Evaluate an incoming agent tool call
verdict = evaluate(
    manifest=manifest,
    tool_name="read_file",
    arguments={"path": "documents/report.pdf"},
    requester="agent:claude-code",
    operator="ops:salik"
)

if verdict.allowed:
    print(f"Action permitted: {verdict.reason}")
else:
    print(f"BLOCKED: {verdict.reason}")

Test Suite & Conformance

LOKAHI ships with a comprehensive test suite covering 102 tests:

# Run core security & evaluation tests (70 tests)
python tests/test_core.py

# Run monotonicity & decisions tier tests (32 tests)
python tests/test_decisions.py

# Run the 50-scenario red-team benchmark
python tools/run_evals.py

# Run CLI conformance
lokahi-conformance

All 70 core evaluation tests and 32 decisions tests run in under 2 seconds on standard hardware using standard-library Python.


Multi-Runtime Ecosystem

LOKAHI is designed to be runtime-agnostic:

Implementation Package / Path Performance Intended Environment
Python Core Reference pip install lokahi ~5–9 ms Python MCP agents, LangChain, LlamaIndex, CLI tools
Rust Native Kernel crates/lokahi-gate (Dirgha) 0.2 ms (p95) High-throughput agent runtimes, robotics, native binaries
WebAssembly Gate lokahi_gate.wasm (104.8 KB) <1 ms Browser extensions, edge workers, Node.js runtimes
SSE Streaming Interceptor src/gateway/ (Dirgha 2.0.1) Zero latency on text Reverse proxy intercepting Claude Code & OpenAI streaming APIs

Known Limits & Scope

  1. Independent External Review: An internal audit of record is published in AUDIT_REPORT.md; independent third-party external review is on the roadmap.
  2. Threshold Signatures: Each validator currently signs independently and LOKAHI counts distinct valid signatures. FROST threshold signing (RFC 9591) is planned for future versions.
  3. Decisions Tier is Experimental: The optional ML classifier in tools/decisions/ is off by default and is excluded from the core mathematical safety claim. The safety guarantee comes strictly from deterministic manifests and Ed25519 consent.

Repository Layout

Path Description
tools/lokahi.py Decision engine: manifests, tool policies, 15 rules, vote binding, ledger
tools/mcp_stdio_proxy.py Model Context Protocol (MCP) JSON-RPC proxy gate & self-test
tools/lokahi_sign.py Cryptographic key generation & manifest signing CLI
tools/lokahi_approve.py Out-of-band Ed25519 action consent signing CLI
examples/ Complete boundary manifests, approvers lists, and editorial desk demo
tests/test_core.py 70 core security tests and adversarial attacks
tests/test_decisions.py 32 tests for learned decisions monotonicity
data/ Canonical 50-scenario Red-Team evaluation corpus (CC BY 4.0)
docs/SPEC.md Full technical specification: manifest fields, rule ordering, vote binding
CHANGELOG.md Release history and version notes

  • Dirgha: High-performance coding agent runtime and enterprise streaming gateway featuring the native Rust LOKAHI gate.
  • Ahimsa AI: Design-time AI impact assessment compiler that generates signed boundary manifests for LOKAHI.
  • Synthetic Humanism: Theoretical framework and empirical benchmarks across documented AI failure modes.

Background & Academic Context

  • Object Capabilities & Boundaries: Andrew Critch, Boundaries: an open sequence on multi-agent alignment and cooperative AI (2022–2023).
  • Local Context in AI Risk: Aggarwal et al., ASTRA: AI Safety, Trust, & Risk Assessment, arXiv:2602.17357 (2026).
  • Guaranteed Safe AI: Dalrymple, Skalse, Bengio, Russell, Tegmark et al., Towards Guaranteed Safe AI, arXiv:2405.06624 (2024).
  • Robust Composition: Mark S. Miller, Robust Composition, PhD dissertation, Johns Hopkins University (2006).

Authors & Contributors

  • Salik Shah (Author & Creator): protocol design, reference implementation, formal specification, scenario set (salikshah.com, GitHub)
  • Sabin Ranjit (Community Contributor): security architecture contributions (GitHub)

License

This project is licensed under the Apache-2.0 License. The scenario evaluation data in data/ is licensed under CC BY 4.0.

Metadata

Release files for lokahi 1.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for lokahi 1.2.0
File Size Uploaded Provenance Actions
lokahi-1.2.0.tar.gz 2.3 MB With provenance Details for lokahi-1.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for lokahi 1.2.0
File Interpreter ABI Platform Actions
lokahi-1.2.0-py3-none-any.whl Python 3 none any Details for lokahi-1.2.0-py3-none-any.whl

Total release size: 4.6 MB

Release files / lokahi-1.2.0.tar.gz

Download URL lokahi-1.2.0.tar.gz
Size 2.3 MB
Tags Source
SHA-256 checksum
How to use checksums
3ede66068cb4fe4e340714928abccb47d9613b88a34412468a05ab223e609293
BLAKE2b-256 checksum
How to use checksums
3348785efb07ef9393613b8ee36a24f541e451c989782a06147be0b4c36c9166
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.

Transparency log

Release files / lokahi-1.2.0-py3-none-any.whl

Download URL lokahi-1.2.0-py3-none-any.whl
Size 2.3 MB
Tags Python 3
SHA-256 checksum
How to use checksums
12a8261289a556d7cb987c322b6bdaad178dff7523997d6663ab510e698bf538
BLAKE2b-256 checksum
How to use checksums
173b2ad294ec3547212297b736ffcd5a347520b0fedea7c896979af1bc168553
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.

Transparency log

Security for lokahi 1.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for lokahi-1.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page