Hono
A Hono app embeds the aidy runtime in the same process, on Node or Cloudflare Workers. Routes declared with @hono/zod-openapi carry x-aidy next to their schemas, the app serves its own OpenAPI 3.1 document, and aidy calls the app in process through app.fetch.
npm install hono @hono/zod-openapi @aidy-dev/core @aidy-dev/spec @aidy-dev/sqlAnnotate routes
Section titled “Annotate routes”createRoute accepts OpenAPI extension keys, so x-aidy goes on the route object and @hono/zod-openapi copies it into the generated operation.
import { createRoute, OpenAPIHono, z } from '@hono/zod-openapi';
const app = new OpenAPIHono();
const stopVm = createRoute({ method: 'post', path: '/api/vm/{vm_id}/stop', summary: 'Stop server', request: { params: z.object({ vm_id: z.string() }), body: { content: { 'application/json': { schema: z.object({ forced: z.boolean().default(false) }) } } }, }, responses: { 200: { description: 'Stopped', content: { 'application/json': { schema: Vm } } } }, 'x-aidy': { name: 'stop_vm', description: 'Stop a running cloud server (VM).', open: '/console/instance/{vm_id}', confirmation: { title: 'Stop server {resource_name}?', lookup: { path: '/api/vm/{vm_id}', labelPath: 'name' }, }, },});
app.openapi(stopVm, async (c) => { const { vm_id } = c.req.valid('param'); return c.json(await vms.stop(vm_id, c.req.valid('json')), 200);});Path and query parameters and the JSON body fields become one flat input schema; a name that appears in two places is a catalog error. See Operations.
Serve the OpenAPI document
Section titled “Serve the OpenAPI document”aidy fetches the document with the user’s credential, so the host may answer each user with only the operations they can use. Serve it as OpenAPI 3.1:
app.doc31('/openapi.json', { openapi: '3.1.0', info: { title: 'Cloud Console', version: '1.0.0', description: 'Cloud servers on demand.' },});info.title and info.description name the product in /skill.md and /llms.txt. Check the catalog with aidy check --openapi http://localhost:8787/openapi.json.
Identity
Section titled “Identity”One GET operation with role: identity answers who the credential belongs to:
const whoami = createRoute({ method: 'get', path: '/api/me', responses: { 200: { description: 'Caller', content: { 'application/json': { schema: Identity } } } }, 'x-aidy': { name: 'whoami', role: 'identity' },});
app.openapi(whoami, (c) => { const user = c.get('user'); return c.json({ subject: user.id, tenant: user.tenantId, name: user.name, scopes: user.scopes }, 200);});Search sources follow the same pattern with role: 'search' and a required q query parameter; see Search.
Mount aidy
Section titled “Mount aidy”createAidy(config) from @aidy-dev/core returns { fetch(request, ctx?), migrate(), close() }. fetch is a Web-standard handler for every aidy route. Pass the app’s own fetch as host.fetch so aidy’s calls stay in process.
import { createAidy, SqlStore } from '@aidy-dev/core';import { importSigningKey } from '@aidy-dev/spec/delegation';import { sqliteDriver } from '@aidy-dev/sql/sqlite';
// The private JWK from `aidy keys generate`, imported extractable so aidy can publish the// public key at /.well-known/aidy-keys.json.const signingKey = await importSigningKey(JSON.parse(process.env.AIDY_SIGNING_KEY!));
const aidy = createAidy({ url: 'https://console.example.com', host: { origin: 'https://console.example.com', openapi: '/openapi.json', fetch: (request) => app.fetch(request), }, signingKey, secret: process.env.AIDY_SECRET!, store: new SqlStore(sqliteDriver('aidy.sqlite')), models: { chain: [ { id: 'qwen', provider: 'openai-compatible', model: 'qwen3-max', baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1', apiKey: process.env.DASHSCOPE_API_KEY, }, ], },});
for (const path of ['/aidy/v0/*', '/mcp', '/skill.md', '/llms.txt', '/.well-known/aidy-keys.json']) { app.all(path, (c) => aidy.fetch(c.req.raw));}On Workers, pass the execution context as the second argument (aidy.fetch(c.req.raw, c.executionCtx)) so runs outlive the response, and use d1Driver from @aidy-dev/sql/d1. Under a prefix, set basePath (for example /assistant) and url to match; aidy then serves every route below that prefix, so one app.all('/assistant/*', …) mounts it. aidy ships no Hono adapter package: these lines and the middleware below are the whole integration.
On Workers, waitUntil ends with the request’s lifetime limits, so a run can be cut short when its response closes early. For production, route each user (or each thread) to a Durable Object that owns the aidy instance; see Deploy: several instances. For Workers AI models, see Models.
Verify assertions
Section titled “Verify assertions”Every call from aidy carries Aidy-Assertion. Add one middleware, before your routes, that verifies it with @aidy-dev/spec/delegation: verifyAssertion covers signature, lifetime, audience, method, URL, body hash and replay; checkCall covers the user, the operation and the approval.
import { createMiddleware } from 'hono/factory';import { ASSERTION_HEADER, AssertionError, checkCall, importPublicKeys, verifyAssertion,} from '@aidy-dev/spec/delegation';
const keys = await importPublicKeys([JSON.parse(process.env.AIDY_PUBLIC_JWK!)]);const seen = new Map<string, number>(); // jti -> expiry; prune it, or use Redis/KV with several instances
type Op = { method: string; pattern: RegExp; op: string; approval: 'never' | 'always' };let operations: Op[] | undefined;function catalogOps(): Op[] { const doc = app.getOpenAPI31Document({ openapi: '3.1.0', info: { title: 'Cloud Console', version: '1.0.0' } }); return Object.entries(doc.paths ?? {}).flatMap(([path, item]) => Object.entries(item ?? {}).flatMap(([method, operation]) => { const ext = (operation as { 'x-aidy'?: { name: string; effect?: string; approval?: 'never' | 'always' } })['x-aidy']; if (!ext) return []; const read = (ext.effect ?? (method === 'get' || method === 'head' ? 'read' : 'write')) === 'read'; return [{ method: method.toUpperCase(), pattern: new RegExp(`^${path.replace(/\{[^}]+\}/g, '[^/]+')}$`), op: ext.name, approval: ext.approval ?? (read ? 'never' : 'always'), }]; }), );}
app.use('/api/*', createMiddleware(async (c, next) => { const token = c.req.header(ASSERTION_HEADER); if (!token) return next(); // an ordinary user request try { const claims = await verifyAssertion(token, { keys, audience: 'https://console.example.com', request: { method: c.req.method, url: c.req.url, body: new Uint8Array(await c.req.raw.clone().arrayBuffer()) }, remember: (jti, until) => { if (seen.has(jti)) return false; seen.set(jti, until); return true; }, }); operations ??= catalogOps(); const served = operations.find((o) => o.method === c.req.method && o.pattern.test(c.req.path)); const user = c.get('user'); // resolved from Authorization by your auth middleware checkCall(claims, { subject: user.id, tenant: user.tenantId, op: served?.op ?? '', approval: served?.approval ?? 'always' }); c.set('aidy', claims); // rid, cid, apr for your audit log } catch (error) { if (!(error instanceof AssertionError)) throw error; return c.json({ error: 'aidy_assertion_invalid', code: error.code }, 401); } return next();}));c.req.url must equal the assertion’s htu: host.origin followed by the path and query aidy called. With host.fetch and no host.baseUrl, it is. Behind a proxy that rewrites the host or strips a prefix, rebuild it from the public origin. The rules are in Delegation.