### Install @onkeiki/agents and Postgres storage with bun

Source: https://onkeiki.com/docs/sdk

Install the SDK and the Postgres storage adapter using bun. Required before using the SDK.

```bash
bun add @onkeiki/agents @onkeiki/agents-storage-postgres
```

--------------------------------

### Install @onkeiki/agents-plugins with bun

Source: https://onkeiki.com/docs/cloud-agents

Adds the plugins package to your project. Run this command to install the package before using any plugins.

```bash
bun add @onkeiki/agents-plugins
```

--------------------------------

### Install @onkeiki/ai-sdk with bun

Source: https://onkeiki.com/docs/ai-sdk

Install the required packages for the AI SDK integration. Use this command in your project to add @onkeiki/ai-sdk, ai, and @ai-sdk/mcp.

```sh
bun add @onkeiki/ai-sdk ai @ai-sdk/mcp
```

--------------------------------

### Install @onkeiki/eve

Source: https://onkeiki.com/docs/eve

Install the @onkeiki/eve package. Requires Node.js 24 or later. Alternatively, run npx @onkeiki/cli init to set up the integration automatically.

```sh
npm install @onkeiki/eve
```

--------------------------------

### Install Hermes harness with curl

Source: https://onkeiki.com/docs/harnesses

Runs the Keiki harness installer on a host machine. Requires a Keiki API key and installs Hermes, enables its OpenAI-compatible API server, registers Keiki's MCP server and observability plugin, stores the local Hermes key as an encrypted secret, and points the agent at the host. Safe to run again. Options are passed via CONNECTIVITY; set HERMES_BIN if the binary is not on PATH, and HERMES_INSIDE_GATEWAY=1 when running inside the gateway to skip the restart.

```sh
curl -fsSL https://<your-keiki-host>/api/v1/harness/install.sh \
  | KEIKI_API_KEY=sk_live_… bash
```

--------------------------------

### createServer

Source: https://onkeiki.com/docs/sdk

Starts the turn-handling HTTP server. This is what kit.serve() wraps.

```APIDOC
## createServer

### Description
Starts the turn-handling HTTP server. This is what `kit.serve()` wraps.

### Method
Function

### Signature
`createServer`

### Returns
HTTP server instance
```

--------------------------------

### GET /ping

Source: https://onkeiki.com/docs/external-channel-evals

Setup check for the external channel eval driver.

```APIDOC
## GET /ping?driver=imessage

### Description
A setup check that returns the agent, driver, channel, and target for the given driver. It never claims a run.

### Method
GET

### Endpoint
/api/v1/evals/channel/ping

### Parameters
#### Query Parameters
- **driver** (string) - Required - The driver to check, e.g., `imessage`.

### Response
#### Success Response (200)
- **agent_id** (string) - The agent identifier.
- **driver** (string) - The driver name.
- **channel** (string) - The channel name.
- **target** (string) - The target handle.

#### Response Example
{
  "agent_id": "agent_...",
  "driver": "imessage",
  "channel": "sms",
  "target": "+15550001111"
}
```

--------------------------------

### Install @onkeiki/flue and @flue/runtime

Source: https://onkeiki.com/docs/flue

Install the required packages for integrating Flue with Keiki. Use a current Node release for local development; Cloudflare targets need nodejs_compat because the channel signing helper uses the Node-compatible crypto API.

```sh
npm install @onkeiki/flue @flue/runtime
```

--------------------------------

### Start tunnel supervisor with curl and sh

Source: https://onkeiki.com/docs/external-harness

Run this command after starting your HTTP server. It downloads and executes the tunnel script, setting KEIKI_API_KEY and PORT. TUNNEL defaults to cloudflared, HARNESS to external, KEIKI_HOME to ~/.keiki. The script verifies the key and harness, warns if nothing is listening on PORT, and starts a detached supervisor that manages only the tunnel.

```sh
curl -fsSL https://<your-keiki-host>/api/v1/harness/tunnel.sh \
  | KEIKI_API_KEY=sk_live_… PORT=8789 sh
```

--------------------------------

### Install Hermes with public URL connectivity

Source: https://onkeiki.com/docs/harnesses

Installs the Hermes harness using a public URL for connectivity. Requires a Keiki API key, the Keiki host URL, and the HERMES_PUBLIC_URL environment variable.

```sh
curl -fsSL https://<your-keiki-host>/api/v1/harness/install.sh \
  | KEIKI_API_KEY=sk_live_… CONNECTIVITY=public-url \
    HERMES_PUBLIC_URL=https://hermes.example.com bash
```

--------------------------------

### Install Hermes with relay connectivity

Source: https://onkeiki.com/docs/harnesses

Installs the Hermes harness using the default relay mode. Requires a Keiki API key and the Keiki host URL.

```sh
curl -fsSL https://<your-keiki-host>/api/v1/harness/install.sh \
  | KEIKI_API_KEY=sk_live_… CONNECTIVITY=relay bash
```

--------------------------------

### Install @onkeiki/agents with bun

Source: https://onkeiki.com/docs/cloud-agents

Adds the @onkeiki/agents package to your project.

```bash
bun add @onkeiki/agents
```

--------------------------------

### AgentKitInstance.serve({ port?, host? })

Source: https://onkeiki.com/docs/sdk

Starts the HTTP server that receives turn requests from the platform and runs the loop on your machine. It syncs first.

```APIDOC
## AgentKitInstance.serve({ port?, host? })

### Description
Starts the HTTP server that receives turn requests from the platform and runs the loop on your machine. It syncs first.

### Method
function

### Parameters
- **port** (number) - Optional - The port to listen on.
- **host** (string) - Optional - The host to bind to.

### Returns
- **Promise** - Resolves when the server starts.
```

--------------------------------

### POST /runs

Source: https://onkeiki.com/docs/external-channel-evals

Starts an external channel eval run.

```APIDOC
## POST /runs

### Description
Starts an external channel eval run. Returns run details, target, eligible cases, and excluded cases.

### Method
POST

### Endpoint
/api/v1/evals/channel/runs

### Parameters
#### Request Body
- **driver** (string) - Required - The driver name: `imessage`, `sms`, `slack`, `telegram`, `whatsapp`, `email`, or `x`.
- **case_ids** (array of strings) - Optional - Specific case IDs to run.

### Request Example
{
  "driver": "imessage",
  "case_ids": ["case_1", "case_2"]
}

### Response
#### Success Response (200)
- **run_id** (string) - The run identifier.
- **driver** (string) - The driver name.
- **target** (object) - The target channel and handle.
- **cases** (array) - List of eligible cases with id, name, prompt, and history.
- **excluded** (array) - List of excluded cases with id, name, and reason.
- **quiet_ms** (number) - Quiet period in milliseconds.
- **timeout_ms** (number) - Timeout in milliseconds.

#### Response Example
{
  "run_id": "evalrun_...",
  "driver": "imessage",
  "target": { "channel": "sms", "handle": "+15550001111" },
  "cases": [
    {
      "id": "...",
      "name": "SMS: answers in one message",
      "prompt": "...",
      "history": [{ "role": "user", "content": "..." }]
    }
  ],
  "excluded": [{ "id": "...", "name": "Retries a failing tool", "reason": "mocked tools" }],
  "quiet_ms": 8000,
  "timeout_ms": 180000
}

### Error Handling
- **409** - A channel run for the agent is already in flight, or the agent has no active line on the channel.
- **400** - No case is eligible.
```

--------------------------------

### Configure MCP plugin with sandbox

Source: https://onkeiki.com/docs/cloud-agents

Shows how to configure the mcp() plugin, which requires sandbox() and throws at boot without it. The example sets maxServers, userCanAdd, and a list of servers.

```ts
import { sandbox, mcp } from '@onkeiki/agents-plugins'

const kit = AgentKit.create({
  // ...
  plugins: [
    sandbox({ persistent: true }),
    mcp({
      maxServers: 5,
      userCanAdd: true,
      servers: [{ url: 'https://my-internal-mcp.example.com/mcp' }],
    }),
  ],
})
```

--------------------------------

### Capability manifest example (JSONC)

Source: https://onkeiki.com/docs/capabilities

A complete example of a capability manifest in JSONC format. It shows the required fields like slug, version, title, description, runtime, uses, secrets, tools, http, prompt, loops, entities, and templates. The runtime is 'render-template' and the manifest includes a tool named 'render_cards'.

```jsonc
{
  "slug": "cards",              // unique per publisher, [a-z0-9-]
  "version": "1.0.0",           // semver; installs pin an exact version
  "title": "Cards",
  "description": "Render swipeable image card carousels and deliver them as one media message.",

  // How the capability's tools run. One of:
  //   render-template  slides rendered to images by the rendering service
  //   openapi          an OpenAPI source plus OAuth (the user-connections path)
  //   codemode         a small program the agent writes over granted namespaces
  //   mcp              an MCP server source
  //   builtin          a Keiki builtin (official capabilities only)
  "runtime": "render-template",

  // The host namespaces this capability may reach. A namespace you do not
  // list here is not available to it.
  "uses": ["loops", "entities"],

  // Secrets the installer provides. They are resolved per call and never handed
  // to code the model wrote.
  "secrets": [
    { "name": "RENDER_SERVICE_URL", "required": false, "description": "Override the shared rendering service." }
  ],

  // The tools this capability adds to an agent.
  "tools": [
    {
      "name": "render_cards",
      "description": "...",
      "inputSchema": { "type": "object", "properties": { /* ... */ } },
      "run": { "kind": "render-template", "template": "story" }
    }
  ],

  // The hosts the `http` namespace may reach (required with uses: ["http"]).
  // A leading "*." matches subdomains. HTTPS only.
  "http": { "allow": ["api.example.com"] },

  // Guidance added to the agent's system prompt while the capability is installed.
  "prompt": "Use render_cards only for genuinely multi-beat stories...",

  // Loop presets registered while installed (requires uses: ["loops"]).
  "loops": [
    { "name": "daily-digest", "scheduleType": "cron", "scheduleExpression": "0 8 * * *", "quiet": true, "prompt": "..." }
  ],

  // The entities this capability stores data in (requires uses: ["entities"]).
  "entities": ["digest_state"],

  // Card templates uploaded to the rendering service for your account
  // (render-template runtime only).
  "templates": [
    { "name": "story", "source": "...tsx source...", "inputSchema": { "fields": [ /* ... */ ] } }
  ]
}
```

--------------------------------

### CapabilityRef

Source: https://onkeiki.com/docs/sdk

Type for installing a published capability by exact publisher, slug, and version.

```APIDOC
## CapabilityRef

### Description
Install a published capability by exact `publisher`/`slug`/`version`.

### Type
`CapabilityRef`
```

--------------------------------

### CapabilityLoop, CapabilityLoopProbe, CapabilityLoopTrigger

Source: https://onkeiki.com/docs/sdk

Types for loop presets registered while installed.

```APIDOC
## CapabilityLoop, CapabilityLoopProbe, CapabilityLoopTrigger

### Description
Loop presets registered while installed.
```

--------------------------------

### Hono server with createKeikiHandler and streamText

Source: https://onkeiki.com/docs/ai-sdk

Sets up a Hono app that handles Keiki turns. The handler starts the turn in the background without waitUntil, so a persistent Node server process is required. It uses streamText with the OpenAI model and passes the Keiki tools and prepareStep.

```TypeScript
import { Hono } from 'hono'
import { createKeikiHandler } from '@onkeiki/ai-sdk'
import { streamText } from 'ai'
import { openai } from '@ai-sdk/openai'

const app = new Hono()
const keikiTurn = createKeikiHandler({
  onTurn: async ({ instructions, messages, tools, prepareStep, abortSignal }) =>
    streamText({
      model: openai('gpt-4.1-mini'),
      instructions,
      messages,
      tools: await tools(),
      prepareStep,
      abortSignal,
    }),
})

app.post('/keiki/turn', (context) => keikiTurn(context.req.raw))
export default app
```

--------------------------------

### Agent prompt for building a Keiki capability

Source: https://onkeiki.com/docs/publishing

A system prompt that instructs a coding agent to build a Keiki capability. It outlines the steps: read the format docs, get API access, write a manifest, publish privately, and verify. Includes rules for slug, version, uses, http.allow, secrets, and prompt.

```text
You are building a Keiki capability: a versioned JSON manifest that gives any Keiki agent
new tools, prompt guidance, schedules and stored state. Goal: publish it privately to my
Keiki organization and install it on my agent, so I can try it before submitting it to the
marketplace. Derive every value from my spec and this repository. Never invent endpoints,
secrets or hosts. Stop and ask me if the spec leaves a choice open.

# What to build

<describe the capability: what the agent should be able to do, which API or service it
talks to, and what the tools should be called>

# 1. Read the format

Read https://onkeiki.com/docs/capabilities.md in full before writing anything. It defines
the manifest, the runtimes (render-template, openapi, codemode, mcp), the `uses`
namespaces (entities, sandbox, http) and how secrets are declared. Pick the runtime that
matches my spec; prefer `codemode` with `uses: ["http"]` for wrapping an HTTP API.

# 2. Get access

- If KEIKI_API_KEY is set in the environment, use it and skip to step 3.
- Otherwise tell me to sign in at https://onkeiki.com (signups are invite-only: accept an
  invite or join the waitlist), create a key under Settings → API Keys, and export it as
  KEIKI_API_KEY. Wait for me. Do not create an account on my behalf.
- Treat the key as a secret: read it from the environment, never write it into a file
  that gets committed.

# 3. Write the manifest

Install the SDK if it is not already a dependency (`bun add @onkeiki/agents` or
`npm install @onkeiki/agents`), then write ONE manifest as a TypeScript object in this
repository, next to my agent config if there is one. Type it strictly — do not widen or
cast. Shape, for a capability that wraps an HTTP API:

    import type { CapabilityManifest } from '@onkeiki/agents'

    export const myCapabilityManifest = {
      slug: 'open-meteo-weather',
      version: '1.0.0',
      title: 'Open-Meteo weather',
      description: 'Current weather and short-range forecast for any coordinates.',
      runtime: 'codemode',
      uses: ['http'],
      http: { allow: ['api.open-meteo.com'] },
      // only when the upstream API needs a credential:
      // secrets: [{ name: 'EXAMPLE_API_KEY', required: true, description: '...' }],
      prompt:
        'When the user asks about the weather, call GET https://api.open-meteo.com/v1/forecast' +
        '?latitude=<lat>&longitude=<lon>&current_weather=true (no auth) and summarize current_weather.',
    } satisfies CapabilityManifest

Run the TypeScript compiler; a manifest that does not type-check is not done. Rules:
- `slug` is [a-z0-9-], unique to my organization; `version` is semver and starts at 1.0.0.
- List in `uses` only the namespaces the tools need, and in `http.allow` only the hosts
  they call. HTTPS only; a leading "*." matches subdomains.
- Declare every credential the capability needs in `secrets`, and reference it as
  `{{SECRET_NAME}}` in headers or bodies. The installer supplies the value. Never hard-code
  a key.
- Give every tool a precise `description` and a strict JSON Schema `inputSchema`. The
  agent that installs this only sees those two things.
- `prompt` tells the installing agent when to use the tools, and for `codemode` documents
  the API it should call. Keep it short and specific.

# 4. Publish privately and install

Add the manifest to my agent's `capabilities` array and sync with the SDK. If my
repository already has an AgentKit config, add to it rather than creating a second one;
otherwise create `publish.ts`:

    import { AgentKit } from '@onkeiki/agents'
    import { myCapabilityManifest } from './capability'

    const kit = AgentKit.create({
      apiKey: process.env.KEIKI_API_KEY!,
      name: 'My Agent',
      agent: {
        model: 'openai/gpt-4o-mini', // any OpenRouter model id
        maxSteps: 10,
        historyLimit: 40,
        systemPrompt: () => 'You are a helpful assistant.',
        tools: [],
        capabilities: [myCapabilityManifest],
      },
    })
    await kit.sync()

Run it with `bun run publish.ts` (or `npx tsx publish.ts`). `sync` validates the manifest,
publishes it under my organization (private) and installs that exact version on the agent.
If the platform rejects the manifest, fix the manifest, not the platform.

# 5. Verify and report

Success looks like:

    [agents] Syncing to platform at https://onkeiki.com
    [agents] Sync complete: agent="My Agent" id=<uuid> tools=0

A `[agents] Sync failed` warning with the platform's error is not success. Then tell me:
the slug and version, the tools added, which secrets I have to set as developer secrets
before the tools work, and the next step (submitting for review, which I do myself). Do
not submit it for review.
```

--------------------------------

### GET /deployments

Source: https://onkeiki.com/docs/partner-deployments

Retrieves the deployment object for the current deployment. Returns the same deployment object as a create, without provider credentials.

```APIDOC
## GET /deployments

### Description
Retrieves the deployment object for the current deployment. Returns the same deployment object as a create, without provider credentials.

### Method
GET

### Endpoint
/deployments

### Response
#### Success Response (200)
- **deployment** (object) - The deployment object, same as returned by a create request, without provider credentials.

#### Response Example
{
  "deployment": {
    "mcpConnections": [
      {
        "name": "string",
        "status": "connected"
      }
    ]
  }
}
```

--------------------------------

### Developer REST API curl examples

Source: https://onkeiki.com/docs/cloud-agents

Shows how to use the developer REST API with curl: list agents, read config, update the system prompt, upload a webhook tool, acquire a phone number, and check usage. All requests use the Authorization header with the API key.

```bash
# List the agents this key can act on
curl -H "Authorization: Bearer $API_KEY" https://<your-host>/api/v1/developer/agents

# Read agent config (org-wide key: add ?agent_id=<agent-id>)
curl -H "Authorization: Bearer $API_KEY" https://<your-host>/api/v1/developer/config

# Update the system prompt; other fields keep their values
curl -X PATCH -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "<agent-id>", "system_prompt": "You are..."}' \
  https://<your-host>/api/v1/developer/config

# Upload a custom tool that Keiki calls over a webhook
curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "check_weather",
    "description": "Get weather for a city",
    "inputSchema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    "executionType": "webhook",
    "webhookUrl": "https://my-app.com/api/tools/weather"
  }' \
  https://<your-host>/api/v1/developer/tools

# Acquire a phone number
curl -X POST -H "Authorization: Bearer $API_KEY" \
  -d '{"pool": "us-west", "strategy": "least-active"}' \
  https://<your-host>/api/v1/developer/phones/acquire

# Check usage
curl -H "Authorization: Bearer $API_KEY" https://<your-host>/api/v1/developer/usage
```

--------------------------------

### Define a custom plugin with definePlugin

Source: https://onkeiki.com/docs/cloud-agents

Shows how to write a plugin that satisfies the AgentKitPlugin interface using definePlugin for type safety. The example defines an 'analytics' plugin with an afterTurn hook that captures data to PostHog.

```ts
import { Effect } from 'effect'
import { definePlugin } from '@onkeiki/agents'

export const analytics = (opts: { posthogKey: string }) =>
  definePlugin({
    id: 'analytics',
    hooks: {
      afterTurn: (result) =>
        Effect.tryPromise(() =>
          posthog.capture('sms_turn', {
            phone: result.phone,
            toolCalls: result.toolCalls.length,
            tokensUsed: result.tokensUsed,
            durationMs: result.durationMs,
          })
        ),
    },
  })
```

--------------------------------

### POST /api/v1/developer/deployments

Source: https://onkeiki.com/docs/billing-agent-example

Creates or updates a deployment for an organization. One call per organization, from the organization's backend, when the organization installs the Slack app. Re-running with the same `external_ref` updates the agent in place.

```APIDOC
## POST /api/v1/developer/deployments

### Description
Creates or updates a deployment for an organization. One call per organization, from the organization's backend, when the organization installs the Slack app. Re-running with the same `external_ref` updates the agent in place.

### Method
POST

### Endpoint
/api/v1/developer/deployments

### Headers
- **Authorization** (string) - Required - Bearer token with an org-wide API key.

### Request Body
- **external_ref** (string) - Required - Unique reference for the organization.
- **agent** (object) - Required - Agent configuration with `template` and `name`.
- **channels** (array) - Required - List of channel configurations, e.g., Slack with `bot_token` and `signing_secret`.
- **identity** (object) - Required - Identity configuration with `webhook_url` and `secret`.
- **actions** (object) - Required - Actions configuration with `view_url`, `webhook_url`, and `secret`.
- **tools** (array) - Required - List of tool definitions.

### Request Example
```json
{
  "external_ref": "org_acme_customer_42",
  "agent": { "template": "leaf", "name": "Acme billing" },
  "channels": [
    { "type": "slack", "bot_token": "xoxb-…", "signing_secret": "…" }
  ],
  "identity": {
    "webhook_url": "https://api.acme.com/keiki/identity",
    "secret": "<identity signing secret>"
  },
  "actions": {
    "view_url": "https://app.acme.com/org_acme_customer_42/agent/actions/{actionId}",
    "webhook_url": "https://api.acme.com/keiki/actions",
    "secret": "<actions signing secret>"
  },
  "tools": [
    {
      "name": "preview_plan_change",
      "description": "Show what changing a customer's plan would do: proration, credit due now, next invoice. Run this before update_customer_plan, with the same arguments.",
      "executionType": "webhook",
      "webhookUrl": "https://api.acme.com/keiki/tools/preview_plan_change",
      "inputSchema": {
        "type": "object",
        "properties": {
          "customer_id": { "type": "string" },
          "plan": { "type": "string", "description": "Plan id to move the customer to" },
          "remove_plans": { "type": "array", "items": { "type": "string" } },
          "env": { "type": "string", "enum": ["live", "sandbox"] }
        },
        "required": ["customer_id", "plan", "env"]
      },
      "policy": { "requiredScopes": ["billing:read"] }
    },
    {
      "name": "update_customer_plan",
      "description": "Change a customer's plan. Requires approval; call preview_plan_change first with the same arguments.",
      "executionType": "webhook",
      "webhookUrl": "https://api.acme.com/keiki/tools/update_customer_plan",
      "inputSchema": {
        "type": "object",
        "properties": {
          "customer_id": { "type": "string" },
          "plan": { "type": "string" },
          "remove_plans": { "type": "array", "items": { "type": "string" } },
          "env": { "type": "string", "enum": ["live", "sandbox"] },
          "walkthrough": { "type": "string", "description": "One or two sentences for the approver explaining what will change and why." }
        },
        "required": ["customer_id", "plan", "env", "walkthrough"]
      },
      "policy": {
        "approval": "ask",
        "requiredScopes": ["billing:write"],
        "previewTool": "preview_plan_change",
        "freshnessFields": ["plan", "credit_due_now", "next_invoice.total", "next_invoice.date"],
        "descriptionArg": "walkthrough"
      }
    }
  ]
}
```

### Response
No response schema is documented in the source.

```

--------------------------------

### POST /runs request body

Source: https://onkeiki.com/docs/external-channel-evals

JSON body for starting an external channel run. Requires a driver and optional case IDs. Returns run details, target, cases, excluded cases, and timing parameters.

```json
{
  "run_id": "evalrun_…",
  "driver": "imessage",
  "target": { "channel": "sms", "handle": "+15550001111" },
  "cases": [
    {
      "id": "…",
      "name": "SMS: answers in one message",
      "prompt": "…",
      "history": [{ "role": "user", "content": "…" }]
    }
  ],
  "excluded": [{ "id": "…", "name": "Retries a failing tool", "reason": "mocked tools" }],
  "quiet_ms": 8000,
  "timeout_ms": 180000
}
```

--------------------------------

### Stop tunnel supervisor with KEIKI_TUNNEL_STOP=1

Source: https://onkeiki.com/docs/external-harness

Run this command with the same agent API key to stop the tunnel supervisor. It validates the setup and downloads the supervisor before stopping the previous one.

```sh
curl -fsSL https://<your-keiki-host>/api/v1/harness/tunnel.sh \
  | KEIKI_API_KEY=sk_live_… KEIKI_TUNNEL_STOP=1 sh
```

--------------------------------

### GET /api/v1/traces?status=error

Source: https://onkeiki.com/docs/partner-deployments

Lists traces with a given status. The example shows listing failed traces.

```APIDOC
## GET /api/v1/traces?status=error

### Description
Lists traces with a given status. The example shows listing failed traces.

### Method
GET

### Endpoint
/api/v1/traces

### Parameters
#### Query Parameters
- **status** (string) - Optional - Filter traces by status. Example: error.

### Response
#### Success Response (200)
- **traces** (array) - List of trace objects.

#### Response Example
{
  "traces": []
}
```

--------------------------------

### Initialize Keiki CLI

Source: https://onkeiki.com/docs/cli

Run in your application directory to initialize the Keiki external harness. Detects the framework from package.json dependencies and writes the appropriate integration files.

```sh
npx @onkeiki/cli init
```

--------------------------------

### create

Source: https://onkeiki.com/docs/sdk

Creates a Keiki agent kit instance with configuration for API key, name, number resolution, storage, and agent settings. Returns a kit object with `sync()` and `serve()` methods.

```APIDOC
## create

### Description
Creates a Keiki agent kit instance with configuration for API key, name, number resolution, storage, and agent settings. Returns a kit object with `sync()` and `serve()` methods.

### Method
create

### Endpoint
create

### Parameters
#### Request Body
- **apiKey** (string) - Required - API key for the Keiki platform.
- **name** (string) - Required - Name of the agent.
- **resolveNumber** (function) - Required - Function that resolves the phone number to use, given a context.
- **storage** (object) - Required - Storage adapter for the agent.
- **agent** (object) - Required - Agent configuration.
  - **model** (string) - Required - Model identifier.
  - **maxSteps** (number) - Required - Maximum number of steps.
  - **historyLimit** (number) - Required - History limit.
  - **systemPrompt** (function) - Required - Function that returns the system prompt.
  - **tools** (array) - Required - List of tools.

### Request Example
```ts
import { Effect } from 'effect'
import { create } from '@onkeiki/agents'
import { PostgresStorage } from '@onkeiki/agents-storage-postgres'

const kit = create({
  apiKey: process.env.KEIKI_API_KEY!,
  name: 'My Agent',
  resolveNumber: (ctx) => Effect.succeed(process.env.SMS_LINE!),
  storage: PostgresStorage({ connectionString: process.env.DATABASE_URL! }),
  agent: {
    model: 'google/gemini-3.5-flash',
    maxSteps: 10,
    historyLimit: 40,
    systemPrompt: ({ now }) => `You are a helpful assistant. Current time: ${now.toISOString()}`,
    tools: [],
  },
})
```

### Response
#### Success Response
- **kit** (object) - The kit instance with `sync()` and `serve()` methods.

#### Response Example
```ts
const kit = create({ ... })
```
```

--------------------------------

### GET /api/v1/keys

Source: https://onkeiki.com/docs/cloud-agents

Lists all API keys for the organization.

```APIDOC
## GET /api/v1/keys

### Description
Lists all API keys for the organization.

### Method
GET

### Endpoint
https://<your-host>/api/v1/keys

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token with admin or key management permissions.
- **X-Org-Id** (string) - Required - The organization ID.

### Response
#### Success Response (200)
- **keys** (array) - List of API key objects.

#### Response Example
[
  {
    "id": "key-id",
    "name": "Production Agent",
    "scopes": ["*"]
  }
]
```

--------------------------------

### Create AgentKit with plugins

Source: https://onkeiki.com/docs/cloud-agents

Shows how to create an AgentKit instance with various plugins: memory, browser, steering, media, observability, and alerts. The agent config includes model, maxSteps, historyLimit, systemPrompt, and custom tools. The kit.sync() call is required to sync the agent.

```ts
import { AgentKit } from '@onkeiki/agents'
import { memory, browser, steering, media, observability, alerts } from '@onkeiki/agents-plugins'

const kit = AgentKit.create({
  apiKey: process.env.KEIKI_API_KEY!,
  name: 'My Agent',

  plugins: [
    memory({ autoRetrieve: true }),
    browser({ handoff: true, screenshotDelivery: true }),
    steering({ debounceWindow: '2 seconds', midTurnStrategy: 'interrupt', maxBatch: 5 }),
    media({ audio: 'transcribe', image: 'describe', video: 'describe', document: 'extract' }),
    observability({ exporters: [braintrustExporter({ apiKey: '...', projectName: 'my-agent' })] }),
    alerts({ alerts: [dailyBriefing] }),
  ],

  agent: {
    model: '<model-id>',
    maxSteps: 10,
    historyLimit: 40,
    systemPrompt: () => `...`,
    tools: [myCustomTool],  // only your custom tools here
  },
})

await kit.sync()
```

--------------------------------

### GET /api/v1/evals/diffs

Source: https://onkeiki.com/docs/evals

Reads a comparison between two runs.

```APIDOC
## GET /api/v1/evals/diffs

### Description
Reads a comparison between two runs.

### Method
GET

### Endpoint
/api/v1/evals/diffs

### Parameters
#### Query Parameters
- **diff_id** (string) - Required - The ID of the comparison to read.

### Response
#### Success Response (200)
- **diff** (object) - The comparison data.

#### Response Example
{
  "diff": {}
}
```

--------------------------------

### Create and sync or serve a Keiki agent with @onkeiki/agents

Source: https://onkeiki.com/docs/sdk

Defines an agent with `create()`, configuring API key, name, resolveNumber, storage, and agent options. Then either syncs to the cloud with `kit.sync()` or runs the loop yourself with `kit.serve()` (commented out).

```ts
import { Effect } from 'effect'
import { create } from '@onkeiki/agents'
import { PostgresStorage } from '@onkeiki/agents-storage-postgres'

const kit = create({
  apiKey: process.env.KEIKI_API_KEY!,
  name: 'My Agent',
  resolveNumber: (ctx) => Effect.succeed(process.env.SMS_LINE!),
  storage: PostgresStorage({ connectionString: process.env.DATABASE_URL! }),
  agent: {
    model: 'google/gemini-3.5-flash',
    maxSteps: 10,
    historyLimit: 40,
    systemPrompt: ({ now }) => `You are a helpful assistant. Current time: ${now.toISOString()}`,
    tools: [],
  },
})

// Cloud-served: the platform runs the agentic loop.
await kit.sync()

// Self-hosted: run the loop yourself instead.
// await kit.serve({ port: 8789 })
```

--------------------------------

### AgentKitInstance.sync()

Source: https://onkeiki.com/docs/sdk

Pushes the full declarative config to the platform, including system prompt, tools, policies, model limits, harness, feature flags, loop presets, connections, capabilities, alerts, and secrets. Run on every deploy.

```APIDOC
## AgentKitInstance.sync()

### Description
Pushes the full declarative config to the platform: rendered system prompt, merged tools, tool policies, model and step/history limits, harness, feature flags, loop presets, user connections, capabilities, alerts, and developer secrets. It is the infrastructure-as-code operation; run it on every deploy.

### Method
function

### Parameters
None.

### Returns
- **Promise** - Resolves when the sync completes.
```

--------------------------------

### GET /api/v1/traces/{trace-id}

Source: https://onkeiki.com/docs/cloud-agents

Retrieves a single trace with all of its spans.

```APIDOC
## GET /api/v1/traces/{trace-id}

### Description
Retrieves a single trace with all of its spans.

### Method
GET

### Endpoint
https://<your-host>/api/v1/traces/{trace-id}

### Parameters
#### Path Parameters
- **trace-id** (string) - Required - The ID of the trace to retrieve.

### Response
#### Success Response (200)
- **id** (string) - The trace ID.
- **model** (string) - The model used.
- **tokens_in** (integer) - Number of input tokens.
- **tokens_out** (integer) - Number of output tokens.
- **steps** (integer) - Number of steps.
- **duration** (number) - Duration in seconds.
- **spans** (array) - List of spans, each with inputs, outputs, errors, and metadata.

#### Response Example
{
  "id": "trace-id",
  "model": "model-name",
  "tokens_in": 123,
  "tokens_out": 456,
  "steps": 5,
  "duration": 1.23,
  "spans": [
    {
      "type": "model",
      "input": "...",
      "output": "...",
      "error": null,
      "metadata": {}
    }
  ]
}
```

--------------------------------

### Sync config to Keiki with kit.sync()

Source: https://onkeiki.com/docs/cloud-agents

Pushes config, tools, and plugins to Keiki; Keiki runs everything. Use after configuring the agent.

```ts
await kit.sync() // push config, tools and plugins to Keiki; Keiki runs everything
```

--------------------------------

### GET /api/v1/developer/usage

Source: https://onkeiki.com/docs/cloud-agents

Checks usage for the API key or agent.

```APIDOC
## GET /api/v1/developer/usage

### Description
Checks usage for the API key or agent.

### Method
GET

### Endpoint
https://<your-host>/api/v1/developer/usage

### Authentication
Bearer token (API key)

### Request Example
```bash
curl -H "Authorization: Bearer $API_KEY" https://<your-host>/api/v1/developer/usage
```

### Response
#### Success Response (200)
- **usage** (object) - Usage details.

#### Response Example
(Not provided in source)

```

--------------------------------

### kit.serve()

Source: https://onkeiki.com/docs/sdk

Runs the agentic loop yourself, self-hosting the agent. Optionally accepts a port number for the server.

```APIDOC
## kit.serve()

### Description
Runs the agentic loop yourself, self-hosting the agent. Optionally accepts a port number for the server.

### Method
serve

### Endpoint
kit.serve()

### Parameters
#### Query Parameters
- **port** (number) - Optional - Port number for the server.

### Request Example
```ts
await kit.serve({ port: 8789 })
```

### Response
#### Success Response
No return value specified.

#### Response Example
```ts
await kit.serve({ port: 8789 })
```
```

--------------------------------

### GET /api/v1/evals/runs/:id/transcript

Source: https://onkeiki.com/docs/evals

Retrieves the turn transcript for a specific run.

```APIDOC
## GET /api/v1/evals/runs/:id/transcript

### Description
Retrieves the turn transcript for a specific run.

### Method
GET

### Endpoint
/api/v1/evals/runs/:id/transcript

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the run.

### Response
#### Success Response (200)
- **transcript** (object) - The turn transcript.

#### Response Example
{
  "transcript": {}
}
```

--------------------------------

### Create and sync an AgentKit agent

Source: https://onkeiki.com/docs/cloud-agents

Creates an AgentKit with API key, name, resolveNumber, and agent config, then syncs it. The systemPrompt uses user, now, and context. Requires KEIKI_API_KEY and SMS_LINE environment variables.

```ts
// src/index.ts
import { Effect } from 'effect'
import { AgentKit } from '@onkeiki/agents'

const kit = AgentKit.create({
  apiKey: process.env.KEIKI_API_KEY!,
  name: 'My Agent',

  resolveNumber: (ctx) => Effect.succeed(process.env.SMS_LINE!),

  agent: {
    model: '<model-id>',
    maxSteps: 10,
    historyLimit: 40,

    systemPrompt: ({ user, now, context }) => [
      `You are a helpful assistant.`,
      `Current time: ${now.toISOString()}`,
      context.memorySummary ? `\nAbout this user:\n${context.memorySummary}` : '',
    ].join('\n'),

    tools: [],
  },
})

await kit.sync()
```

--------------------------------

### GET /api/v1/evals/runs/:id/cases

Source: https://onkeiki.com/docs/evals

Retrieves per-case results for a specific run.

```APIDOC
## GET /api/v1/evals/runs/:id/cases

### Description
Retrieves per-case results for a specific run.

### Method
GET

### Endpoint
/api/v1/evals/runs/:id/cases

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the run.

### Response
#### Success Response (200)
- **cases** (array) - The per-case results.

#### Response Example
{
  "cases": []
}
```

--------------------------------

### GET /api/v1/evals/suggestions

Source: https://onkeiki.com/docs/evals

Retrieves suggested evaluation cases derived from your conversations.

```APIDOC
## GET /api/v1/evals/suggestions

### Description
Retrieves suggested evaluation cases derived from your conversations.

### Method
GET

### Endpoint
/api/v1/evals/suggestions

### Response
#### Success Response (200)
- **suggestions** (array) - The list of suggested cases.

#### Response Example
{
  "suggestions": []
}
```

--------------------------------

### Configure Keiki push dispatchUrl

Source: https://onkeiki.com/docs/eve

Configure the external harness with push connectivity and the dispatchUrl pointing to the mounted route POST /keiki/v1/dispatch. The timeoutMs is set to '10 minutes'.

```ts
const kit = AgentKit.create({
  // ...
  harness: {
    type: 'external',
    connectivity: 'push',
    dispatchUrl: 'https://your-eve-app.example/keiki/v1/dispatch',
    timeoutMs: '10 minutes',
  },
})
```

--------------------------------

### GET /api/v1/evals/cases/versions?agent_id=

Source: https://onkeiki.com/docs/evals

Retrieves the revision history of cases for a given agent.

```APIDOC
## GET /api/v1/evals/cases/versions?agent_id=

### Description
Retrieves the revision history of cases for a given agent.

### Method
GET

### Endpoint
/api/v1/evals/cases/versions?agent_id=

### Parameters
#### Query Parameters
- **agent_id** (string) - Required - The ID of the agent whose case versions are to be retrieved.

### Response
#### Success Response (200)
- **versions** (array) - The list of case revisions.

#### Response Example
{
  "versions": []
}
```

--------------------------------

### Run the agent script

Source: https://onkeiki.com/docs/cloud-agents

Runs the script and outputs a confirmation that the config was synced.

```bash
bun run src/index.ts
# Config synced to Keiki. Keiki now runs your agent.
```

--------------------------------

### GET /api/v1/traces

Source: https://onkeiki.com/docs/cloud-agents

Lists recent traces. Each trace represents a turn with nested spans.

```APIDOC
## GET /api/v1/traces

### Description
Lists recent traces. Each trace represents a turn with nested spans.

### Method
GET

### Endpoint
https://<your-host>/api/v1/traces

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of traces to return. Default is 20.

### Response
#### Success Response (200)
- **traces** (array) - List of trace objects.

#### Response Example
[
  {
    "id": "trace-id",
    "model": "model-name",
    "tokens_in": 123,
    "tokens_out": 456,
    "steps": 5,
    "duration": 1.23,
    "spans": []
  }
]
```

--------------------------------

### create(config)

Source: https://onkeiki.com/docs/sdk

Alias for AgentKit.create. Provides a shorthand way to create an agent instance.

```APIDOC
## create(config)

### Description
Alias for `AgentKit.create`.

### Method
function

### Parameters
- **config** (object) - Required - Configuration for the agent instance.

### Returns
- **AgentKitInstance** - The created agent instance.
```

--------------------------------

### GET {turnUrl}/arrivals?after=0

Source: https://onkeiki.com/docs/external-harness

Pulls up to 50 durable arrival batches after a sequence cursor.

```APIDOC
## GET {turnUrl}/arrivals?after=0

### Description
Pulls up to 50 durable arrival batches after a sequence cursor.

### Method
GET

### Endpoint
{turnUrl}/arrivals?after=0

### Parameters
#### Query Parameters
- **after** (integer) - Required - Sequence cursor to fetch arrivals after.

### Response
#### Success Response (200)
- **arrivals** (array) - List of arrival batches (up to 50).
```