Runtime and APIs

--- title: Runtime and APIs description: Runtime wiring and well known endpoints. ---

Runtime and APIs

This section documents the runtime integration points and the public APIs generated by Ekairos.

withRuntime (Next.js)

@ekairos/domain/next provides withRuntime() that:

• Injects the bootstrap module into server bundles.
• Generates a domain endpoint under .well-known/ekairos/v1/domain.
• Ensures the workflow step route imports the bootstrap module.

Usage:

import { withRuntime } from "@ekairos/domain/next";

export default withRuntime(nextConfig, {
  bootstrapModule: "./src/runtime.ts",
});

Domain endpoint

Generated at:

• /.well-known/ekairos/v1/domain

GET

Returns:

• mode: "full"
• domain: summary or full context
• schema: InstantDB schema
• contextString: prompt friendly text

POST

Executes an InstaQL query using the org admin DB.

Payload:

{
  "orgId": "org_123",
  "query": { "projects": { "$": { "limit": 5 } } }
}

Response:

{
  "ok": true,
  "data": { "projects": [] },
  "truncated": null
}

Truncation

The response truncates each array field to 50 items. If truncation happens, a truncated map is returned with totals.

Auth

Auth is required when any of the env vars are set:

• EKAIROS_DOMAIN_TOKEN
• EKAIROS_DOMAIN_JWKS_URL
• EKAIROS_DOMAIN_ISSUER
• EKAIROS_DOMAIN_AUDIENCE

Auth options:

• Static bearer token (EKAIROS_DOMAIN_TOKEN).
• OIDC verification using JWKS. Defaults to Vercel OIDC endpoints.

Workflow endpoint

The Workflow DevKit endpoint is generated under:

• /.well-known/workflow/v1/step

Ekairos ensures the bootstrap module is imported for this route so runtime config is available when steps execute.

Runtime config surface

From @ekairos/domain/runtime:

• configureRuntime()
• getRuntimeConfig() / getRuntimeProjectId()
• resolveRuntime() / runtime()

From @ekairos/thread/runtime:

• resolveThreadRuntime()
• registerThreadEnv() / getThreadEnv()

These APIs are used by the bootstrap module to configure runtime behavior.