System documentation

Operate one policy across the full agent boundary.

Use this page to choose the first enforcement boundary, wrap a dangerous tool, publish a constitution, and keep action, data, and compute evidence in one proof schema.

Start here

Choose the path that matches your job.

Choose the first boundary

Start with Boundary Choice to decide which part of the agent needs control first: a tool call, MCP authority, CI lane, hosted workflow, database branch, or compute run.

Keep one constitution

Use SDK Quickstart and Adapters, MCP, Scanner to keep the same policy context around the dangerous function and later data or compute boundaries.

Export one proof packet

Use Policy Model, Operations, and Evidence to understand how blocks, branches, protected runs, source-untouched checks, halts, and scanner results become one buyer-readable packet.

Overview

The system in one picture.

Imladri is built around one policy source and one evidence schema. The first deployment can be the surface the team already runs, but the category claim is the combination: blocked actions, governed database branches, and protected compute all becoming one proof packet.

Policy

Publishes what a coding, cloud, database, compute, or privileged automation agent may do, deny, escalate, or require for review.

Runtime enforcement

Performs synchronous allow, deny, branch, sandbox, or compute checks before code pushes, deploys, database mutations, or privileged jobs run.

Evidence

Normalizes action decisions, database branch lifecycle, scanner output, protected compute metadata, halts, and digest state into reviewable proof.

Current proof state

The canonical proof story is now unified. Standard control can begin with SDK frameworks, hosted workflow paths, MCP stdio/client configuration, GitLab/Vercel CI scanner proof, and the OpenClaw/Hermes/MCP/Generic HTTP runtime bridge. Database and compute lanes add stronger proof when the same agent also needs source-isolated data work or protected GPU execution.

Validation snapshot
SignalCurrent resultWhy it matters
Unified proof schemaOne packet shapeAgent decisions, DB branch metadata, CI scans, and compute evidence export into the same buyer-reviewable proof model.
Production buyer-flow smokePassedFresh approved onboarding path, Resend email checks, agent connect/classify/publish/verify/deploy flow, 310s monitoring, proof export, and SDK key rotation.
Runtime-agnostic agent boundary4 runtimesOpenClaw, Hermes, MCP, and Generic HTTP share one policy path; mixed-runtime blocks complete with 0 prohibited body calls.
SDK adopter report71/71 lanes20 SDK adapter families passed the current generated report. MCP and hosted CI are certified separately as product surfaces.
LangChain focused proof4/4 lanesPython and TypeScript LangChain lanes cover wrapped tools, agent tool-loop middleware, ToolNode, and original-tool LangSmith traceable wrappers.
OpenAI Agents focused proof4/4 lanesPython and TypeScript OpenAI Agents SDK lanes cover wrapped function tools retained inside Agent tool lists, JS action aliases for SDK-normalized names, and raw tool-loop guards.
Hosted adopter proof5 surfacesDify, Flowise, n8n, Zapier MCP, and Botpress hosted proof paths passed with allowed-call evidence and zero blocked-path body calls.
Hosted CI proofGitLab + VercelThe scanner runs in hosted CI but stores evidence as Imladri-native proof, not as GitHub-specific state.
Local SDK block0.065ms p95Known-prohibited actions stop before network and before customer code when the constitution is warm.
Live preflight194.45ms p95Halt-aware Worker strict preflight for high-risk actions.
Operator halt74.18ms p95Worker-proxied halt rejected the next enforcement-boundary action with AGENT_HALTED.
5B-row DB sandbox56.84ms p50Twenty governed Postgres COW branches over a verified 5B-row, 690.34 GiB source; 0 source mutations and 6/6 proof checks.
Evidence integritySHA-256 chainAuditor packets carry previousHash, canonicalPayloadHash, entryHash, chain root, and packet digest; private workspace exports are signed with the workspace key.
Adopter proof path

Start local, then move proof into a private workspace after approval.

Public pages stay access-gated: pick one adopter path, run the local wrapper and scanner artifacts, and keep customer accounts closed until the design partner is approved. The approved private workspace then becomes the place to store proof state, MCP authority, CI evidence, and buyer packet exports.

Beta access path

Request access, pick the closest adopter path, and run the local artifact flow. Private workspace access opens only after approval.

What demo blocks and proves
  • CLI doctor confirms service health and SDK auth.
  • Wrapper proves one allowed action and one pre-body denial.
  • Sandbox proof checks branch writes, source isolation, export, and cleanup.
Step 1

Pick

Choose the adopter path, MCP host, CI lane, hosted workflow, runtime bridge, or database branch.

Step 2

Verify

Confirm service health, SDK auth, adapter command, scanner output, and any DB wiring in scope.

Step 3

Prove

Run allowed and blocked wrapper checks, scan the repo, create any required DB branch, export proof, and clean up.

Step 4

Inspect

Review the readable report and JSON evidence locally before a private design-partner workspace is opened.

Artifact path

The combined proof packet is written to tmp/imladri-package/demo-<timestamp>/demo.json. The paired demo.mdis the human-readable proof report with the wrapper denial, DB sandbox lifecycle, source cleanup check, and JSON SHA-256 digest. The public auditor packet sample is available at /proof, with downloadable JSON and a SHA-256 sidecar.

Private workspace alignment

The approved design-partner workspace is the visual version of this path: agent wrapping maps to the adapter boundary, sandboxing maps to the DB branch lifecycle, deployments hold activity and proof, MCP authority issues short-lived tool-host tokens, and proof export holds the buyer packet after review.

Boundary choice

Pick the lightest boundary that gives the guarantee you need.

Imladri does not need to sit in front of every harmless agent step. Put the right boundary around the dangerous capability: local block for known bad actions, strict preflight for high-risk side effects, sandbox for command-shaped work, and database control or database sandbox branches for SQL and production-like write tests.

BoundaryLatency postureNetworkWhen to use it
Local SDK block0.065ms p95NoKnown-prohibited actions with inline or cached constitution state.
Strict preflightabout 195ms p95 live todayYesHigh-risk allowed actions that need live halt or policy state before commit; Access/network is now the dominant cost.
Operator halt74ms p95 Worker pathYesStops following SDK, preflight, sandbox, and database enforcement-boundary actions until review clears the agent.
Sandbox denied before spawnabout 213ms p95YesCommand-shaped actions rejected by halt or constitution before process start.
Sandbox allowed or violatedDecision time plus workload executionYesCommand-shaped actions where execution proof, blocked writes, backend, and network mode matter.
Database executionNetwork plus query timeYesSQL actions that need template, tenant, schema/table, mode, masking, branch isolation, and row proof.
Database sandbox branch56.84ms p50 createYesPostgres copy-on-write branches for agent tests that must prove writes stayed away from the source database.
Honest boundary

Capabilities not routed through the SDK boundary are observable and haltable, but not pre-execution preventable. Dangerous capabilities should be wrapped through wrapped tools, strict preflight, sandboxed actions, or governed database actions.

Strict preflight and sandbox execution both depend on the runtime seeing a fresh published policy. If that cache is stale, the decision can be stale too. The sandbox lane improves the evidence story because allowed work runs under the declared backend, path, and network policy, but cache health is still an operator responsibility.

SDK quickstart

Wrap the privileged action path, not the whole app.

The examples below show the pilot integration path: normal evidence uses the Worker URL, while high-risk strict preflight can point directly at the runtime host for the lower-latency halt boundary. If that endpoint is Cloudflare Access protected, the SDK can attach the pilot service-token headers from environment variables.

python (illustrative)
from imladri import Imladri

imladri = Imladri.from_env()

@imladri.action("cloud.deploy", strict_preflight=True)
def deploy_release(release):
    return deployer.deploy(release)

tools = imladri.wrap_tools(
    {"customer.read": customer_lookup, "email.send": send_email},
    strict_tools=["email.send"],
)

intent = {"customer_id": customer_id, "amount_cents": 5000}
imladri.preflight("payment.refund", intent=intent)
payment_gateway.refund(**intent)
typescript (illustrative)
const agent = new ConstitutionalAgent({
  agentId: process.env.IMLADRI_AGENT_ID!,
  apiKey: process.env.IMLADRI_API_KEY!,
  apiUrl: process.env.IMLADRI_API_URL!,
  preflightUrl: process.env.IMLADRI_PREFLIGHT_URL,
});

const deployRelease = agent.action(
  "cloud.deploy",
  async (changeSet: ReleasePlan) => cloud.deploy(changeSet),
  {
    strictPreflight: true,
    intent: (changeSet) => ({ service: changeSet.service, version: changeSet.version }),
  },
);

await agent.runSandboxedAction("deploy.preview", {
  command: "node",
  args: ["scripts/check-release.mjs"],
  workspaceFiles: [{ path: "plan.json", content: "{}" }],
  outputPaths: ["reports/preview.txt"],
});
Adapters, MCP, scanner

Adopt Imladri without changing agent frameworks.

The beta path now has three integration surfaces: SDK adapters for existing tool objects, an MCP server for tool hosts, and an Imladri-native CI scanner that writes local findings during access review. Private proof workspaces are opened for design partners when the integration moves from public preview into onboarding.

typescript adapters
import {
  ConstitutionalAgent,
  createLangChainMiddleware,
  createOpenAIAgentsToolGuard,
  normalizeOpenAIAgentsToolName,
  wrapLangChainTools,
  wrapLangGraphNodes,
  wrapLlamaIndexTools,
  wrapOpenAIAgentsTools,
  wrapVercelAITools,
  wrapMastraTools,
} from "@imladri/sdk";
import { Agent, tool as openAIAgentsTool } from "@openai/agents";
import { tool } from "langchain";
import { traceable } from "langsmith/traceable";
import * as z from "zod";

const agent = new ConstitutionalAgent({ agentId, apiKey, apiUrl, preflightUrl });

const tracedCustomerLookup = tool(
  traceable(async ({ customerId }) => `customer:${customerId}`, {
    name: "customer.lookup",
    run_type: "tool",
  }),
  {
    name: "customer.lookup",
    description: "Look up a customer by id.",
    schema: z.object({ customerId: z.string() }),
  },
);

const guardedLangChainTools = wrapLangChainTools(agent, [tracedCustomerLookup], {
  strictTools: ["payment.transfer", "cloud.deploy"],
});

const langChainMiddleware = createLangChainMiddleware(agent);
// Pass middleware to the LangChain JS agent setup that owns raw tool dispatch.

const transferAction = "payment.transfer";
const transferToolName = normalizeOpenAIAgentsToolName(transferAction);
const guardedOpenAITools = wrapOpenAIAgentsTools(agent, [
  openAIAgentsTool({
    name: transferToolName,
    description: "Transfer funds after approval.",
    parameters: z.object({ amountUsd: z.number() }),
    execute: async ({ amountUsd }) => ({ ok: true, amountUsd }),
  }),
], {
  strictTools: [transferAction],
  actionAliases: { [transferToolName]: transferAction },
});

const openAIAgent = new Agent({
  name: "Payments operator",
  instructions: "Use tools only for approved workflows.",
  tools: guardedOpenAITools,
});

const openAIGuard = createOpenAIAgentsToolGuard(agent, {
  strictTools: [transferAction],
  actionAliases: { [transferToolName]: transferAction },
});

const guardedGraphNodes = wrapLangGraphNodes(agent, nodes, {
  strictTools: ["secrets.read"],
});

const guardedVercelTools = wrapVercelAITools(agent, aiTools, {
  strictTools: ["email.send"],
});

const guardedLlamaTools = wrapLlamaIndexTools(agent, llamaTools, {
  strictTools: ["customer.data.export"],
});

const guardedMastraTools = wrapMastraTools(agent, mastraTools, {
  strictTools: ["cloud.deploy.production"],
});
mcp + scanner
# MCP server uses short-lived authority from an approved design-partner workspace
IMLADRI_AGENT_ID=<pilot-agent-id> \
IMLADRI_AUTHORITY_TOKEN=<pilot-issued-token> \
IMLADRI_WORKER_URL=https://<worker> \
node mcp-server/server.mjs

# Access preview keeps scanner artifacts local
imladri scan init-ci --provider gitlab --output .gitlab-ci-imladri.yml

IMLADRI_SCAN_WORKER_URL=https://<worker> \
IMLADRI_SCAN_AGENT_ID=<pilot-agent-id> \
IMLADRI_SCAN_SDK_KEY=<pilot-sdk-key> \
imladri scan --path . \
  --config .imladri-scan.json \
  --format json \
  --output imladri-boundary.json \
  --fail-on new

# Private design partners can export a signed proof packet during onboarding
imladri proof export --format json --output imladri-proof.json
Policy model

One schema feeds enforcement and monitoring.

The table below describes the public shape conceptually rather than listing every implementation-facing field name.

FieldTypeUse
Purpose and scopePolicy documentHuman-readable mission and operating shape for the agent.
Hard-deny rulesRule setActions that should never execute on the hot path.
Allowed-path rulesRule setActions that may run under the published policy.
Conditional constraintsRule setAdditional checks attached to more sensitive actions.
Monitored behaviorsRule setBehaviors that stay allowed but receive closer drift review.
Fallback behaviorPolicy modeHow the system treats newly seen or uncategorized actions.
Revision markerVersion idPublished identifier carried into runtime and reports.
Operations

The five operational states you need to reason about.

Allowed

Action passes the hot path and the signed acknowledgement is stored.

Blocked

A denied action or hard rule rejects the request before side effects.

Review required

The action is parked before side effects and recorded for operator approval, which now matters in the governed database lane.

Warned

Semantic drift stays below halt threshold but still becomes part of operator review.

Halted

An agent-level halt stops all future actions until a human clears it.

Evidence

What a signed report needs to contain.

Published policy revision and review context.
Signed runtime decisions with timestamps, body-entry status, and integrity data.
Requested versus effective sandbox backend, network mode, and whether network isolation was actually enforced.
Scoped database credential resolution, approved query template use, and masked result fields when DB control is active.
Source-untouched database assertions with branch-local write and cleanup status.
Actor attribution and export context suitable for audit and security review.
Drift findings with severity and review state.
Human review annotations describing intervention and outcome.
Tamper-evident proof with previousHash, canonicalPayloadHash, entryHash, chain root, and packet digest.
Performance

Current live enforcement sample.

Keep the public docs focused on the enforcement boundaries a customer chooses during integration. Full proof-lane timing history stays in the engineering performance guide; this page carries the numbers that explain the SDK decision.

The live canary is run with tests/bench_production_canary.py. The local microbenchmarks still use tests/bench_agent_overhead.py. Production latency still depends on network, service placement, database choice, and concurrency, so the live runtime numbers are the ones that matter for public claims.

MetricLatest sampleSample basisNotes
Local SDK hard block0.013ms p50 / 0.065ms p95100 blocked attemptsKnown hard-deny actions reject from inline/cached constitution state before network and before customer code.
Worker strict preflight149.34ms p50 / 194.45ms p95100 allowed attemptsLatest live Worker allowed-action burst after the 60s SDK-auth cache TTL, Worker assertion, and queue changes.
Worker blocked preflight104.88ms p50 / 195.85ms p95100 blocked attemptsLatest prohibited payment.transfer burst through the live Worker path.
Operator halt propagation67.87ms p50 / 74.18ms p95Worker pathThe next enforcement-boundary action was rejected with AGENT_HALTED.
Sandbox denied before spawn106.64ms p50 / 212.51ms p95100 blocked attemptsLatest OpenClaw lab sample: live constitution or halt gate rejects before the process or Docker lease starts.
Database sandbox branch56.84ms p50 / 68.95ms p95 create20 COW branches over 5B rowsLatest focused repeat check over a verified 690.34 GiB source: 0 source mutations and 6/6 proof checks.
Enterprise path

What still has to exist for serious enterprise rollout.

The runtime loop is already real. The next enterprise layer is the control plane around it: tenant scope, RBAC, auditability, validation, and data isolation. That path is documented here as rollout context, not as the first integration step.

Organizations and workspaces

Define every privileged resource under a tenant boundary instead of one shared admin surface.

RBAC and service accounts

Move from the current internal admin model to backend-enforced roles, scoped API tokens, and service-account ownership.

Append-only audit logs

Record who changed policy, who exported evidence, who cleared halts, and what request produced the action.

Validation and bounds checking

Standardize input size, path, enum, timeout, and artifact limits across Worker, runtime enforcement, monitoring, and policy services.

Tenant isolation

Make every read and write org-scoped, then tighten encryption, retention, and export controls around that model.

Narrow white-labeling

Brand the portal and report without forking auth, policy semantics, or the data model per customer.

Current honest state

The current hidden dashboard admin path is still an internal operator surface, not the final enterprise auth model. The target architecture is one org and workspace model, backend-enforced roles, append-only audit logs, org-scoped runtime services, and tenant-scoped data across the control plane.

Today's shipped stack already includes signed evidence, selective sandboxing lanes, an access-protected runtime host, and governed database sandbox branches. Broader rollout work should focus on access control, auditability, validation, and tenant isolation around that core.

Pilot path

Start with one dangerous tool, then prove the full boundary.

The fastest useful pilot begins with one side-effectful action, then expands into the category proof: the same constitution governs the tool call, database branch, and protected compute evidence.