Deploy causal verification in minutes.

Reality Kernel sits between your agent and every dangerous system action. One HTTP call clears the verdict, returns evidence, and writes a tamper-evident ledger entry. No model weights. No prompt classifiers. Deterministic by construction.

1. Quickstart

Three lines of code, one HTTP call, three verdicts: ALLOW · WARN · BLOCK.

curl -X POST https://www.realitykernel.dev/v1/check \
  -H "Authorization: Bearer $RK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "command":      "rm -rf /var/lib/db",
    "prime_intent": "rotate old logs"
  }'

# pip install realitykernel

import os
from reality_kernel import Client

# Use "rk_local_test" for instant, offline local prototyping
rk = Client(api_key=os.environ.get("RK_API_KEY", "rk_local_test"))

result = rk.check(
    command="rm -rf /var/lib/db",
    intent="rotate old logs",
)

# "ALLOW" | "WARN" | "BLOCK"
verdict = result.verdict

const res = await fetch("https://www.realitykernel.dev/v1/check", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.RK_API_KEY}`,
    "Content-Type":  "application/json",
  },
  body: JSON.stringify({
    command:      "rm -rf /var/lib/db",
    prime_intent: "rotate old logs",
  }),
});
const { verdict, evidence, proof_hash } = await res.json();

The response carries the verdict, a confidence score, the list of triggering signals, the latency, and a SHA-256 proof hash that chain-links into your tamper-evident ledger.

2. Authentication

All requests authenticate via the Authorization header with a Bearer token. We support two token shapes:

A. Ephemeral scoped session tokens (recommended)

Per Legacy Systems Zero Trust guidance, agent workloads should never ship a master API key. Exchange it once, in your control plane, for a short-lived signed session token:

curl -X POST https://www.realitykernel.dev/v1/token \
  -H "Authorization: Bearer $RK_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id":   "agent-runner-01",
    "session_id": "session-xyz-789",
    "scopes":     ["fs:read", "sys:info"],
    "ttl":        3600
  }'

The response returns an rk_session_… token valid for the TTL window. Use it for every subsequent /v1/check. The master key never leaves your control plane.

# Exchange master key for 5-minute ephemeral session
agent_client = rk.assume_role(ttl_seconds=300)

# Pass agent_client to untrusted worker loops
agent_client.check(...)

B. Direct master key

For admin tooling, control planes, or trusted backend services that already live inside your sovereignty boundary:

Authorization: Bearer $RK_MASTER_KEY

C. Local Mock Mode (Free Tier)

For instant local prototyping without a network connection, use the rk_local_test key. The SDK will completely bypass the Reality Engine API and return deterministic verdicts based on local signature scanning.

Client(api_key="rk_local_test")

3. POST /v1/check

Submit one command per call. The kernel runs the fast-path policy gate first; if it does not clear, it spawns parallel shadow worlds and returns a sealed verdict.

Request fields

Response fields

4. Least-agency policy

Pin per-request boundaries with a policy block. Commands or destinations outside the allow lists are rejected before simulation runs.

"policy": {
  "allowed_tools": ["git", "grep", "cat", "ls"],
  "allowed_egress": ["*.github.com", "api.yourservice.com"]
}

5. Verdict semantics

6. Native Framework Plugins

Drop Reality Kernel straight into your existing agent framework with zero friction.

LangChain

Use our native RKLangChainGuardrail callback handler to automatically intercept and verify shell tool executions before they hit the host OS.

# pip install realitykernel[langchain]

from langchain.agents import initialize_agent
from reality_kernel import Client
from reality_kernel.integrations.langchain import RKLangChainGuardrail
import os

rk = Client(api_key=os.environ['RK_API_KEY'])
guardrail = RKLangChainGuardrail(client=rk, agent_id="my-agent")

agent = initialize_agent(
    tools=tools, 
    llm=llm, 
    callbacks=[guardrail] 
)

If the Reality Engine returns a BLOCK, the guardrail instantly throws an RKSecurityException, killing the execution loop deterministically.

7. Python SDK (v0.2.0)

For custom agents, RAG pipelines, or generic tool execution, use the SDK's built-in @rk_guard decorator, or wrap workflows in a trace_context() for OpenTelemetry-style data lineage tracking against multi-agent collusion.

# pip install realitykernel

from reality_kernel import Client
from reality_kernel.integrations.generic import rk_guard

rk = Client(api_key="rk_live_...")

@rk_guard(rk, intent="read application config file")
def read_config(path: str) -> str:
    with open(path) as f:
        return f.read()

# Automatically raises RKSecurityException if blocked
read_config("../../.env")        # → BLOCK
read_config("/app/config.yaml")  # → ALLOW

# Multi-agent OpenTelemetry tracing
with rk.trace_context() as trace_id:
    # All checks inside inherit this lineage
    rk.check("cat /etc/shadow", intent="read")

type Verdict = "ALLOW" | "WARN" | "BLOCK" | "ERROR";

export async function verifyAction(
  apiKey: string,
  command: string,
  intent: string,
): Promise<{ safe: boolean; verdict: Verdict; evidence: string[] }> {
  const r = await fetch("https://www.realitykernel.dev/v1/check", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${apiKey}`,
      "Content-Type":  "application/json",
    },
    body: JSON.stringify({ command, prime_intent: intent }),
  });

  if (!r.ok) return { safe: false, verdict: "ERROR", evidence: [`http_${r.status}`] };

  const { verdict, evidence = [] } = await r.json();
  return { safe: verdict === "ALLOW", verdict, evidence };
}

8. Operator review & overrides

WARN verdicts surface in the Pending Review widget on the dashboard. Operators can approve or block from there — overrides are written as fresh chain links, never as edits.

From your code, you can post the override programmatically once an operator decides:

POST /v1/override
Authorization: Bearer $RK_API_KEY
Content-Type: application/json

{
  "action_id": "act_01HXYZ…",
  "decision":  "approved"
}

High-confidence WARNs (≥ 0.60) trigger a step-up challenge in the dashboard — the override is logged with warning_level: "critical" for downstream audit review.

9. Discord alerts

Wire a webhook from the dashboard's Profile tab, or via API. Every WARN (and optionally BLOCK) ships a rich embed back to your channel with a signed link to the override surface.

# control plane env
DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/…"
DISCORD_NOTIFY_BLOCK="true"

Discord links never execute state changes directly. They land the operator on the dashboard, behind their session, so every approval still happens under their own audit identity.

10. Audit chain (EU AI Act Compliance)

Every verdict appends a SHA-256 chain link to your tamper-evident ledger. Use the v0.2.0 Python SDK to maintain a cryptographically sealed local ledger for court-grade proof.

from reality_kernel import Client, AuditLog

# 1. Init ledger
log = AuditLog(path="rk_audit_ledger.jsonl")
rk = Client(api_key="...", audit_log=log)

# 2. Agent runs... every action is chain-hashed locally.

# 3. Auditor requests proof
is_valid, report = rk.verify_audit()
# "Chain intact. 1,452 entries verified. Head hash: 3a9f1b2c..."

rk.export_audit("audit_export.json")

GET /v1/audit?limit=100
Authorization: Bearer $RK_API_KEY

Each entry carries a proof_hash and a prev_hash reference. Tamper one row and the next verification fails the whole chain. Use the interactive verifier to replay your chain online or offline.