CORE CONCEPTS

What you build on EKKA¶

EKKA is the governed runtime for AI agents, and the category it belongs to is governed execution: not a policy you write and hope is followed, but a runtime that refuses the action and signs the record. You describe what an agent should do, run it in your own environment, and every action it takes is authorized before it happens and proven afterward, with no governance code of your own.

EKKA has a small surface area. A couple of ideas cover what you build (agents and plans); the rest are the four words that cover how EKKA governs it: Gate, Grant, Gate Token, and Receipt.

The Quickstart is the fastest way in: set up the CLI, then run your first governed action by hand to watch a governed agent get blocked, get authorized, and get proven. This page is everything that walkthrough stands on.

The one idea to hold onto

Governance is a grant, not an if-statement. You don't write access-control code. You set a Grant, and EKKA enforces it the same way over a database, over an AI model, and over a tool.

Agents¶

An agent is the AI equivalent of a human expert. There is some process you know that other people get wrong: the steps, the order they belong in, and the judgment in the middle that only shows up after you have done it a few times. The agent is where that knowledge goes to work.

It holds plans, one for each thing that expert knows how to do. Real expertise is knowing which plans exist, in what order, and what to check along the way. That's what the agent carries.

An agent is a who. A plan is a what. You create an agent, then give it plans; a plan always belongs to one.

Plans¶

A Plan (an Execution Plan) is the recipe an agent follows: what data to read, which model to ask, what it's allowed to touch, and how the steps connect. You write the recipe; EKKA runs it and proves every step.

The plan is the policy. It lives in version control, so governance becomes a diff you review, not a separate process or a meeting. You don't write the access control, the data plumbing, or the audit trail; the plan declares intent and EKKA governs the rest.

A Plan has no ceiling on what it can express:

as small as read one table, then ask a model to summarize it (the demo), or
as large as a full multi-phase, multi-agent workflow, scope, fan out searches, fetch, verify, synthesize, the kind of orchestration you'd build with a serious agent framework.

Whatever its size, EKKA governs every step the same way, you don't write any of the guardrails yourself. Authoring is declarative and high-level: you describe the work, and the governance comes with it.

Skills¶

A Skill is a piece of work published under a name, so a plan can call it instead of spelling the steps out again. Write slack.read once and every plan names it, rather than each one carrying its own copy of the same steps.

A skill has ports: what it takes in, and what it hands back. A plan fills the ports and never has to know what is inside.

A published version is never rewritten. Publishing the same name again makes the next version, so a plan that names slack.read@1 keeps running exactly what it ran the day you wrote it.

A skill is a body of work, not an authority. Calling one changes nothing about permissions: the steps still run as the agent that owns the plan, and every gate call inside still needs a Grant.

See Skills for how to write, publish and share one.

Running a Plan¶

A Plan is worth little if it only runs when you're watching. EKKA runs plans three ways, the same model you already know from modern CI and automation:

On demand

Kick off a plan yourself, whenever you want, straight from the CLI.
On a schedule, EKKA Clock

Run a plan on a cadence, a nightly reconciliation, an hourly digest, a Monday-morning report, and let it work while you don't.
On events, connectors

Trigger a plan the moment something happens in your stack. Connectors turn real-world events into governed agent runs.

Event triggers are the third way a plan starts. Connect your systems and a plan can fire automatically when, for example:

a payment fails in your billing system, an agent investigates and drafts the recovery email;
a support ticket lands, an agent triages it, pulls the relevant context, and drafts a governed reply;
a contract or PDF is uploaded, an agent extracts the key terms and flags anything out of policy;
a new customer signs up, an agent enriches the record and kicks off onboarding;
a metric anomaly fires, an agent investigates across your own data and reports back;
a new record appears in your database or CRM, an agent picks it up and acts.

Every one of these touches real data, real models, real tools, which is exactly why each run is governed, per action, with a signed receipt. You get the automation and the proof, together.

How EKKA governs it: four words¶

The rest of EKKA is four ideas. You don't build any of them, you get them around every plan, automatically. They are the same four you use in the Quickstart, so learn these and you know EKKA.

Gate¶

A Gate is a governed boundary over something your agent might touch: a database, an AI model, a tool. An agent reaches a resource only through its gate, never around it. The demo uses a hosted database gate (type postgres) and an AI-model gate (type llm); a tool gate (type mcp) fronts tools over MCP. Every gate speaks the same grammar: deny, grant, allow, receipt.

Grant¶

A Grant is durable policy you set once: which agent may do what, on which gate and resource. Nothing is allowed by default, no Grant, no action. A Grant for one resource opens exactly that resource and nothing else: a Grant to read customers never opens invoices, and a Grant for one tool never opens the rest. That's least privilege, declared as intent rather than written as a check. This is the whole product in one sentence: governance is a grant, not an if-statement.

A Grant stays in force until you change it. Revoke it and the very same operation is refused again, live, with no code change. Re-grant it and it flows again.

Gate Token¶

A Gate Token is a short-lived, signed permit issued per operation from a Grant. When an operation is covered by a Grant, EKKA issues a fresh token scoped to exactly that one call, the gate verifies it, and the token expires almost immediately. So the standing permission (the Grant) and the thing sent over the wire (the Gate Token) are two different objects: revoke the Grant and no new tokens can be issued, while any token already issued was only ever good for one scoped call. The gate returns only what was in scope; anything outside the token's scope is never handed back.

Receipt¶

Every access, allowed and denied, is a Receipt: a signed, verifiable record of exactly what happened, what was read, which model or tool ran, under which token. A run's receipts are chained together so that changing, removing, or reordering any one of them visibly breaks the chain (that's what tamper-evident means). Anyone can re-check the whole thing against EKKA's public keys, offline. See Governance receipts.

A denied action is stopped before anything is read or sent anywhere, and that "no" is recorded too, so a block is just as provable as an allow.

The Enclave¶

The Enclave is the boundary on your machine where the agent's work actually happens. It runs on your side, your laptop, your servers, your cloud. Your passwords, keys and data stay there. What travels back to EKKA is a short signed summary of what happened. For sensitive or regulated work that's the part that matters: the work runs on your machines and your data stays inside your walls. You start it with ekka enclave start and leave it running.

How it fits together¶

flowchart LR
  Grant[Grant<br/>durable policy] --> EKKA
  EKKA -- mints per operation --> GT[Gate Token<br/>short-lived, signed]
  GT --> Enclave
  Enclave -- presents token --> Gate[Gate<br/>database / AI model / tool]
  Gate -- returns only what's in scope --> Enclave
  Gate -- signed receipt --> Chain[Receipt chain<br/>allowed and denied]

You set the Grant; EKKA issues the token; the Enclave does the work on your side, reaching each resource only through its gate; the gate returns only what was in scope and signs a receipt. What you get, with no governance code of your own: every action checked before it runs, anything unpermitted stopped before it touches your systems, a signed receipt for each step, and an audit trail no one can quietly rewrite.

The bigger picture¶

Put it together and EKKA is a full agent runtime: you build your own agents, run community and private ones, author plans of any size, and trigger them on demand, on a schedule, or on events, all on your own infrastructure, all governed the same way. As developers build and share agents, this compounds into a marketplace of governed agents, where every action carries a signature anyone can check.