Operate one policy across the full agent boundary.
The technical reference and proof evidence are public. Product credentials, Profile, onboarding, and command execution require private-beta approval.
From private-beta approval to buyer proof.
Public customer access is closed. This path begins after private-beta approval: connect the issued Profile workspace, wrap one risky action through terminal or API commands, then review, export, and share the proof packet.
Receive private access
After waitlist approval, receive the Profile workspace and credentials for the scoped private-beta environment.
Install or wrap one agent
With approved access, install the CLI or SDK adapter in the customer repo and wrap the first action where it actually executes.
Run one safe action
Run a safe allowed action first so Profile receives live monitored activity before adding stricter proof lanes.
Confirm activity
Open Profile and confirm the same agent shows the action in monitored activity with policy, source, status, and proof context.
Export proof packet
Export the buyer packet and AI-BOM, verify the digest, and create a redacted share only after Profile marks the packet current.
Need the one-page customer path?
The A-to-Z guide keeps the same flow in one checklist: Profile setup, API/terminal setup, first proof, support bundle, and final acceptance checks.
What the customer needs before the first proof run.
The public path starts with a private-beta waitlist request. The customer uses Profile as the workspace, then runs terminal/API commands from the repo where the agent actually executes.
| Need | Customer-facing detail |
|---|---|
| Profile account | An approved customer receives private account access for Profile setup and the scoped proof trial. |
| Workspace and agent | Customer creates or selects the active Profile agent, gives it a mission, and chooses allowed, review-required, and blocked actions. |
| SDK key | Profile issues or rotates the SDK key. The key belongs in the customer secret manager, not screenshots, decks, public proof links, or browser code. |
| Runtime URLs | Customer uses the Worker URL, action log URL, preflight URL, and agent evidence URL shown by Profile for that workspace. |
| Repo or CI access | Customer runs terminal/API proof from the repo where the agent or scanner actually runs. CI upload uses the same Profile agent id and SDK key. |
IMLADRI_AGENT_ID=<profile-agent-id>
IMLADRI_API_KEY=<profile-sdk-key>
IMLADRI_SDK_KEY=<profile-sdk-key>
IMLADRI_WORKER_URL=https://imladri-beta-api.imladri.workers.dev
IMLADRI_API_URL=https://imladri-beta-api.imladri.workers.dev/api/v1/agent-log
IMLADRI_PREFLIGHT_URL=https://imladri-beta-api.imladri.workers.dev/api/v1/action-preflight
IMLADRI_AGENT_EVIDENCE_URL=<profile-agent-evidence-url>The customer should never need to guess which secret or URL to use. Profile should show the active agent id, SDK key state, Worker URL, proof command, and next action. SDK keys, hosted verification tokens, and provider keys should stay in a secret manager or server environment.
Each customer account has its own API identity map.
Profile is the visual workspace, and the Worker API is the machine-readable workspace. They should agree on the same account id, active agent id, agent subject, route map, monitored activity, proof state, and key fingerprints.
| Workspace part | Customer-facing detail |
|---|---|
| Workspace id | Every customer account receives a workspace id shaped like customer:<account-id>. Profile shows it in Account; Admin can read it back per customer. |
| Active agent id | The active Profile agent id is the id used by terminal/API commands, runtime proof, activity readback, proof export, and proof-share routes. |
| Agent subject | Each agent has a stable subject such as imladri://customer/<account>/agent/<agent>. This is what delegated authority and Admin readback use to prove ownership. |
| SDK key fingerprint | Profile shows fingerprints and active/revoked state. The full key is shown only at rotation time and should stay in server-side secrets. |
| Catalog route | GET /api/customer/api is public and machine-readable. Customers and scripts can use it to see the supported route contract. |
| Readiness route | GET /api/customer/readiness requires the customer session and returns required checks, counts, runtime configuration flags, and next actions. |
| Admin readback | Operators can see the same customer, agent, workspace, route count, activity, key count, and proof readiness in Admin without seeing private SDK key values. |
| # | Route | Path | What the customer uses it for |
|---|---|---|---|
| 1 | Catalog | GET /api/customer/api | Public route contract for customer tooling. |
| 2 | Readiness | GET /api/customer/readiness | Signed-in readiness summary with missing setup steps. |
| 3 | OpenAPI | GET /customer-api.openapi.json | Static machine-readable route schema for setup tooling. |
| 4 | Agent activity | GET /api/customer/agents/:agentId/activity | Recent monitored allowed, blocked, and error events. |
| 5 | Runtime verification | POST /api/customer/agents/:agentId/runtime-test | Profile-driven allowed/blocked proof using the customer SDK key. |
| 6 | Runtime evidence | GET/POST /api/customer/agents/:agentId/runtime-evidence | Latest normalized runtime evidence stored for the agent and terminal/API uploads. |
| 7 | Proof export | GET /api/customer/agents/:agentId/proof-export | JSON, Markdown, or PDF proof packet export. |
| 8 | Proof share | GET/POST /api/customer/agents/:agentId/proof-share | Create, refresh, and list active redacted buyer/auditor proof links. |
| 9 | Authority tokens | GET /api/customer/agents/:agentId/authority-tokens | Delegated authority records for MCP or tool hosts. |
imladri doctor --customer --worker-url "$IMLADRI_WORKER_URL" --remediate
imladri onboard --sandbox --worker-url "$IMLADRI_WORKER_URL" --email "$IMLADRI_PROFILE_EMAIL" --password "$IMLADRI_PROFILE_PASSWORD" --scan-path . --proof-format json --proof-output imladri-proof.json
curl "$IMLADRI_WORKER_URL/api/customer/api"
curl "$IMLADRI_WORKER_URL/api/customer/readiness" -H "Authorization: Bearer $IMLADRI_CUSTOMER_TOKEN"Machine-readable customer API
Use the OpenAPI JSON when building setup scripts, customer checks, or support tooling against the same customer route contract.
Every customer-facing surface and how to know it is working.
Customers do not need every lane on day one. The core path is Profile plus one wrapped risky action. Add scanner, MCP, hosted workflow, database, or compute proof only when that is part of the buyer's real workflow.
| Offering | Where it lives | What it does | Done signal |
|---|---|---|---|
| Profile workspace | Profile | The customer-facing control room for agents, policy, activity, proof, shares, SDK keys, provider setup, DB sandboxing, and account state. | Customer can see the active agent, proof state, recent activity, and next required action. |
| Customer API contract | Worker API | Expose a machine-readable catalog at /api/customer/api and a signed-in readiness summary at /api/customer/readiness. | Customer tooling can verify supported routes and see missing setup steps without guessing. |
| Agent policy | Profile Agent tab | Define the agent mission, allowed actions, review-required actions, blocked actions, unknown-action mode, and publish/verify the policy. | Policy is published, the version changes, and the same agent verifies it. |
| SDK and terminal wrapper | Customer repo | Wrap the risky function or tool where it executes, then run one allowed action and one blocked-before-body action. | Profile shows both events, and the blocked path has zero dangerous body calls. |
| Framework adopters | Adopters pages and Proof tab | Use existing stacks such as LangChain, OpenAI Agents SDK, Vercel AI SDK, LlamaIndex, CrewAI, Haystack, AutoGen, PydanticAI, Semantic Kernel, hosted workflows, MCP, and CI lanes. | The selected adopter path has setup commands and, when in scope, a certification packet synced into Profile. |
| CI scanner | Customer CI or terminal | Run the Imladri-native scanner in GitHub, GitLab, CircleCI, Buildkite, Vercel, Bitbucket, Azure DevOps, or locally. | Scanner output uploads to Profile and appears in the proof packet. |
| MCP authority | Proof tab and MCP host | Issue short-lived authority tokens for MCP hosts instead of giving hosts long-lived SDK keys. | Token is issued for the right subject/scope and MCP evidence is visible when MCP is in scope. |
| Hosted workflow proof | Hosted workflow plus Profile | Use hosted verification endpoints for Dify, Flowise, n8n, Zapier MCP, Botpress, or another hosted surface when the customer uses a hosted product. | A credentialed hosted row passes only when a real verification endpoint and token credentials were loaded. |
| Deployments and activity | Profile Deployments tab | Inspect last seen, observed calls, blocked calls, status, HTTP status, latency, source, authority context, and proof state. | The deployment has recent activity and proof export controls are enabled when evidence is ready. |
| AI-card summary | Profile Home and proof exports | Review each monitored agent as a compact system card with owner, runtime/framework, model/provider, tools, data, compute, authority, policy, activity, and proof state. | Rows are labeled proven, observed, imported, missing, or accepted risk. |
| Proof-health alerts | Profile Home and Proof tabs | Review customer-facing alerts for draft policy, missing activity, missing blocked proof, stale or broad authority, replay drift, detector findings, and expired accepted risks. | The customer sees the next action before sharing a buyer packet. |
| Saved proof evidence | Profile Deployments, Home, and Proof tabs | Save trace replay, red-team, policy-tuning, reviewer note, and accepted-risk records into the proof packet evidence stream. | Saved evidence appears in buyer packet JSON/Markdown without exposing plaintext secrets. |
| Proof export and share | Proof and Deployments tabs | Export JSON, Markdown, or PDF proof and create an auditor-redacted buyer link after verification. | Public readback verifies and the share does not expose private workspace evidence. |
| Public proof verifier | Browser or CLI | Verify exported JSON proof through /verify-proof or imladri proof verify before sending it to a buyer or auditor. | Digest, public signature when available, and hash-chain checks pass. |
| Detector lanes | Boundary scanner and Proof tab | Run prompt-injection, secret, PII, URL, unsafe-content, custom-topic, and tool-argument detector checks alongside the action-boundary scanner. | Detector findings are absent, fixed, explicitly reviewed, or accepted with expiration before proof sharing. |
| OTLP/OpenInference export | AI-BOM and buyer packet | Export Imladri proof events as span-shaped JSON so proof context can sit beside observability stacks. | Imported or exported spans are observability context; enforcement truth remains the signed Profile evidence. |
| Release-agent package | Focused workflow | Use the release-agent workflow package when the buyer needs one concrete code/cloud deployment proof path. | Allowed deployment proof, blocked credential proof, scanner evidence, verified packet, and cleanup all pass. |
| Database sandbox | Profile Sandbox tab | Create a governed DB branch, run signed SQL transactions, prove source data was untouched, export proof, and destroy the branch. | Branch proof exists, source mutation check passes, and the branch is destroyed after use. |
| Protected provider training | Profile Providers and Training tabs | Verify provider credentials, launch protected provider training, monitor callbacks, stop/delete workloads, and export proof. | Provider key is verified, auto-stop is set, run evidence appears, and provider resources are stopped or deleted. |
| Account and keys | Profile Account tab | Review account state, identity, SDK keys, rotation, active/revoked fingerprints, and logout. | Active keys are known, old keys are revoked when rotated, and sensitive values are not exposed. |
| Support bundle | Profile Account tab | Export a customer support bundle with account id, workspace id, route map, key fingerprints, recent activity, shares, scans, certifications, and proof digest. | The bundle excludes plaintext SDK keys, passwords, provider keys, hosted tokens, authority tokens, and raw private payloads. |
Prove one allowed path and one blocked path.
The first useful setup is intentionally narrow: pick the framework or tool host the customer already uses, wrap one side-effectful action, run the allowed case, then run the blocked case and confirm the dangerous body never executes.
Runs in the customer repo. This is where the wrapper, scanner, adapter certification, and allowed/blocked proof commands produce evidence from the actual execution path.
Runs in the customer workspace. This is where the team sees monitored activity, proof readiness, scanner state, MCP authority, exports, and buyer/auditor sharing.
Use the adopter path for the customer's framework, then run the proof command that syncs evidence to Profile. The reference view keeps the detailed SDK and adapter examples.
imladri proof run --worker-url "$IMLADRI_WORKER_URL" --agent-id "$IMLADRI_AGENT_ID" --allowed-action ticket.summarize --blocked-action credential.access_request --stack "Existing agent" --proof-need "Show blocked-before-body proof for the buyer"| Customer need | Use | Why |
|---|---|---|
| Known bad action | Local SDK block | Use inline or cached constitution state to reject before network and before customer code. |
| High-risk allowed action | Strict preflight | Prepare the intent, call live policy/halt preflight, then commit only after approval. |
| Existing framework tool | SDK adapter | Use the adopter page for the framework and wrap the tool object without replacing the whole agent. |
| Repo or pull-request review | CI scanner | Run scanner locally or in CI and upload the boundary report to Profile. |
| MCP tool host | MCP authority token | Issue short-lived Profile authority for the host instead of a long-lived SDK key. |
| Hosted workflow | Hosted adopter verification | Call the customer hosted workflow through a credentialed verification endpoint when that surface is part of the proof. |
| SQL or data mutation | Database action or DB sandbox | Use governed DB actions for runtime SQL and sandbox branches for isolated write proof. |
| Provider workload | Protected training lane | Use Providers and Training only when the customer needs compute proof and accepts provider cost controls. |
Customers should know what they are looking at.
Profile is not another setup checklist. It is the review surface for evidence produced by the terminal/API half. The customer should be able to confirm the current proof state without reading raw JSON first.
| Profile area | What the customer confirms |
|---|---|
| Home | Choose the stack, risky action, and buyer proof need; run complete proof or share proof when the first packet is ready. |
| Agent | Connect the real agent, classify allowed/review/blocked actions, publish policy, verify policy, prepare the SDK key, and deploy or unwrap when needed. |
| Deployments | Inspect live state, recent activity, observed and blocked calls, source, HTTP status, latency, authority context, redaction mode, and proof exports. |
| Proof | Refresh proof, review Profile verification status, inspect scanner and SDK certification packets, issue MCP authority tokens, create buyer shares, and copy package commands. |
| Providers | Choose a configured provider, verify credentials, set budget/runtime/auto-stop, and prepare the protected training workload. |
| Training | Monitor provider training deployments, callbacks, status, stop/delete state, and evidence produced by protected compute runs. |
| Sandbox | Create DB sandbox sessions, run signed read/write transactions, export proof, diagnose policy/RLS/security-invoker issues, and destroy branches. |
| Account | Review identity, account state, SDK key fingerprints, active/revoked keys, password state, and logout. |
Share proof only after the packet reads cleanly.
The buyer packet should answer simple questions: what agent acted, what policy was active, what was allowed, what was blocked before side effects, whether source data changed, and whether the evidence chain can be replayed from hashes.
Open the current proof packet and inspect the allowed action, blocked denial, scanner evidence, chain root, and packet digest.
Use the auditor-redacted share for external buyers and keep private workspace details inside Profile.
Use the public readback or verifier flow before sending the link to a buyer or auditor.
| Packet area | What the customer checks |
|---|---|
| Agent and policy | Active Profile agent, published policy version, mission, allowed/review/blocked actions, and unknown-action mode. |
| Allowed evidence | At least one allowed action from the wrapped runtime path with timestamp, source, latency, and proof context. |
| Blocked evidence | At least one denied or halt-required action blocked before the dangerous body or committed side effect. |
| Scanner and adopter evidence | CI scanner upload and SDK/adopter certification rows when those lanes are part of the customer proof. |
| AI-card and proof health | Agent summary rows, proof-health alerts, saved trace replay evidence, detector findings, and accepted-risk state. |
| MCP or hosted evidence | Authority-token and hosted verification rows only when MCP or hosted workflow products are in scope. |
| Data or compute evidence | DB branch/source-write proof and protected training evidence only when the customer uses those lanes. |
| Integrity data | SHA-256 digest metadata, chain root, packet digest, redaction context, and signature metadata when configured. |
| Share status | Buyer/auditor link is created only after verification and public readback succeeds. |
Add stronger lanes only when the customer needs them.
The first proof packet should stay narrow. After the wrapped agent path works, customers can add database, provider, hosted workflow, MCP, or CI evidence to the same Profile evidence model when the buyer needs those assurances.
Use after agent-action proof works and the customer needs proof that database writes stay isolated from the source. Customer should export proof and destroy the branch after the session.
Use when the customer needs provider compute proof. Customer should verify provider key, set budget/runtime/auto-stop, monitor Training, and stop/delete resources.
Use when the buyer runs a hosted workflow product. Missing hosted credentials should be reported honestly instead of claimed as a pass.
Use when an MCP host needs delegated tool authority. Authority tokens should be short-lived and scoped; MCP hosts should not receive long-lived SDK keys.
Use for repo boundary proof. CI vendors are runners only; the evidence stays Imladri-native and uploads to Profile.
Fast checks when the flow does not move.
| Symptom | First check |
|---|---|
| No activity in Profile | Check the agent id, SDK key, Worker URL, and whether the terminal/API command used the same workspace. |
| Allowed proof works, blocked proof missing | Confirm the risky action is listed as strict or hard-deny in the published policy before rerunning the proof. |
| Adapter certification failed | Open the adopter path, rerun the focused adapter command, then sync the fresh artifact to Profile. |
| Scanner output missing | Run the scanner from the repo root and confirm the output path is attached to the current workspace proof run. |
| MCP tool host cannot connect | Confirm the authority token is active, not expired, scoped for the host, and that the MCP host is not using a long-lived SDK key. |
| Hosted workflow row is not passed | Confirm the hosted verification endpoint and token are configured for that hosted product; missing credentials should stay visible as missing, not passed. |
| DB sandbox proof missing | Confirm the target id, allowed relation, SDK key, runtime base URL, session status, and whether the branch was destroyed before export. |
| Training status is stuck | Confirm provider key verification, budget/runtime limits, auto-stop, provider callback activity, and whether the provider pod/container still exists. |
| Share link unavailable | Refresh proof status first; sharing is blocked until Profile has a current verified packet. |
What runs locally, what Profile shows, and what buyers see.
Terminal/API wrapping runs from the customer repo so the risky action is controlled at the execution boundary.
Profile stores monitored activity, proof status, redacted shares, and buyer-readable packet history.
Proof packets carry ordered chain entries, a chain root, packet digest, and redaction context.
Use the browser verifier at /verify-proof or the CLI command imladri proof verify --input <proof.json> before sharing auditor evidence.
Prompt-injection and sensitive-data findings help reviewers decide what to fix or accept; prevention still requires routing the side effect through Imladri.
Use redacted public shares for buyers and keep sensitive workspace evidence inside the approved customer workspace.
Capabilities not routed through wrapped tools, strict preflight, sandboxed actions, or governed DB actions are observable and haltable, but not pre-execution preventable.
SDK keys, hosted verification tokens, provider keys, and service tokens belong in secret managers or server environments, never browser-side code.
Provider runs should have auto-stop enabled. Customers should stop/delete pods, remove exposed keys from local environment, and rotate any shown provider key.
The customer is done when these signals are true.
Use this as the final acceptance checklist for the first customer proof. Anything outside the customer's selected scope should be marked not in scope rather than hidden or implied.
| Area | Acceptance signal |
|---|---|
| Access | Approved customer can use issued credentials to see the correct private Profile workspace and active agent. |
| Policy | The agent mission and action lists are published and verified with the same connected agent. |
| Runtime wrapper | One allowed action and one blocked-before-body action have run from the customer repo or API path. |
| Profile readback | Home, Deployments, and Proof show current activity, proof status, latency/source context, and the selected redaction mode. |
| Integration lane | The customer-selected adopter, CI scanner, MCP, hosted workflow, DB sandbox, or training lane is either passed in Profile or marked honestly as not in scope. |
| Proof packet | JSON/Markdown/PDF export or public auditor share verifies, includes integrity metadata, and omits private secrets. |
| Cleanup | Old SDK keys are revoked when rotated, provider pods are stopped/deleted, DB sandbox branches are destroyed, and no secrets are left in screenshots or generated docs. |
| Support handoff | If anything is stuck, customer can run doctor and export the Account support bundle without exposing plaintext secrets. |
Start with one risky action and one proof packet.
The easiest customer path is one framework, one policy, one allowed call, one blocked call, then a buyer packet that Profile can verify and share.
Choose the path that matches your job.
Start with one action that needs control first: a tool call, MCP authority, CI lane, hosted workflow, database branch, or compute run.
Use SDK Quickstart and Adapters, MCP, Scanner to keep the same policy context around the dangerous function while generating evidence from the customer repo.
Use Profile to review monitored activity, proof history, public proof shares, blocks, branches, protected runs, halts, and scanner results in one buyer-readable packet.
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.
Publishes what a coding, cloud, database, compute, or privileged automation agent may do, deny, escalate, or require for review.
Performs synchronous allow, deny, branch, sandbox, or compute checks before code pushes, deploys, database mutations, or privileged jobs run.
Normalizes action decisions, database branch lifecycle, scanner output, protected compute metadata, halts, and digest state into reviewable proof.
The canonical proof story is now unified. Standard control can begin with terminal/API proof commands for SDK frameworks, hosted workflow paths, MCP stdio/client configuration, GitLab/Vercel CI scanner proof, and the OpenClaw/Hermes/MCP/Generic HTTP runtime bridge. Profile is the customer workspace where that evidence is monitored, verified, exported, and shared. Database and compute lanes add stronger proof when the same agent also needs source-isolated data work or protected provider execution.
| Signal | Current result | Why it matters |
|---|---|---|
| Unified proof schema | One packet shape | Agent decisions, DB branch metadata, CI scans, and compute evidence export into the same buyer-reviewable proof model. |
| Adopter proof pages | Per adopter | Each adopter page now carries its public proof lane, certification status, latest run date, CI gate, owner action, and Profile handoff notes. |
| Production buyer-flow verification | Passed | Fresh approved onboarding path, Resend email checks, agent connect/classify/publish/verify/deploy flow, terminal proof sync, 310s monitoring, proof export/share, and SDK key rotation. |
| Runtime-agnostic agent boundary | 4 runtimes | OpenClaw, Hermes, MCP, and Generic HTTP share one policy path; mixed-runtime blocks complete with 0 prohibited body calls. |
| SDK adopter report | 71/71 lanes | 20 SDK adapter families passed the current generated report. MCP and hosted CI are certified separately as product surfaces. |
| LangChain focused proof | 4/4 lanes | Python and TypeScript LangChain lanes cover wrapped tools, agent tool-loop middleware, ToolNode, and original-tool LangSmith traceable wrappers. |
| OpenAI Agents focused proof | 4/4 lanes | Python 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. |
| Vercel AI SDK focused proof | 2/2 lanes | TypeScript Vercel AI SDK lanes cover direct tool.execute, generateText and streamText tool loops, JS-safe tool-key aliases, forwarded toolCallId metadata, and zero blocked-path body calls. |
| LlamaIndex focused proof | 4/4 lanes | Python and TypeScript LlamaIndex lanes cover FunctionTool.call, metadata.name preservation, action aliases, and zero blocked-path body calls. |
| CrewAI focused proof | 4/4 lanes | Python real-package CrewAI lanes cover Tool.run, Tool._run, CrewStructuredTool.invoke, action_aliases, 3 allowed body calls, and zero blocked-path body calls. |
| Haystack focused proof | 4/4 lanes | Python real-package haystack-ai lanes cover component.run, Pipeline.run, action_aliases, 2 allowed body calls, and zero blocked-path body calls. |
| AutoGen focused proof | 4/4 lanes | Python real-package autogen-core lanes cover FunctionTool.run_json, FunctionTool.run, action_aliases, 2 allowed body calls, and zero blocked-path body calls. |
| PydanticAI focused proof | 2/2 lanes | Python real-package pydantic-ai lanes cover Tool.function_schema.call, Agent.run_sync, FunctionToolset, action_aliases, 2 allowed body calls, and zero blocked-path body calls. |
| Semantic Kernel focused proof | 4/4 lanes | Python real-package semantic-kernel lanes cover KernelFunction.invoke, Kernel.invoke plugin dispatch, action_aliases, 2 allowed body calls, and zero blocked-path body calls. |
| Remaining adopter batch proof | 19 surfaces | LangGraph, Mastra, DSPy, Dify, Flowise, n8n, Zapier AI, Botpress, Rasa, and smolagents share alias-aware metadata.name mapping, strict preflight, and zero blocked-path body calls. |
| Hosted adopter proof | Credentialed lanes | Dify, Flowise, n8n, Zapier MCP, and Botpress are credentialed hosted proof paths; each lane is claimed only when its current URL/token artifact passes. |
| Hosted CI proof | GitLab + Vercel | The scanner runs in hosted CI but stores evidence as Imladri-native proof, not as GitHub-specific state. |
| Local SDK block | 0.065ms p95 | Known-prohibited actions stop before network and before customer code when the constitution is warm. |
| Live preflight | 194.45ms p95 | Halt-aware Worker strict preflight for high-risk actions. |
| Operator halt | 74.18ms p95 | Worker-proxied halt rejected the next enforcement-boundary action with AGENT_HALTED. |
| 5B-row DB sandbox | 56.84ms p50 | Twenty governed Postgres COW branches over a verified 5B-row, 690.34 GiB source; 0 source mutations and 6/6 proof checks. |
| Evidence integrity | SHA-256 chain | Auditor packets carry previousHash, canonicalPayloadHash, entryHash, chain root, and packet digest; Profile exports are signed with the workspace key. |
Wrap locally, then prove it in Profile.
The customer-facing flow is intentionally split. Terminal and API commands run from the customer repo so the risky action is wrapped where it executes. Profile is the visual proof layer: it shows monitored activity, proof readiness, MCP authority, CI evidence, and the buyer/auditor share.
After approval, connect the issued Profile workspace, publish policy, copy the agent id and SDK key into the repo, then run the terminal/API proof path against the customer agent.
- Terminal commands confirm Profile auth, SDK key state, and the active policy.
- Wrapper proof records one allowed action and one blocked-before-body denial.
- Profile shows synced activity, proof history, scanner status, and the shareable buyer packet.
Pick
Choose the adopter path, MCP host, CI lane, hosted workflow, runtime bridge, or database branch.
Wrap
Publish policy in Profile, rotate or paste the SDK key, and run the terminal/API wrapper around the risky action.
Sync
Run allowed and blocked proof, upload scanner or certification evidence, and confirm Profile activity readback.
Share
Export or create a public buyer/auditor proof link after Profile verifies the current packet.
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. For the current customer path, use imladri proof runto sync action evidence to Profile, then imladri proof share --verify-publicto create and read back the auditor-redacted link.
Profile is the visual version of the terminal/API 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.
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 verification.
| Boundary | Latency posture | Network | When to use it |
|---|---|---|---|
| Local SDK block | 0.065ms p95 | No | Known-prohibited actions with inline or cached constitution state. |
| Strict preflight | about 195ms p95 live today | Yes | High-risk allowed actions that need live halt or policy state before commit; Access/network is now the dominant cost. |
| Operator halt | 74ms p95 Worker path | Yes | Stops following SDK, preflight, sandbox, and database enforcement-boundary actions until review clears the agent. |
| Sandbox denied before spawn | about 213ms p95 | Yes | Command-shaped actions rejected by halt or constitution before process start. |
| Sandbox allowed or violated | Decision time plus workload execution | Yes | Command-shaped actions where execution proof, blocked writes, backend, and network mode matter. |
| Database execution | Network plus query time | Yes | SQL actions that need template, tenant, schema/table, mode, masking, branch isolation, and row proof. |
| Database sandbox branch | 56.84ms p50 create | Yes | Postgres copy-on-write branches for agent validation that must prove writes stayed away from the source database. |
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.
Wrap the privileged action path, not the whole app.
The examples below show the current customer 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 workspace service-token headers from environment variables.
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 = {"service": release.service, "version": release.version}
imladri.preflight("cloud.deploy", intent=intent)
deployer.deploy(release)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"],
});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. The CLI/API path generates evidence from the customer repo; Profile receives scanner, certification, MCP, activity, and proof-share state for review.
import {
ConstitutionalAgent,
createLangChainMiddleware,
createOpenAIAgentsToolGuard,
normalizeOpenAIAgentsToolName,
wrapLangChainTools,
wrapLangGraphNodes,
wrapLlamaIndexTools,
wrapOpenAIAgentsTools,
wrapVercelAITools,
wrapMastraTools,
} from "@imladri/sdk";
import { Agent, tool as openAIAgentsTool } from "@openai/agents";
import { tool as aiTool } from "ai";
import { FunctionTool as LlamaIndexFunctionTool } from "llamaindex";
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: ["credential.export", "cloud.deploy"],
});
const langChainMiddleware = createLangChainMiddleware(agent);
// Pass middleware to the LangChain JS agent setup that owns raw tool dispatch.
const exportAction = "credential.export";
const exportToolName = normalizeOpenAIAgentsToolName(exportAction);
const guardedOpenAITools = wrapOpenAIAgentsTools(agent, [
openAIAgentsTool({
name: exportToolName,
description: "Export a credential bundle after approval.",
parameters: z.object({ systemId: z.string() }),
execute: async ({ systemId }) => ({ ok: true, systemId }),
}),
], {
strictTools: [exportAction],
actionAliases: { [exportToolName]: exportAction },
});
const openAIAgent = new Agent({
name: "Credential operator",
instructions: "Use tools only for approved workflows.",
tools: guardedOpenAITools,
});
const openAIGuard = createOpenAIAgentsToolGuard(agent, {
strictTools: [exportAction],
actionAliases: { [exportToolName]: exportAction },
});
const guardedGraphNodes = wrapLangGraphNodes(agent, nodes, {
strictTools: ["secrets.read"],
});
const guardedVercelTools = wrapVercelAITools(agent, {
sendEmail: aiTool({
description: "Send a customer email after approval.",
inputSchema: z.object({ to: z.string().email(), body: z.string() }),
execute: async ({ to, body }, { toolCallId }) => ({ sent: to, toolCallId }),
}),
}, {
strictTools: ["email.send"],
actionAliases: { sendEmail: "email.send" },
});
const guardedLlamaTools = wrapLlamaIndexTools(agent, [
LlamaIndexFunctionTool.from(
({ customerId }) => ({ exported: customerId }),
{ name: "customerExport", description: "Export approved customer data." },
),
], {
strictTools: ["customer.data.export"],
actionAliases: { customerExport: "customer.data.export" },
});
const guardedMastraTools = wrapMastraTools(agent, mastraTools, {
strictTools: ["cloud.deploy.production"],
});from crewai.tools import tool as crewai_tool
from crewai.tools.base_tool import Tool
from crewai.tools.structured_tool import CrewStructuredTool
from imladri.adapters import wrap_crewai_tools
@crewai_tool("customer_export")
def customer_export(customer_id: str) -> str:
"""Export approved customer data."""
return f"exported:{customer_id}"
def summarize_ticket(ticket_id: str) -> dict:
return {"summary": ticket_id}
def lookup_inventory(sku: str) -> dict:
return {"sku": sku, "available": True}
guarded_crewai_tools = wrap_crewai_tools(
agent,
[
customer_export,
Tool(name="ticket_summarize", description="Summarize ticket", func=summarize_ticket),
CrewStructuredTool.from_function(
func=lookup_inventory,
name="inventory_lookup",
description="Look up inventory",
),
],
strict_tools=["customer.data.export"],
action_aliases={
"customer_export": "customer.data.export",
"ticket_summarize": "ticket.summarize",
"inventory_lookup": "inventory.lookup",
},
)
# Pass guarded_crewai_tools into the CrewAI Agent/Task/Crew path that owns execution.from haystack import Pipeline, component
from imladri.adapters import wrap_haystack_components
@component
class CustomerExport:
@component.output_types(result=dict)
def run(self, customer_id: str):
return {"result": {"exported": customer_id}}
@component
class TicketSummarizer:
@component.output_types(result=dict)
def run(self, ticket_id: str):
return {"result": {"summary": ticket_id}}
guarded_haystack_components = wrap_haystack_components(
agent,
{
"customer_export": CustomerExport(),
"ticket_summarize": TicketSummarizer(),
},
strict_tools=["customer.data.export"],
action_aliases={
"customer_export": "customer.data.export",
"ticket_summarize": "ticket.summarize",
},
)
pipeline = Pipeline()
pipeline.add_component("ticket_summarize", guarded_haystack_components["ticket_summarize"])
direct_result = guarded_haystack_components["customer_export"].run(customer_id="cust_123")
pipeline_result = pipeline.run({"ticket_summarize": {"ticket_id": "T-100"}})from autogen_core import CancellationToken
from autogen_core.tools import FunctionTool
from imladri.adapters import wrap_autogen_tools
def customer_lookup(customer_id: str) -> dict:
return {"customer_id": customer_id}
def credential_export(system_id: str) -> dict:
return {"exported": system_id}
guarded_autogen_tools = wrap_autogen_tools(
agent,
[
FunctionTool(customer_lookup, description="Lookup customer", name="customer_lookup"),
FunctionTool(credential_export, description="Export credential bundle", name="credential_export"),
],
strict_tools=["customer.lookup"],
action_aliases={
"customer_lookup": "customer.lookup",
"credential_export": "credential.export",
},
)
# Await run_json or run inside the AutoGen async execution path.
result = await guarded_autogen_tools[0].run_json(
{"customer_id": "cust_123"},
CancellationToken(),
)from pydantic_ai import Agent, FunctionToolset, Tool
from pydantic_ai.models.test import TestModel
from imladri.adapters import wrap_pydanticai_tools
def customer_lookup(customer_id: str) -> dict:
return {"customer_id": customer_id}
def ticket_summarize(ticket_id: str) -> dict:
return {"ticket_id": ticket_id}
guarded_pydanticai_tools = wrap_pydanticai_tools(
agent,
[
Tool(customer_lookup, name="customer_lookup", description="Lookup customer"),
FunctionToolset([
Tool(ticket_summarize, name="ticket_summarize", description="Summarize ticket"),
]),
],
strict_tools=["customer.lookup"],
action_aliases={
"customer_lookup": "customer.lookup",
"ticket_summarize": "ticket.summarize",
},
)
test_agent = Agent(
TestModel(call_tools=["customer_lookup"]),
tools=[guarded_pydanticai_tools[0]],
)
result = test_agent.run_sync("Look up the approved customer.")from semantic_kernel import Kernel
from semantic_kernel.functions import KernelArguments, KernelFunction, KernelPlugin, kernel_function
from imladri.adapters import wrap_semantic_kernel_functions
@kernel_function(name="customer_lookup", description="Lookup customer")
def customer_lookup(customer_id: str) -> dict:
return {"customer_id": customer_id}
@kernel_function(name="ticket_summarize", description="Summarize ticket")
def ticket_summarize(ticket_id: str) -> dict:
return {"ticket_id": ticket_id}
guarded_kernel_functions = wrap_semantic_kernel_functions(
agent,
[
KernelFunction.from_method(customer_lookup, plugin_name="support"),
KernelPlugin(
name="support",
functions=[KernelFunction.from_method(ticket_summarize, plugin_name="support")],
),
],
strict_tools=["customer.lookup"],
action_aliases={
"customer_lookup": "customer.lookup",
"ticket_summarize": "ticket.summarize",
},
)
result = await guarded_kernel_functions[0].invoke(
Kernel(),
KernelArguments(customer_id="cust_123"),
)# MCP server uses short-lived authority from an approved customer workspace
IMLADRI_AGENT_ID=<agent-id> \
IMLADRI_AUTHORITY_TOKEN=<workspace-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=<agent-id> \
IMLADRI_SCAN_SDK_KEY=<profile-sdk-key> \
imladri scan --path . \
--config .imladri-scan.json \
--format json \
--output imladri-boundary.json \
--fail-on new
# Customers can export a signed proof packet during onboarding
imladri proof export --format json --output imladri-proof.jsonOne schema feeds enforcement and monitoring.
The table below describes the public shape conceptually rather than listing every implementation-facing field name.
| Field | Type | Use |
|---|---|---|
| Purpose and scope | Policy document | Human-readable mission and operating shape for the agent. |
| Hard-deny rules | Rule set | Actions that should never execute on the hot path. |
| Allowed-path rules | Rule set | Actions that may run under the published policy. |
| Conditional constraints | Rule set | Additional checks attached to more sensitive actions. |
| Monitored behaviors | Rule set | Behaviors that stay allowed but receive closer drift review. |
| Fallback behavior | Policy mode | How the system treats newly seen or uncategorized actions. |
| Revision marker | Version id | Published identifier carried into runtime and reports. |
The five operational states you need to reason about.
Action passes the hot path and the signed acknowledgement is stored.
A denied action or hard rule rejects the request before side effects.
The action is parked before side effects and recorded for operator approval, which now matters in the governed database lane.
Semantic drift stays below halt threshold but still becomes part of operator review.
An agent-level halt stops all future actions until a human clears it.
What a signed report needs to contain.
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.
| Metric | Latest sample | Sample basis | Notes |
|---|---|---|---|
| Local SDK hard block | 0.013ms p50 / 0.065ms p95 | 100 blocked attempts | Known hard-deny actions reject from inline/cached constitution state before network and before customer code. |
| Worker strict preflight | 149.34ms p50 / 194.45ms p95 | 100 allowed attempts | Latest live Worker allowed-action burst after the 60s SDK-auth cache TTL, Worker assertion, and queue changes. |
| Worker blocked preflight | 104.88ms p50 / 195.85ms p95 | 100 blocked attempts | Latest prohibited credential-access burst through the live Worker path. |
| Operator halt propagation | 67.87ms p50 / 74.18ms p95 | Worker path | The next enforcement-boundary action was rejected with AGENT_HALTED. |
| Sandbox denied before spawn | 106.64ms p50 / 212.51ms p95 | 100 blocked attempts | Latest OpenClaw lab sample: live constitution or halt gate rejects before the process or Docker lease starts. |
| Database sandbox branch | 56.84ms p50 / 68.95ms p95 create | 20 COW branches over 5B rows | Latest focused repeat check over a verified 690.34 GiB source: 0 source mutations and 6/6 proof checks. |
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.
Define every privileged resource under a tenant boundary instead of one shared admin surface.
Move from the current internal admin model to backend-enforced roles, scoped API tokens, and service-account ownership.
Record who changed policy, who exported evidence, who cleared halts, and what request produced the action.
Standardize input size, path, enum, timeout, and artifact limits across Worker, runtime enforcement, monitoring, and policy services.
Make every read and write org-scoped, then tighten encryption, retention, and export controls around that model.
Brand the portal and report without forking auth, policy semantics, or the data model per customer.
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.
Start with one dangerous tool, then prove the full boundary.
The fastest useful proof trial 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.
