System documentation

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.

Customer guide

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.

01

Receive private access

After waitlist approval, receive the Profile workspace and credentials for the scoped private-beta environment.

02

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.

03

Run one safe action

Run a safe allowed action first so Profile receives live monitored activity before adding stricter proof lanes.

04

Confirm activity

Open Profile and confirm the same agent shows the action in monitored activity with policy, source, status, and proof context.

05

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.

Open A-to-Z guide
Access + setup

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.

NeedCustomer-facing detail
Profile accountAn approved customer receives private account access for Profile setup and the scoped proof trial.
Workspace and agentCustomer creates or selects the active Profile agent, gives it a mission, and chooses allowed, review-required, and blocked actions.
SDK keyProfile issues or rotates the SDK key. The key belongs in the customer secret manager, not screenshots, decks, public proof links, or browser code.
Runtime URLsCustomer uses the Worker URL, action log URL, preflight URL, and agent evidence URL shown by Profile for that workspace.
Repo or CI accessCustomer 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.
environment
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>
Customer expectation

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.

API workspace

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 partCustomer-facing detail
Workspace idEvery 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 idThe active Profile agent id is the id used by terminal/API commands, runtime proof, activity readback, proof export, and proof-share routes.
Agent subjectEach 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 fingerprintProfile shows fingerprints and active/revoked state. The full key is shown only at rotation time and should stay in server-side secrets.
Catalog routeGET /api/customer/api is public and machine-readable. Customers and scripts can use it to see the supported route contract.
Readiness routeGET /api/customer/readiness requires the customer session and returns required checks, counts, runtime configuration flags, and next actions.
Admin readbackOperators can see the same customer, agent, workspace, route count, activity, key count, and proof readiness in Admin without seeing private SDK key values.
Core API routes
#RoutePathWhat the customer uses it for
1CatalogGET /api/customer/apiPublic route contract for customer tooling.
2ReadinessGET /api/customer/readinessSigned-in readiness summary with missing setup steps.
3OpenAPIGET /customer-api.openapi.jsonStatic machine-readable route schema for setup tooling.
4Agent activityGET /api/customer/agents/:agentId/activityRecent monitored allowed, blocked, and error events.
5Runtime verificationPOST /api/customer/agents/:agentId/runtime-testProfile-driven allowed/blocked proof using the customer SDK key.
6Runtime evidenceGET/POST /api/customer/agents/:agentId/runtime-evidenceLatest normalized runtime evidence stored for the agent and terminal/API uploads.
7Proof exportGET /api/customer/agents/:agentId/proof-exportJSON, Markdown, or PDF proof packet export.
8Proof shareGET/POST /api/customer/agents/:agentId/proof-shareCreate, refresh, and list active redacted buyer/auditor proof links.
9Authority tokensGET /api/customer/agents/:agentId/authority-tokensDelegated authority records for MCP or tool hosts.
terminal
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.

Open OpenAPI JSON
What we offer

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.

OfferingWhere it livesWhat it doesDone signal
Profile workspaceProfileThe 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 contractWorker APIExpose 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 policyProfile Agent tabDefine 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 wrapperCustomer repoWrap 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 adoptersAdopters pages and Proof tabUse 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 scannerCustomer CI or terminalRun 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 authorityProof tab and MCP hostIssue 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 proofHosted workflow plus ProfileUse 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 activityProfile Deployments tabInspect 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 summaryProfile Home and proof exportsReview 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 alertsProfile Home and Proof tabsReview 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 evidenceProfile Deployments, Home, and Proof tabsSave 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 shareProof and Deployments tabsExport 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 verifierBrowser or CLIVerify 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 lanesBoundary scanner and Proof tabRun 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 exportAI-BOM and buyer packetExport 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 packageFocused workflowUse 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 sandboxProfile Sandbox tabCreate 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 trainingProfile Providers and Training tabsVerify 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 keysProfile Account tabReview 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 bundleProfile Account tabExport 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.
Wrap agent

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.

Terminal/API half

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.

Profile half

Runs in the customer workspace. This is where the team sees monitored activity, proof readiness, scanner state, MCP authority, exports, and buyer/auditor sharing.

First-pass command shape

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.

terminal
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"
Pick adopter path
Which boundary should I choose?
Customer needUseWhy
Known bad actionLocal SDK blockUse inline or cached constitution state to reject before network and before customer code.
High-risk allowed actionStrict preflightPrepare the intent, call live policy/halt preflight, then commit only after approval.
Existing framework toolSDK adapterUse the adopter page for the framework and wrap the tool object without replacing the whole agent.
Repo or pull-request reviewCI scannerRun scanner locally or in CI and upload the boundary report to Profile.
MCP tool hostMCP authority tokenIssue short-lived Profile authority for the host instead of a long-lived SDK key.
Hosted workflowHosted adopter verificationCall the customer hosted workflow through a credentialed verification endpoint when that surface is part of the proof.
SQL or data mutationDatabase action or DB sandboxUse governed DB actions for runtime SQL and sandbox branches for isolated write proof.
Provider workloadProtected training laneUse Providers and Training only when the customer needs compute proof and accepts provider cost controls.
Profile review

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 areaWhat the customer confirms
HomeChoose the stack, risky action, and buyer proof need; run complete proof or share proof when the first packet is ready.
AgentConnect the real agent, classify allowed/review/blocked actions, publish policy, verify policy, prepare the SDK key, and deploy or unwrap when needed.
DeploymentsInspect live state, recent activity, observed and blocked calls, source, HTTP status, latency, authority context, redaction mode, and proof exports.
ProofRefresh proof, review Profile verification status, inspect scanner and SDK certification packets, issue MCP authority tokens, create buyer shares, and copy package commands.
ProvidersChoose a configured provider, verify credentials, set budget/runtime/auto-stop, and prepare the protected training workload.
TrainingMonitor provider training deployments, callbacks, status, stop/delete state, and evidence produced by protected compute runs.
SandboxCreate DB sandbox sessions, run signed read/write transactions, export proof, diagnose policy/RLS/security-invoker issues, and destroy branches.
AccountReview identity, account state, SDK key fingerprints, active/revoked keys, password state, and logout.
Proof packet

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.

Review

Open the current proof packet and inspect the allowed action, blocked denial, scanner evidence, chain root, and packet digest.

Redact

Use the auditor-redacted share for external buyers and keep private workspace details inside Profile.

Verify

Use the public readback or verifier flow before sending the link to a buyer or auditor.

Packet contents
Packet areaWhat the customer checks
Agent and policyActive Profile agent, published policy version, mission, allowed/review/blocked actions, and unknown-action mode.
Allowed evidenceAt least one allowed action from the wrapped runtime path with timestamp, source, latency, and proof context.
Blocked evidenceAt least one denied or halt-required action blocked before the dangerous body or committed side effect.
Scanner and adopter evidenceCI scanner upload and SDK/adopter certification rows when those lanes are part of the customer proof.
AI-card and proof healthAgent summary rows, proof-health alerts, saved trace replay evidence, detector findings, and accepted-risk state.
MCP or hosted evidenceAuthority-token and hosted verification rows only when MCP or hosted workflow products are in scope.
Data or compute evidenceDB branch/source-write proof and protected training evidence only when the customer uses those lanes.
Integrity dataSHA-256 digest metadata, chain root, packet digest, redaction context, and signature metadata when configured.
Share statusBuyer/auditor link is created only after verification and public readback succeeds.
Data + compute

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.

Database sandbox

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.

Protected provider training

Use when the customer needs provider compute proof. Customer should verify provider key, set budget/runtime/auto-stop, monitor Training, and stop/delete resources.

Hosted adopter credentials

Use when the buyer runs a hosted workflow product. Missing hosted credentials should be reported honestly instead of claimed as a pass.

MCP authority

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.

CI scanner proof

Use for repo boundary proof. CI vendors are runners only; the evidence stays Imladri-native and uploads to Profile.

Troubleshooting

Fast checks when the flow does not move.

SymptomFirst check
No activity in ProfileCheck the agent id, SDK key, Worker URL, and whether the terminal/API command used the same workspace.
Allowed proof works, blocked proof missingConfirm the risky action is listed as strict or hard-deny in the published policy before rerunning the proof.
Adapter certification failedOpen the adopter path, rerun the focused adapter command, then sync the fresh artifact to Profile.
Scanner output missingRun the scanner from the repo root and confirm the output path is attached to the current workspace proof run.
MCP tool host cannot connectConfirm 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 passedConfirm the hosted verification endpoint and token are configured for that hosted product; missing credentials should stay visible as missing, not passed.
DB sandbox proof missingConfirm the target id, allowed relation, SDK key, runtime base URL, session status, and whether the branch was destroyed before export.
Training status is stuckConfirm provider key verification, budget/runtime limits, auto-stop, provider callback activity, and whether the provider pod/container still exists.
Share link unavailableRefresh proof status first; sharing is blocked until Profile has a current verified packet.
Security basics

What runs locally, what Profile shows, and what buyers see.

Local first

Terminal/API wrapping runs from the customer repo so the risky action is controlled at the execution boundary.

Profile is the review surface

Profile stores monitored activity, proof status, redacted shares, and buyer-readable packet history.

Evidence is digest-backed

Proof packets carry ordered chain entries, a chain root, packet digest, and redaction context.

Proof should be verified

Use the browser verifier at /verify-proof or the CLI command imladri proof verify --input <proof.json> before sharing auditor evidence.

Detector signals are advisory

Prompt-injection and sensitive-data findings help reviewers decide what to fix or accept; prevention still requires routing the side effect through Imladri.

Private data should stay scoped

Use redacted public shares for buyers and keep sensitive workspace evidence inside the approved customer workspace.

Prevention requires routing

Capabilities not routed through wrapped tools, strict preflight, sandboxed actions, or governed DB actions are observable and haltable, but not pre-execution preventable.

Secrets stay server-side

SDK keys, hosted verification tokens, provider keys, and service tokens belong in secret managers or server environments, never browser-side code.

Provider resources need cleanup

Provider runs should have auto-stop enabled. Customers should stop/delete pods, remove exposed keys from local environment, and rotate any shown provider key.

Done checklist

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.

AreaAcceptance signal
AccessApproved customer can use issued credentials to see the correct private Profile workspace and active agent.
PolicyThe agent mission and action lists are published and verified with the same connected agent.
Runtime wrapperOne allowed action and one blocked-before-body action have run from the customer repo or API path.
Profile readbackHome, Deployments, and Proof show current activity, proof status, latency/source context, and the selected redaction mode.
Integration laneThe 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 packetJSON/Markdown/PDF export or public auditor share verifies, includes integrity metadata, and omits private secrets.
CleanupOld 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 handoffIf anything is stuck, customer can run doctor and export the Account support bundle without exposing plaintext secrets.
Next step

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.