ikura/Documentation

ikura Documentation

The guide for AI and humans building safe, reproducible automation.

ikura is an automation platform where AI writes TypeScript workflows at design time and validated IR runs deterministically at run time. Humans handle explanation, approval, and audit, while AI agents use structured contracts and diagnostics to help author and repair workflows.

Start in 5 minutes Create an account

Start in 5 minutes

The fastest path from a cloned repository to a validated sample workflow.

1
Prepare dependencies and packages
Install the monorepo dependencies and build the CLI and runtime packages.
2
Validate a workflow
Build the invoice-dispatch example and check its structure, contracts, taint, and golden tests.
```
pnpm install
pnpm build

cd examples/invoice-dispatch
pnpm ikura validate
pnpm ikura test
```
3
Inspect human-readable projections
Generate a narrative, a flow graph, and per-scenario timelines from the same IR.
```
pnpm ikura explain
pnpm ikura graph --mermaid
pnpm ikura timeline --scenario scenarios/happy.json
```

Three core concepts

Every ikura automation can be traced through these three units.

Module

A reusable unit of work that defines an API's actions, triggers, schemas, side effects, and trusted inputs. At run time it is pinned by version and SHA-256 digest.

Workflow

Triggers, actions, AI transforms, approvals, and retries declared in TypeScript and compiled into deterministic IR. The IR is the source of truth.

Run

One execution of a workflow. It carries status, trace, approvals, idempotency, and an audit trail; durable execution resumes without repeating completed actions.

User guide

Day-to-day operations

Review each Module's publisher, trust tier, scopes, and side effects in Marketplace.
Connect OAuth or API keys in Connections. Credential values are never returned to the UI or traces.
Review descriptions, nodes, and parameters in Workflows, then execute.
Track progress and pending approvals in Runs; when something fails, trace the cause from Incidents.

Roles

owner / admin: Manage connections, Modules, invitations, billing, and approvals
member: Run, approve, and browse workflows
viewer: Read run results and configuration

The AI agent working loop

Agents read contracts first, pass validation and simulation, and explain the diff to a human before proposing state changes.

01
Discover
Check trust, scopes, quirks, and side effects from the catalog and Module metadata.
02
Author
Write workflow TypeScript with generated types and make module lock changes explicit.
03
Validate
Fix until diagnostics reach zero, then simulate with fixtures and golden tests.
04
Explain
Present the narrative, graph, scope, side-effect, and lock diffs to a human.
05
Operate
Deploy through policy gates, and send patch proposals from runs and incidents to review.

CLI quick reference

Purpose	Command	Output
Validate	`ikura validate --json`	Diagnostics with stable codes
Test	`ikura test`	Golden test results
Explain	`ikura explain`	Narrative derived from IR
Visualize	`ikura graph --mermaid`	Mermaid flowchart
Run without side effects	`ikura run --dry-run`	RunResult using fixtures
History	`ikura runs list`	List of stored runs
Pre-publish validation	`ikura module validate`	Module package diagnostics

MCP — the control plane for agents

The MCP server runs as JSON-RPC 2.0 over stdio and works with canonical IR, contracts, runs, and incidents. It never exposes user TypeScript or credentials.

pnpm build
pnpm --filter @ikura/mcp exec ikura-mcp

catalog.search / catalog.describe

Inspect contracts, schemas, trusted inputs, and quirks

workflow.validate

Validate canonical Workflow IR and return structured diagnostics

workflow.simulate

Execute without side effects using fixtures; returns trace and timeline

workflow.explain / workflow.graph

Generate a narrative and a Mermaid graph from IR

workflow.deploy

Evaluate policy, then deploy or route to the approval queue

runs.list / runs.get

Read stored runs and PII-tokenized traces

incidents.get / workflow.propose_patch

Investigate failures and submit validated patch proposals for review

Modules installed from Marketplace can also be added to the tool list of MCP clients authenticated with a tenant API token.

Security and invariants

Never run user code at run time.TypeScript executes only to emit IR at build time.
Confine side effects to action boundaries.Only the RuntimeHost / activity layer makes real API calls.
Never show credentials to agents.Secrets are encrypted and never returned to the UI, traces, or MCP responses.
Never flow LLM output into trusted inputs.Validation halts when tainted values reach recipients or monetary amounts.
Never repeat side effects on re-execution.The idempotency ledger and durable journal reuse completed actions.
Pin the executed Modules.Avoid implicit updates after a run starts, keeping versions and digests auditable.

Public API reference

The primary HTTP surfaces used by external integrations. Check authentication requirements and side effects per route.

GET/api/health

Check service health

GET/api/registry/modules

Search public Modules

GET/api/registry/modules/:name/:version

Fetch a version-pinned artifact

GET/api/agent/whoami

Check the token's tenant and role

GET/api/mcp/tools

Fetch installed MCP tool metadata

POST/api/mcp/tools/call

Invoke a declarative Module tool

For run, trigger, OAuth, and publisher APIs, see the authenticated control plane and each route's schema.

Glossary

Behavioral Contract: A versioned contract that defines a connector's actions, triggers, schemas, side effects, trusted inputs, and display metadata.
IR: The deterministic intermediate representation generated from workflow TypeScript. The source of truth for execution and projections.
Projection: Narratives, graphs, parameter views, and timelines generated from IR and run history. Read-only.
Taint: A provenance marker that tracks the origin of values such as LLM output and blocks unsafe flow into trusted fields.
Durable run: A run whose journal and signals are stored so it can resume after a crash without repeating completed actions.