Example engines

The repository examples apply the same Invokta contracts to different domain outcomes. Each engine keeps direct, CLI, and MCP execution on engine.invoke, while its own package owns ports, policies, limits, and outbound connectors.

Choose by problem

You need to	Start with
Learn the smallest complete path	`hello-engine`
Inject dependencies and enforce domain authorization	`support-engine`
Consume an engine from a private MCP harness	`support-harness`
Build network-backed connectors behind domain ports	`crawl-engine`, `image-engine`, or `observability-engine`
Build filesystem-backed connectors behind domain ports	`obsidian-context-engine` or `agent-session-engine`
Build development workflow actions	`spec-engine`, `review-engine`, or `agent-session-engine`
Publish deterministic agent-routing policy	`cursor-agent-routing-engine`
Navigate local project knowledge progressively	`obsidian-context-engine`
Publish and compose reusable capabilities	`community-capabilities` and `composed-engine`
Authenticate engine callers with your identity provider	`auth-jwt-bearer-engine`, then the `auth-*` example for your provider

Choose by operational requirement

Examples	What you need locally
`hello-engine`, `support-engine`, `support-harness`, `cursor-agent-routing-engine`, `spec-engine`, `review-engine`, `community-capabilities`, `composed-engine`	No external provider credential for direct, CLI, stdio, or tests
`agent-session-engine`	A writable data directory; the session ID and directory have local defaults
`obsidian-context-engine`	`OBSIDIAN_VAULT_PATH` pointing to the directory the read-only connector may inspect
`crawl-engine`	`FIRECRAWL_API_KEY`
`image-engine`	`OPENAI_API_KEY`, `ARK_API_KEY`, and `GEMINI_API_KEY`
`observability-engine`	Sentry, Datadog, and New Relic credentials plus their organization or account identifiers
`auth-*` examples	Nothing for the tests, which verify locally generated credentials offline; each README lists the issuer, audience, or key variables its HTTP entry point needs against a real provider project

The HTTP entry points use example-specific bearer-token environment variables in addition to the requirements above. Every linked README gives the exact variable names and commands. Provider-backed direct examples perform real outbound calls, so review provider data handling and billing before running them.

Patterns demonstrated

Independent consumers: support-harness uses only MCP stdio and does not import the engine runtime.
Replaceable providers: the crawl, image, and observability engines keep vendor-specific connectors behind domain-owned ports.
Bounded filesystem connectors: the Obsidian and agent-session engines keep local filesystem access behind domain-owned ports with explicit limits.
Domain-owned workflows: the spec and review engines keep ordering, revisions, and gates outside the framework runtime.
Durable local state: the agent-session engine owns persistence, concurrency, checkpoints, and harness hooks.
Bounded context: the Obsidian engine exposes declared roots and one node at a time instead of loading an entire vault.
Reusable packages: community capabilities publish atomic and library entry points; the composed engine selects and remaps them.

Learn the framework boundary

Hello Engine

Define onboarding.create-welcome-message once and expose it through direct invocation, CLI, MCP stdio, and stateless MCP HTTP with a deterministic injected writer.

Open hello-engine

Support Engine

Classify support tickets with injected repository, classifier, and permission ports. The example covers authorization, safe errors, cancellation, and all four entry points.

Open support-engine

Support Harness

Start the Support Engine over MCP stdio from a private consumer, discover its tool, invoke it once, and record harness-owned history without importing the engine runtime.

Open support-harness

Crawl Engine

Publish bounded page scraping, site mapping, and crawling while Firecrawl stays behind a WebCrawler port and public-target validation runs before provider I/O.

Open crawl-engine

Build development actions

Spec Engine

Publish specification, planning, task breakdown, implementation evidence, and status as separate capabilities. Ordering and revisions remain domain rules instead of framework orchestration.

Open spec-engine

Review Engine

Assess task readiness with code review, acceptance evidence, and adversarial checks. The fail-closed result allows completion only when every gate passes.

Open review-engine

Agent Session Engine

Persist tasks, phases, checkpoints, evidence, and handoffs independently of Cursor, Antigravity, Claude Code, or Codex with explicit concurrency and storage limits.

Open agent-session-engine

Cursor Agent Routing Engine

Publish versioned, deterministic policy that selects a Cursor custom subagent and model for seven development use cases without adding routing to the Invokta core.

Open cursor-agent-routing-engine

Obsidian Context Engine

Expose an Obsidian vault as a bounded knowledge graph. Agents list declared roots, open one node at a time, and follow stable links without loading the entire vault.

Open obsidian-context-engine

Authenticate engine callers

Ten examples share one minimal identity.whoami capability and differ only in how the composition root verifies a credential and maps it to Principal. Start with the provider-neutral JWT bearer engine; every provider example follows its shape. Each pairs with a page in the authentication recipes.

Example	Shows
`auth-jwt-bearer-engine`	Provider-neutral JWKS verification with `jose`, claims-to-`Principal` mapping, and Protected Resource Metadata for MCP OAuth discovery
`auth-self-hosted-oauth-engine`	Production-oriented self-hosted OAuth with PKCE, DCR, ES256 tokens, rotating refresh tokens, PostgreSQL, and Caddy or Traefik deployment assets
`auth-supabase-engine`	Supabase Auth asymmetric JWTs verified against the project JWKS
`auth-clerk-engine`	Clerk session tokens with authorized-party enforcement and organization claims
`auth-auth0-engine`	Auth0 API access tokens with a required audience, scopes, and permissions
`auth-cognito-engine`	Cognito user-pool access tokens with `client_id`, `token_use`, and group mapping
`auth-firebase-engine`	Firebase ID-token verification behind an injectable verifier port
`auth-better-auth-engine`	Better Auth JWT-plugin tokens plus the embedded same-process surface
`auth-authjs-engine`	Auth.js sessions passed to `engine.invoke`, with app-issued tokens for HTTP callers
`auth-workos-engine`	WorkOS AuthKit access tokens with organization claims for multi-tenant rules
`auth-api-key-engine`	Hashed machine-to-machine API keys compared in constant time

Integrate external systems

Image Engine

Publish outcome-oriented editing, text rendering, campaign series, and reference composition while GPT Image 2, Seedream 5.0, and Nano Banana 2 remain behind replaceable ports.

Open image-engine

Observability Engine

Collect bounded incident context from Sentry, Datadog, and New Relic through one provider-independent capability and normalized domain result.

Open observability-engine

Publish and compose capabilities

Community Capabilities

Demonstrate atomic root exports, subpath exports, and a capability library with factory-injected dependencies and literal default IDs.

Open community-capabilities

Composed Engine

Combine a local capability, atomic imports, selected library capabilities, and deliberate ID remapping in one eagerly checked engine map.

Open composed-engine

Run an example locally

Clone and build the repository first:

git clone https://github.com/vinilana/invokta.git
cd invokta
yarn install --frozen-lockfile
yarn build

Each linked README lists its configuration, direct and CLI commands, MCP entry points, and focused test command. For smaller code extracts with an explanation of each decision, use the practical recipes.

Develop against an example

Every example that exports a constructed engine carries the same scripts a project generated by create-invokta-engine gets, so what you learn here transfers unchanged to your own engine:

Script	What it does
`devtools`	Rebuilds on change and serves the engine on a loopback URL. The Playground emulates one call through the direct, CLI, MCP stdio, or MCP HTTP path under a development `Principal` you select, and records what that adapter exchanged.
`devtools:doctor`	Runs the read-only engine checks and reports whether an `invokta.mcp.json` manifest sits next to the project.
`check:mcp`	The build-time MCP conformance gate: it fails when two capability IDs derive the same portable MCP tool name, before an adapter starts or the engine is installed.

The externally backed engines — crawl, image, observability, and Obsidian — need deployment configuration to compose, so they publish no constructed engine for serve or check-mcp to import. They gate their portable tool names in their own tests and ship devtools:verify, which runs initialization and the complete tools/list against the built stdio adapter without calling a tool. support-harness verifies the engine it consumes the same way.

The MCP stdio and CLI emulations can also run the project’s own built entry point instead of the DevTools child, so the composition root that decides the principal is the example’s rather than the inspector’s.

Both workbenches are workspace-independent, so an installed engine can be inspected without a checkout at all:

npx @invokta/devtools open

open lands on a chooser: /mcp attaches to one stdio command or Streamable HTTP endpoint, and /cli drives an installed Invokta CLI through list, describe, and one deliberate run.