OpenKedge

Governing Agentic Mutation with Execution-Bound Safety and Evidence Chains

OpenKedge is a protocol for safely operating AI agents over real-world systems.

It replaces direct API execution with:

• intent-governed mutation
• execution-bounded contracts
• verifiable decision lineage (IEEC)

Try It In 30 Seconds

npm install
npm run build

./dist/cli/index.js preview examples/intents/terminate-25-instances.json

See exactly why a mutation would be blocked before it ever reaches production.

Local MCP gateway quickstart

Use Node.js 22 or newer (the local gateway stores IEEC in node:sqlite).

npm install
npm run build
npm run demo:mcp

The demo's official MCP client starts two stdio gateway processes against one authoritative policy file, lists the protected tool, exercises admission and execution, updates the shared policy, and prints the evidence directory and proposal ID. It needs no model, API key or AWS account. Its fixed key is accepted only through the explicit demo-only launch setting.

Run the separate MCP client example from the repository root. It starts a gateway child process through the SDK and shows tool discovery, an allowed mock action, a denial, and the caller's replay evidence:

npm install
npm run build
export OKG_SIGNING_KEY_HEX="$(openssl rand -hex 32)"
export OKG_GATEWAY_ID=external-gateway
export OKG_CALLER_ID=external-agent
export OKG_DELEGATED_BY=local-operator
node examples/mcp-external-client.mjs

For another MCP client, configure a stdio server with command node, argument <repository>/dist/gateway/mcp-server.js, and the same four required environment variables. Set OKG_POLICY_FILE and OKG_EVIDENCE_DB to absolute paths as needed. The trusted launcher, not an MCP tool argument, supplies the caller and delegator IDs. One stdio gateway process serves one caller; stdio does not authenticate multiple remote callers. Give each gateway its own evidence DB for this local example. The tools are request_ec2_termination, execute_ec2_termination, openkedge_policy_status, and openkedge_replay.

The demo copies the local policy to a temporary directory. To change a copied policy while gateways are running, use node dist/gateway/policy-cli.js <policy-file> deny-all or allow-dev; status prints its content hashed version. The command replaces the file atomically. Each gateway reads the authoritative file on its next admission or execution; policy read failures deny destructive operations. To inspect evidence, call openkedge_replay with the printed proposal ID against the gateway that handled it. The RFC defines result and error semantics.

This is a mock execution boundary: the agent receives no adapter credential, and the gateway verifies a one use grant before invoking the mock EC2 action. Replay returns full proposal evidence only to the gateway's launcher-attested caller and delegator; policy status returns only the current revision. Real AWS enforcement also requires IAM and network controls that prevent agents from using direct AWS credentials or bypassing the gateway. See deployment limits.

Disposable AWS pilot

The optional EC2 pilot protects one tagged, running test instance. The mock remains the default. Pilot startup needs a separate test-account config, exact AWS principal and target, and live DescribeInstances; execution defaults to AWS TerminateInstances(DryRun=true). Real termination requires both mutationEnabled: true in that config and a separate OKG_AWS_PILOT_MUTATE launch flag. The AWS guide provides exact IAM setup, bypass preflight, independent MCP client, CloudTrail correlation, and teardown commands. No AWS account is used by npm test or npm run demo:mcp.

Controller and gateway distribution

The controller protocol replaces the shared local policy file as the distributed path. Gateways fetch Ed25519 signed bundles over an authenticated interface, persist a monotonic epoch, acknowledge activation, and obtain a short controller permit before consequential dispatch. The original shared-file demo remains a local example only. Run the two-gateway, two-client, separate-storage scenario and the conformance fixtures and runner from the repository root:

npm run demo:controller
npm run conformance:controller

The observed local measurements include update, acknowledgement, admission and redemption delay, one pending-update rejection, and IEEC outcome reconciliation. The controller demo uses mock actions and no AWS credentials.

The implementer quickstart gives exact commands for a disposable controller, gateway and conformance run.

---

📄 Paper

OpenKedge is backed by a research paper:

👉 arXiv:2604.08601

This work introduces intent-based mutation governance — a shift from direct API execution to structured, policy-controlled decision flows.

---

🎯 From Paper → Code

The core ideas from the paper are implemented here:

Paper Concept	OpenKedge Implementation
Intent	OpenKedgeClient.submitIntent() / SDK
Context Resolution	ContextProvider
Policy Evaluation	AwsSafetyPolicyEvaluator, OPA policy packs, and Cedar adapters
Execution Control	Executor + IdentityManager / execution identity
Evidence Chain	Event store + ReplayEngine

---

🚨 Why OpenKedge?

Modern infrastructure is built on assumptions that no longer hold:

• callers are deterministic
• actions are correct
• context is complete

This breaks in the era of AI agents.

Today’s model:

Agent → API → Immediate Mutation

Leads to:

• unsafe deletions (e.g., terminating live infrastructure)
• conflicting multi-agent updates
• context-blind automation
• cascading failures

👉 The issue is not just the model —
it’s the mutation model.

---

🔐 The OpenKedge Model

OpenKedge introduces a governed mutation pipeline:

Intent → Context → Policy → Contract → Execution → Evidence Chain

---

1. Intent-Governed Mutation

Agents do not execute APIs directly.

They submit:

what they want to achieve

The system evaluates:

• system-wide context
• dependencies
• policy constraints
• multi-agent conflicts

---

2. Execution-Bound Safety

Approved intents are compiled into execution contracts:

• allowed actions
• scoped resources
• strict time bounds

Execution is enforced via ephemeral identities (e.g., AWS STS).

Even if an agent hallucinates, execution is physically constrained.

---

3. Intent-to-Execution Evidence Chain (IEEC)

Every mutation produces a verifiable lineage:

Intent → Context → Policy → Contract → Execution → Outcome

Properties:

• cryptographically linked
• temporally ordered
• fully reconstructable

This enables:

• auditability
• explainability
• forensic debugging

👉 Not just what happened, but why it was allowed

---

🧠 Core Insight

Mutation should not be executed. Mutation should be governed.

---

🏗 Architecture

Key guarantees:

• no direct agent → API execution path
• all mutations pass governance
• execution is strictly bounded
• every step is recorded in IEEC

---

🧪 Example: Safe Instance Termination

❌ Traditional: API-Driven Execution

A user tells an AI agent to terminate 2 EC2 instances. The agent immediately invokes the AWS API:

Action: ec2:TerminateInstances
Instances: [i-0123456789abcdef0, i-0abcdef1234567890]

The problem: If you look at AWS CloudTrail, you only see that the ec2:TerminateInstances API was called. The original user request, the agent's context, and any safety checks (or lack thereof) are never logged. You only see what eventually happened, even if the instances were actively serving production traffic.

---

✅ OpenKedge: Intent-Governed Mutation

OpenKedge forces the AI agent to start from an "intent" and enforces safety checks through policies prior to execution. Everything is recorded in a cryptographically chained log.

1. Intent Submission
The agent cannot call the API directly. It submits an intent:

{
  "action": "terminate_instances",
  "reason": "User requested cleanup of idle environments",
  "targets": ["i-0123456789abcdef0", "i-0abcdef1234567890"]
}

2. Context & Policy Evaluation
OpenKedge evaluates the blast radius against live infrastructure state:

• Context: Are these instances receiving traffic from an active Load Balancer?
• Policy: Does the agent have permissions to terminate instances lacking the env:dev tag?

3. Execution Contract Generation
If approved, OpenKedge generates an immutable execution contract and issues highly-scoped, temporary credentials (e.g., via AWS STS) that only permit terminating those exact two instances within a 5-minute window.

4. Bounded Execution
The mutation occurs. Even if the agent goes rogue, the physical execution is bounded by the credentials—it cannot terminate a third instance.

5. Intent-to-Execution Evidence Chain (IEEC)
Instead of an isolated CloudTrail API event, OpenKedge produces a cryptographically sealed chain:

[Hash1: Intent] → [Hash2: Context] → [Hash3: Policy Approval] → [Hash4: Contract] → [Hash5: Execution Event]

You have complete forensic visibility into why the mutation was allowed, not just that it happened.

---

🚀 Getting Started

git clone https://github.com/openkedge/openkedge
cd openkedge
npm install

Running the Interactive Demo

Experience the OpenKedge safety guarantees in real-time by running the full-stack interactive demo locally. The demo overlays an automated agent attempting a destructive mutation against a mocked context.

You will need two terminals.

Terminal 1: Start the API Engine (Backend)

cd apps/demo-server
npm run dev

Terminal 2: Start the Replay Visualizer (Frontend)

cd apps/replay-ui
npm run dev

1. Navigate to http://localhost:5173/ in your browser.
2. Click Run Outage Simulation
3. Watch the visual timeline demonstrate how the mutation is intercepted, contextualized, and blocked dynamically.

⚠️ Early-stage reference implementation

---

🎬 From Theory to Practice

The paper shows how unsafe mutations happen.

This repo shows how to stop them.

Example: Preventing a Cloud Outage

npm run demo:blast

Excerpt from the real demo output:

=== Terminate 50 instances -> CRITICAL -> blocked ===
{
  "finalOutcome": "blocked",
  "blastRadius": {
    "riskLevel": "CRITICAL"
  },
  "result": {
    "success": false,
    "error": "Blocked by policy: ... Blocked due to CRITICAL blast radius"
  }
}

This is the exact failure mode described in the paper — prevented in real time.

---

Temporal Invariants & Capability Attenuation

The execution engine supports HMAC-signed capabilities from successful reads,
declarative preceding-event rules, sliding quotas, and rate limits. Atomic quota
reservations prevent concurrent agents from overspending; signed execution
contracts bind the intent, prerequisites, and strict credential time bounds.
Indexed IEEC stores are available for memory, SQLite, and Postgres.

Run the demo and click Run Capability Attack or Run Budget Scenario to
see blocked parameter substitution and a shared $500 / 24h budget in replay.
See configuration, semantics, and deployment limits.

npm test
npm run typecheck
npm run bench:temporal

🧩 Use Cases

• AI-driven DevOps automation
• multi-agent systems
• cloud infrastructure safety
• workflow engines with AI integration
• autonomous system governance

---

🔬 Key Contributions

• intent-governed mutation protocol
• execution-bound safety via contracts
• IEEC: verifiable mutation lineage

---

📜 RFCs & Governance

OpenKedge is governed by a formal RFC process to ensure protocol stability and multi-agent interoperability.

• RFC Index: Browse all RFCs, architectural standards, and protocol specifications.
• Intent Governance Protocol (IGP): Our primary specification for intent-based safety.
• Event Evidence Chain (EEC): The mathematical model for verifiable mutation lineage.
• Execution Identity (EI): The ephemeral, intent-scoped security primitive.
• Replay & Simulation API (RSA): Standardized interface for time-travel debugging and "what-if" simulations.
• Protocol Schemas: Machine-readable definitions for Intents and Evidence Chains.

---

🛣 Roadmap

• Core protocol (v0.1)
• AWS adapter (STS + policy integration)
• Policy engine plugins (Cedar / OPA)
• Multi-agent simulation framework
• IEEC visualization UI
• Production SDK

---

🤝 Contributing

We welcome contributions across:

• policy engines
• cloud adapters
• agent integrations
• visualization tools

---

📚 Citation

@article{openkedge2026,
	title = {OpenKedge: Governing Agentic Mutation with Execution-Bound Safety and Evidence Chains},
	author = {He, Jun and Yu, Deying},
	journal = {arXiv preprint arXiv:2604.08601},
	year = {2026},
}

---

📜 License

MIT

---

🌍 Vision

As AI agents become primary operators of infrastructure,
the correctness of individual agents becomes secondary to the correctness of the system governing them.

OpenKedge provides that foundation.

---

⭐ If this resonates

Star the repo and follow the project.

This is just the beginning.